Kinetune

Convierte canciones en videos de letras sincronizadas con la palabra (9:16, 16:9, 1:1) y bucles de Spotify Canvas. Sube una pista, explora Looks, obtén una cotización de crédito exacta, y luego renderiza y descarga.

Ver en kinetune.comPrueba este MCPPatrocinado

Servidor MCP alojado

npx add-mcp 'https://kinetune.com/mcp'

Se instala en Claude Code, Codex, Cursor y más

Documentación

Resumen

Un solo servidor lo aloja todo, y cada superficie ejecuta las mismas operaciones con la misma validación y los mismos precios exactos que la aplicación.

Endpoints

API REST

https://kinetune.com/api/v1

Servidor MCP

https://kinetune.com/mcp · HTTP Streamable

OpenAPI 3.1

https://kinetune.com/api/v1/openapi.json

Descubrimiento OAuth

https://kinetune.com/.well-known/oauth-authorization-server

Cómo se hace un video

Añade una canción: el audio maestro y su carátula cuadrada. Se analiza (letras, ritmos, secciones) en aproximadamente un minuto.
Cotiza el video que quieres. La cotización es el número exacto de créditos; no se cobra nada.
Créalo con la misma solicitud más el quote_id. Los créditos se retienen y solo se cobran cuando se entrega el video.
Espera a status: "completed": consulta el video o recibe un callback firmado.
Descarga los archivos: un MP4 por formato, enlaces válidos durante 7 días (vuelve a pedirlos para obtener otros nuevos).

Inicio rápido

La misma solicitud de tres maneras. Elige la que coincida con donde se ejecuta tu código o agente.

Terminal

npm install -g @kinetune/cli
kinetune auth login                       # opens the browser to sign in

kinetune artists create --name "Nova Lane"
kinetune songs create --artist-id ARTIST_ID --title "Midnight Drive" \
  --audio ./midnight-drive.wav --cover-art ./cover.jpg
kinetune songs get SONG_ID                # wait for analysis.status "ready"

kinetune create canvas --song-id SONG_ID  # quotes, shows the credits, asks first
kinetune videos wait VIDEO_ID
kinetune videos download VIDEO_ID

Autenticación

Dos tipos de credenciales, ambas enviadas como token Bearer y ambas limitadas a una organización.

Claves API — servidores, CI y n8n

Crea una en la página API de la aplicación (propietarios y administradores). El secreto se muestra una sola vez; solo almacenamos un HMAC. Las claves actúan en nombre de la organización y están limitadas por tu plan.

Encabezado

Authorization: Bearer kt_live_YOUR_KEY

Ámbitos

videos:read

Ver videos, cotizaciones y tu saldo de créditos

videos:write

Cotizar, crear, cancelar, reintentar y eliminar videos (gasta créditos)

music:read

Ver artistas, sus fotos y canciones

music:write

Añadir, renombrar y archivar artistas y canciones, subir canciones y fotos de artistas

library:read

Explorar Looks

library:write

Renombrar, eliminar y publicar tus Looks

Endpoints OAuth

Servidor de autorización

https://kinetune.com/.well-known/oauth-authorization-server

Recurso MCP

https://kinetune.com/mcp · metadatos en /.well-known/oauth-protected-resource/mcp

Recurso REST

https://kinetune.com/api/v1 · metadatos en /.well-known/oauth-protected-resource/api/v1

Autorizar · token

/api/auth/oauth2/authorize · /api/auth/oauth2/token

Envía resource (RFC 8707) con la URL MCP o REST para que la audiencia del token coincida; las llamadas no autenticadas responden 401 con un encabezado WWW-Authenticate que apunta a los metadatos del recurso.

Servidor MCP

Los agentes remotos usan Kinetune a través del Protocolo de Contexto de Modelo: una herramienta por operación de API, HTTP Streamable, inicio de sesión con tu cuenta.

URL del servidor

https://kinetune.com/mcp

También aparece en el Registro MCP oficial (com.kinetune/kinetune), en Smithery, Glama y Cursor Directory.

En ChatGPT, abre Configuración → Aplicaciones y conectores → Avanzado y activa Modo desarrollador (depende de tu plan y la configuración del espacio de trabajo).
Elige Crear, nómbralo Kinetune, pega la URL del servidor y selecciona OAuth.
Inicia sesión, elige la organización y aprueba. Luego actívalo en un chat desde el menú de herramientas.

Herramientas

El servidor no tiene estado (respuestas JSON, protocolo 2025-11-25). Las herramientas que crean videos gastan créditos, por lo que se instruye a los agentes a cotizar primero y preguntar. wait_for_video espera hasta 55 segundos por llamada.

Herramienta	Qué hace
get_account	Con quién has iniciado sesión, la organización y su saldo de créditos
get_options	Tipos de video, categorías de Look, fuentes de fondo, formatos y los precios de créditos actuales
list_artists	Artistas por nombre, con sus recuentos de canciones y fotos y una imagen
create_artist	Añadir un artista por nombre
get_artist	Un artista
rename_artist	Cambiar el nombre de un artista
archive_artist destructivo	Eliminar un artista que no tiene canciones
set_artist_picture	Elegir qué foto es la imagen del artista y cómo se recorta a un cuadrado
list_artist_photos	Las fotos del artista (referencias de identidad, hasta 6)
add_artist_photos	Subir una o más fotos del artista (JPEG, PNG o WebP)
delete_artist_photo destructivo	Eliminar una foto
list_songs	Canciones con su carátula, duración y estado de análisis
create_song	Añadir una canción: audio maestro y carátula cuadrada
get_song	Una canción y su estado de análisis
rename_song	Cambiar el título de una canción
archive_song destructivo	Eliminar una canción (sus videos permanecen)
get_song_analysis	Letras sincronizadas por palabra, tempo, ritmos, secciones y estribillo
reanalyze_song	Reintentar un análisis fallido
list_looks	Explorar Looks Oficiales, de la Comunidad y propios
get_look	Un Look con su diseño e imágenes de vista previa
rename_look	Renombrar uno de tus Looks
delete_look destructivo	Eliminar uno de tus Looks (los videos hechos con él permanecen)
set_look_visibility	Hacer público uno de tus Looks (gana 10 créditos) o privado
upload_background	Subir tu propia foto o video para diseñar un Nuevo Look alrededor
search_stock	Buscar fotos o clips de Pexels para usar como fondo de stock
quote_lyric_video	Los créditos exactos para un video de letras, antes de cobrar nada
quote_canvas	Los créditos exactos para un Spotify Canvas, antes de cobrar nada
create_lyric_video	Crear el video de letras al precio de la cotización (gasta créditos)
create_canvas	Crear el Canvas al precio de la cotización (gasta créditos)
list_videos	Videos, del más reciente al más antiguo, con estado y miniaturas
get_video	Estado, progreso, créditos y, cuando se completa, los enlaces de descarga
cancel_video destructivo	Detener un video en cola o en procesamiento (los créditos se liberan)
retry_video	Ejecutar de nuevo un video terminado, fallido o cancelado (nuevo cargo)
delete_video destructivo	Eliminar un video terminado y sus archivos
wait_for_video	Espera a que un video termine (hasta 55 s por llamada) y luego lo devuelve como get_video

Prompts y recursos

Los clientes que muestran prompts como comandos obtienen tres inicios listos: make_lyric_video, make_canvas y browse_looks. Cada uno sigue el flujo de trabajo de cotizar primero.

Los recursos de solo lectura reflejan las lecturas de la API: kinetune://account y kinetune://options, más plantillas para kinetune://songs/{song_id}, …/analysis, kinetune://looks/{look_id}, kinetune://videos/{video_id} y kinetune://artists/{artist_id}, todas devueltas como JSON.

CLI

kinetune ejecuta cada operación desde la terminal. Imprime JSON siempre que su salida se canaliza, por lo que los agentes y scripts locales lo leen directamente.

Instalación (Node 20+)

npm install -g @kinetune/cli
# or without installing:
npx @kinetune/cli --help

Iniciar sesión

kinetune auth login                            # browser sign-in, picks the organization
kinetune auth login --api-key kt_live_YOUR_KEY  # or store an API key
kinetune auth status

Cómo trabajar con él

Los comandos siguen la API: kinetune songs list --q "tide" --limit 20, kinetune looks get LOOK_ID, kinetune quote lyric-video --song-id SONG_ID. Los ids de ruta son argumentos, los campos son banderas, y --input file.json (o - para stdin) toma la solicitud completa. Los archivos se suben por ruta o URL https: --audio ./song.wav.

kinetune create … siempre cotiza primero y pregunta antes de cobrar; pasa --yes o un límite con --max-credits 120 en scripts. kinetune videos wait y kinetune videos download completan el trabajo.

Dale a un agente local (Codex, Cursor, opencode, Claude Code…) la habilidad de Kinetune para que conozca el flujo de trabajo: npx skills add kinetune/skills. Es de código abierto en kinetune/skills.

Para agentes

kinetune schema create canvas   # JSON Schema of a command's input
kinetune openapi                 # the whole API as OpenAPI 3.1
kinetune songs list --json       # JSON even in a terminal

Entorno y códigos de salida

KINETUNE_API_KEY

Una clave API de organización; gana sobre el inicio de sesión almacenado (CI, servidores).

KINETUNE_URL

Otra implementación de la aplicación (por defecto este sitio).

KINETUNE_CONFIG_DIR

Dónde viven las credenciales; por defecto ~/.config/kinetune (modo 600).

Códigos de salida

0 hecho · 1 error de API o red · 2 uso inválido o más de --max-credits · 3 no has iniciado sesión o no tienes permiso

API REST

JSON sobre HTTPS. Cada solicitud lleva una credencial Bearer; los ids son cadenas con prefijo; las horas son ISO 8601.

Conceptos básicos

URL base

https://kinetune.com/api/v1

Autenticación

Authorization: Bearer … — una clave API o un token de acceso OAuth

Subidas

multipart/form-data archivos, o JSON con URLs https públicas (audio_url, cover_art_url, photo_urls, file_url)

Tu propio fondo

POST /backgrounds toma tu foto o video; un Nuevo Look con background.source upload-photo o upload-video y su upload_id se diseña alrededor, sin costo de medios. Tal Look permanece privado.

Stock que elijas

GET /stock?kind=photo&q=…&orientation=portrait busca en Pexels (24 por página; landscape cuando 16:9 está entre los formatos, seconds para un clip de Canvas). Una fuente de stock con look.background.stock_id (o el stock_id de un Canvas) usa ese elemento en lugar de la elección del director, lo que elimina la elección de la cotización. Acredita al fotógrafo dondequiera que muestres un elemento.

Cotizaciones

Válidas por tiempo limitado y una sola vez; crea con la solicitud idéntica más quote_id. Reenviar la misma cotización devuelve los videos que ya hizo.

Enlaces de descarga

Firmados, válidos 7 días; GET /videos/{id} devuelve otros nuevos

Imágenes

Se mantienen en los tamaños en que se usan, no como se subieron: el cover_art.url de una canción (1536 px JPEG), preview_url (640 px) y thumbnail_url (160 px WebP); el url de una foto de artista (1536 px) y thumbnail_url; el backgrounds.previews de un Look (480 px de ancho). Los enlaces de imágenes están firmados por 7 días y permanecen iguales todo el día, por lo que se almacenan en caché bien.

Estilos de letras

Un Nuevo Look toma look.lyric_style: cómo se presentan y animan las letras (block-stack, punch, player, neon, terminal …). GET /options los lista; déjalo fuera y el director elige uno. Un Look Existente también lo toma, para renderizar el mismo diseño en otro estilo sin costo adicional. GET /looks?lyric_style= filtra la Biblioteca.

Escenas

Un fondo de imagen AI puede tener 2–4 tomas del mismo mundo que cortan en las secciones de la canción: look.background.scenes (1 por defecto). Cada escena se cotiza como la primera.

Cotiza un video de letras con un Nuevo Look en un estilo de letras

curl -s https://kinetune.com/api/v1/quotes -H "Authorization: Bearer $KINETUNE_API_KEY" \
  -H "content-type: application/json" -d '{
    "type": "lyric-video", "song_id": "SONG_ID", "aspect_ratios": ["9:16", "16:9"],
    "look": { "mode": "new", "category": "street", "lyric_style": "punch" }
  }'

Subir archivos (multipart)

curl -s https://kinetune.com/api/v1/songs -H "Authorization: Bearer $KINETUNE_API_KEY" \
  -F artist_id=ARTIST_ID -F title="Midnight Drive" \
  -F [email protected] -F [email protected]

Callbacks

Pasa callback_url (https, público) con la cotización y la llamada de creación, y el video se te envía por POST cuando se completa, falla o se cancela.

Entrega

Cuerpo

El video, exactamente como lo devuelve GET /videos/{id}

Encabezados

Kinetune-Event (video.completed, video.failed, video.cancelled) · Kinetune-Delivery (id único) · Kinetune-Signature

Reintentos

Cualquier 2xx dentro de 10 segundos cuenta. De lo contrario, reintenta después de 30 s, 2 min, 10 min, 30 min y 2 h.

Secreto de firma

En la página API de la aplicación (whsec_…); rótalo allí.

Verificar Kinetune-Signature (Node)

import { createHmac, timingSafeEqual } from "node:crypto";

// header: "t=1760000000,v1=5f2c…"  body: the raw request body
export function verified(header, body, secret) {
  const { t, v1 } = Object.fromEntries(header.split(",").map(p => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // replay window
  const expected = createHmac("sha256", secret).update(\`${t}.${body}\`).digest("hex");
  return v1?.length === expected.length && timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}

Errores y límites

Los errores son JSON: {"error": "…"} más detalles cuando es útil (errores de campo, créditos requeridos y disponibles).

Códigos de estado

400

Solicitud inválida; details.fieldErrors nombra los campos.

401

Credenciales faltantes, inválidas o expiradas (los clientes OAuth actualizan y reintentan).

402

Créditos insuficientes: required y available te dicen cuántos.

403

Las credenciales carecen del ámbito, o la acción está reservada a la aplicación.

404

No encontrado en esta organización.

409

Un conflicto de estado: la canción aún se está analizando, o la cotización expiró, se usó o ya no coincide.

Los renders concurrentes están limitados por tu plan; los videos adicionales esperan en la cola.

n8n

El nodo de la comunidad cubre las mismas operaciones: canciones, artistas y fotos, Looks, cotizaciones, videos y descargas.

En un n8n autoalojado, abre Configuración → Nodos de la comunidad → Instalar e introduce @kinetune/n8n-nodes-kinetune.
Crea una credencial de API de Kinetune con una clave de API de la aplicación; la URL base es https://kinetune.com.
Elige artistas y canciones de una lista buscable, o cambia el campo a Por ID para un id o una expresión. Listar artistas y Listar canciones buscan y paginan como la API.
Crea una cotización y luego crea con el id de la cotización. Para continuar cuando el video esté listo, establece su URL de callback a un nodo Webhook de n8n.

Referencia de la API

Cada operación con su llamada REST, comando CLI y herramienta MCP. Generado a partir de las mismas definiciones con las que la API valida.

Cuenta

Obtener la cuenta

GET /api/v1/account

Quién eres al iniciar sesión, la organización y su saldo de créditos. Devuelve la organización para la que actúan las credenciales, cómo se autentican y sus alcances, y el saldo de créditos (disponible, mensual, recargas). Verifícalo antes de crear videos.

CLI kinetune account MCP get_account Alcances videos:read or music:read or library:read

Sin parámetros.

Listar las opciones

GET /api/v1/options

Tipos de video, categorías de Look, fuentes de fondo, formatos y los precios de crédito actuales. Todo lo que una solicitud puede elegir, con la tabla de créditos. Úsalo para elegir una categoría o fuente y para explicar los precios.

CLI kinetune options MCP get_options Alcances videos:read or music:read or library:read

Sin parámetros.

Artistas y fotos

Listar artistas

GET /api/v1/artists

Artistas por nombre, con sus conteos de canciones y fotos, y una imagen. Las canciones pertenecen a un artista; crea primero al artista. Ordenados por nombre, 50 por página por defecto: pasa q para buscar por nombre, y limit/offset para paginar.

CLI kinetune artists list MCP list_artists Alcances music:read or videos:read

Campo	Tipo	Descripción
`q` consulta	string	Parte del nombre del artista
`limit` consulta	integer 1–100	Resultados por página, 1-100 (por defecto 50)
`offset` consulta	integer 0–9007199254740991	Cuántos resultados omitir

Crear un artista

POST /api/v1/artists

Añade un artista por nombre. Los nombres son únicos por organización (409 cuando ya está tomado).

CLI kinetune artists create MCP create_artist Alcances music:write or videos:write

Campo	Tipo	Descripción
`name` cuerpo · requerido	string	El nombre del artista

Obtener un artista

GET /api/v1/artists/{artist_id}

Un artista.

CLI kinetune artists get MCP get_artist Alcances music:read or videos:read

Campo	Tipo	Descripción
`artist_id` ruta · requerido	string	El id del artista

Renombrar un artista

PATCH /api/v1/artists/{artist_id}

Cambia el nombre de un artista.

CLI kinetune artists rename MCP rename_artist Alcances music:write or videos:write

Campo	Tipo	Descripción
`artist_id` ruta · requerido	string	El id del artista
`name` cuerpo · requerido	string	El nuevo nombre

Archivar un artista

DELETE /api/v1/artists/{artist_id}

Elimina un artista que no tenga canciones. Se rechaza (409) mientras el artista aún tenga canciones.

CLI kinetune artists archive MCP archive_artist Alcances music:write or videos:write

Campo	Tipo	Descripción
`artist_id` ruta · requerido	string	El id del artista

Establecer la imagen del artista

POST /api/v1/artists/{artist_id}/picture

Elige qué foto es la imagen del artista y cómo se recorta a un cuadrado. La imagen (image_url en el artista, un cuadrado de 512 px) se corta de una de las fotos del artista; la foto en sí no cambia. La primera foto se convierte en la imagen automáticamente, centrada. crop está en fracciones de la foto (su url): x/y es la esquina superior izquierda, size es el lado relativo al lado corto de la foto; déjalo vacío para centrar.

CLI kinetune artists picture MCP set_artist_picture Alcances music:write or videos:write

Campo	Tipo	Descripción
`artist_id` ruta · requerido	string	El id del artista
`photo_id` cuerpo · requerido	string	Una de las fotos del artista (list_artist_photos)
`crop` cuerpo	object	El cuadrado a mantener, en fracciones de la foto; centrado cuando se omite

Listar fotos del artista

GET /api/v1/artists/{artist_id}/photos

Las fotos del artista (referencias de identidad, hasta 6). Las fotos mantienen reconocible al artista cuando un Look o Canvas las muestra; la portada sigue siendo la fuente creativa. url es la foto vertical a hasta 1536 px (lo que recibe la IA; width y height la describen), thumbnail_url una copia de 320 px en su lado corto para cuadrículas.

CLI kinetune artists photos list MCP list_artist_photos Alcances music:read or videos:read

Campo	Tipo	Descripción
`artist_id` ruta · requerido	string	El id del artista

Añadir fotos del artista

POST /api/v1/artists/{artist_id}/photos

Sube una o más fotos del artista (JPEG, PNG o WebP). Hasta 6 por artista, al menos 512 px en el lado corto, hasta 15 MB cada una. Solo con los derechos para usarlas (rights_confirmed). Son solo referencias de identidad: nunca se muestran públicamente ni se usan tal cual. Cada una se mantiene vertical a hasta 1536 px, con una miniatura pequeña; el archivo subido en sí no se conserva.

CLI kinetune artists photos add MCP add_artist_photos Alcances music:write or videos:write

Archivos: photos (multipart) o photo_urls (JSON).

Campo	Tipo	Descripción
`artist_id` ruta · requerido	string	El id del artista
`photo_urls` cuerpo	URL[] (1–6)	URLs https públicas de las fotos (o sube archivos con la CLI)
`rights_confirmed` cuerpo · requerido	true	Tienes los derechos para usar estas fotos del artista

Eliminar una foto del artista

DELETE /api/v1/artists/{artist_id}/photos/{photo_id}

Elimina una foto.

CLI kinetune artists photos delete MCP delete_artist_photo Alcances music:write or videos:write

Campo	Tipo	Descripción
`artist_id` ruta · requerido	string	El id del artista
`photo_id` ruta · requerido	string	El id de la foto

Canciones

Listar canciones

GET /api/v1/songs

Canciones con su portada, duración y estado de análisis. Una canción debe estar analizada (analysis.status "ready") antes de poder crear videos. 50 por página por defecto: pasa q para buscar, y limit/offset para paginar. cover_art.url es la portada a hasta 1536 px (JPEG; width y height la describen), preview_url un WebP de 640 px y thumbnail_url uno de 160 px. Los enlaces de imagen están firmados por 7 días y permanecen iguales todo el día, por lo que se pueden almacenar en caché.

CLI kinetune songs list MCP list_songs Alcances music:read or videos:read

Campo	Tipo	Descripción
`artist_id` consulta	string	Solo las canciones de este artista
`q` consulta	string	Parte del título de la canción o nombre del artista
`limit` consulta	integer 1–100	Resultados por página, 1-100 (por defecto 50)
`offset` consulta	integer 0–9007199254740991	Cuántos resultados omitir
`status` consulta	"pending" \| "processing" \| "ready" \| "failed"	Solo canciones cuyo análisis tenga este estado (ready = usable para videos)
`sort` consulta	"title" \| "newest"	title (por defecto): por artista y luego título; newest: subidas más recientes primero

Subir una canción

POST /api/v1/songs

Añade una canción: audio maestro y portada cuadrada. Audio: MP3, WAV o M4A hasta 250 MB. Portada: un JPEG o PNG cuadrado, de 1000–6000 px (3000×3000 recomendado), hasta 20 MB; se conserva a 1536, 640 y 160 px, no como se subió. La canción se analiza a continuación (letras, ritmos, secciones): consulta get_song hasta que analysis.status sea "ready", normalmente alrededor de un minuto.

CLI kinetune songs create MCP create_song Alcances music:write or videos:write

Archivos: audio (multipart) o audio_url (JSON), cover_art (multipart) o cover_art_url (JSON).

Campo	Tipo	Descripción
`artist_id` cuerpo · requerido	string	El id del artista
`title` cuerpo · requerido	string	El título de la canción
`language` cuerpo	string	Idioma de la letra (ISO 639-1, p. ej. "en"); se detecta cuando se omite
`audio_url` cuerpo	URL	Una URL https pública del audio maestro
`cover_art_url` cuerpo	URL	Una URL https pública de la portada cuadrada

Obtener una canción

GET /api/v1/songs/{song_id}

Una canción y su estado de análisis. cover_art.url es la portada a hasta 1536 px (JPEG; width y height la describen), preview_url un WebP de 640 px y thumbnail_url uno de 160 px. Los enlaces de imagen están firmados por 7 días y permanecen iguales todo el día, por lo que se pueden almacenar en caché.

CLI kinetune songs get MCP get_song Alcances music:read or videos:read

Campo	Tipo	Descripción
`song_id` ruta · requerido	string	El id de la canción

Renombrar una canción

PATCH /api/v1/songs/{song_id}

Cambia el título de una canción.

CLI kinetune songs rename MCP rename_song Alcances music:write or videos:write

Campo	Tipo	Descripción
`song_id` ruta · requerido	string	El id de la canción
`title` cuerpo · requerido	string	El nuevo título

Archivar una canción

DELETE /api/v1/songs/{song_id}

Elimina una canción (sus videos permanecen).

CLI kinetune songs archive MCP archive_song Alcances music:write or videos:write

Campo	Tipo	Descripción
`song_id` ruta · requerido	string	El id de la canción

Obtener el análisis de una canción

GET /api/v1/songs/{song_id}/analysis

Letras sincronizadas por palabra, tempo, ritmos, secciones y estribillo. Usa los tiempos de las secciones para elegir un recorte para un video de letras.

CLI kinetune songs analysis MCP get_song_analysis Alcances music:read or videos:read

Campo	Tipo	Descripción
`song_id` ruta · requerido	string	El id de la canción

Analizar una canción de nuevo

POST /api/v1/songs/{song_id}/analysis

Reintenta un análisis fallido.

CLI kinetune songs reanalyze MCP reanalyze_song Alcances music:write or videos:write

Campo	Tipo	Descripción
`song_id` ruta · requerido	string	El id de la canción

Looks

Listar Looks

GET /api/v1/looks

Explora Looks Oficiales, de la Comunidad y propios. Un Look es un diseño completo y reutilizable de video de letras. Pasa su id como {"mode":"existing","id":…} para reutilizarlo exactamente. Un Look que muestra a un artista (featured_artist) es privado y solo sirve a las canciones de ese artista: al elegir para una canción, pasa su artist_id para omitir Looks que muestren a otro artista.

CLI kinetune looks list MCP list_looks Alcances library:read or videos:read

Campo	Tipo	Descripción
`scope` consulta	"all" \| "official" \| "community" \| "mine"	Qué biblioteca; por defecto all
`category` consulta	string	Un id de categoría de get_options
`lyric_style` consulta	string	Un id de estilo de letra de get_options (cómo se mueven las letras)
`artist_id` consulta	string	El artista de la canción para la que eliges: los Looks que muestran a otro artista se omiten
`q` consulta	string	Palabras de búsqueda
`sort` consulta	"newest" \| "popular"	—
`limit` consulta	integer 1–100	—
`offset` consulta	integer 0–9007199254740991	—

Obtener un Look

GET /api/v1/looks/{look_id}

Un Look con su diseño e imágenes de vista previa. backgrounds.portrait y backgrounds.landscape son las placas de fondo que usa el video; backgrounds.previews tiene copias de 480 px de ancho para miniaturas (null para un Look sin fondo de foto o video).

CLI kinetune looks get MCP get_look Alcances library:read or videos:read

Campo	Tipo	Descripción
`look_id` ruta · requerido	string	El id del Look

Renombrar un Look

PATCH /api/v1/looks/{look_id}

Renombra uno de tus Looks.

CLI kinetune looks rename MCP rename_look Alcances library:write or videos:write

Campo	Tipo	Descripción
`look_id` ruta · requerido	string	El id del Look
`name` cuerpo · requerido	string	El nuevo nombre

Eliminar un Look

DELETE /api/v1/looks/{look_id}

Elimina uno de tus Looks (los videos hechos con él permanecen).

CLI kinetune looks delete MCP delete_look Alcances library:write or videos:write

Campo	Tipo	Descripción
`look_id` ruta · requerido	string	El id del Look

Publicar o despublicar un Look

POST /api/v1/looks/{look_id}/visibility Haz que uno de tus Looks sea público (gana 10 créditos) o privado. Los Looks públicos se unen a la biblioteca de la Comunidad bajo tu @username. Un Look que muestra a tu artista permanece privado (409).

CLI kinetune looks visibility MCP set_look_visibility Scopes library:write or videos:write

Campo	Tipo	Descripción
`look_id` path · obligatorio	string	El id del Look
`visibility` body · obligatorio	"public" \| "private"	—

Subir un fondo

POST /api/v1/backgrounds

Sube tu propia foto o video para diseñar un Nuevo Look alrededor. Foto: JPEG, PNG o WebP, al menos 720 px en el lado corto, hasta 25 MB. Video: MP4, MOV o WebM, de 4 a 180 segundos, al menos 720 px en el lado corto, hasta 300 MB; se convierte en un bucle sin costuras de hasta 20 s. Solo con los derechos para usarlo. Luego cotiza un video de letra con look {"mode":"new","category":"…","background":{"source":"upload-photo" o "upload-video","upload_id":"…"},"visibility":"private"}.

CLI kinetune backgrounds upload MCP upload_background Scopes library:write or videos:write

Archivos: file (multipart) o file_url (JSON).

Campo	Tipo	Descripción
`file_url` body	URL	Una URL https pública de la foto o el video
`rights_confirmed` body · obligatorio	true	Tienes los derechos para usar esta foto o video

Citas y videos

Cotizar un video de letra

POST /api/v1/quotes body {"type":"lyric-video"}

Los créditos exactos para un video de letra, antes de que se cobre nada. Devuelve quote_id, credits (total), credits_per_video y un desglose. Siempre cotiza primero y dile al usuario los créditos antes de crear; los créditos se reservan al crear y se cobran solo cuando se entrega el video. Una cita es válida durante 30 minutos.

CLI kinetune quote lyric-video MCP quote_lyric_video Scopes videos:write or videos:read

Campo	Tipo	Descripción
`song_id` body · obligatorio	string	El id de la canción
`variations` body	integer 1–4	1–4 Nuevos Looks diferentes, un video cada uno (un Look Existente renderiza uno) Predeterminado `1`.
`callback_url` body	string	Una URL https para enviar el video terminado (firmada; ver Callbacks). Cotiza y crea con el mismo valor
`metadata` body	object	Tu propio JSON (un id de pedido, por ejemplo): se guarda con el video y se devuelve en su solicitud. Cotiza y crea con el mismo valor
`look` body · obligatorio	object	{"mode":"existing","id":"look_…"} para reutilizar un Look guardado (añade "lyric_style" para renderizarlo en otro estilo de letra, sin costo adicional), o {"mode":"new","category":"…","lyric_style":"…","background":{"source":"ai-image","quality":"high"},"visibility":"private","direction":"…"} para que se diseñe uno (background.source "upload-photo"/"upload-video" con background.upload_id de upload_background lo diseña alrededor de tu propio material; tal Look permanece privado. "stock-photo"/"stock-video" con background.stock_id de search_stock usa ese elemento de Pexels en lugar de la elección del director). lyric_style (opcional, de get_options) establece cómo se presentan y animan las letras: block-stack, punch, player, neon, terminal, cinematic… Omítelo y el director elige uno. background.scenes (2–4, solo imagen AI) hace esa cantidad de tomas del mismo mundo que cortan en las secciones de la canción, cada una con el mismo precio que la primera. El cantante se omite a menos que se pida: feature_artist "always" (predeterminado "never") lo convierte en el sujeto del fondo, reconocible por sus fotos de artista (add_artist_photos); necesita un fondo de imagen AI o video AI, un Look privado y display.cover false (la portada lo ocultaría), y ese Look entonces solo sirve las canciones de este artista. Un Look guardado que muestra a un artista (featured_artist) solo sirve las canciones de ese artista, también con display.cover false
`aspect_ratios` body	"9:16" \| "16:9" \| "1:1"[] (1–3)	Formatos para renderizar, cada uno su propio archivo: "9:16" (vertical), "16:9" (ancho), "1:1" (cuadrado) Predeterminado `["9:16"]`.
`display` body	object	Qué elementos se muestran (title, artist, cover, lyrics, badges, headline) y sus tamaños. cover debe ser false para mostrar al artista en el fondo Predeterminado `{"title":true,"artist":true,"cover":true,"lyrics":true,"badges":true}`.
`trim` body	object	Renderiza solo esta sección de la canción (al menos 8 segundos)

Cotizar un Canvas

POST /api/v1/quotes body {"type":"canvas"}

Los créditos exactos para un Canvas de Spotify, antes de que se cobre nada. Devuelve quote_id, credits y un desglose. Siempre cotiza primero y dile al usuario los créditos antes de crear; los créditos se reservan al crear y se cobran solo cuando se entrega el video.

CLI kinetune quote canvas MCP quote_canvas Scopes videos:write or videos:read

Campo	Tipo	Descripción
`song_id` body · obligatorio	string	El id de la canción
`variations` body	integer 1–4	1–4 Canvases diferentes Predeterminado `1`.
`callback_url` body	string	Una URL https para enviar el video terminado (firmada; ver Callbacks). Cotiza y crea con el mismo valor
`metadata` body	object	Tu propio JSON (un id de pedido, por ejemplo): se guarda con el video y se devuelve en su solicitud. Cotiza y crea con el mismo valor
`source` body	"ai-video" \| "ai-image" \| "stock-photo" \| "stock-video"	ai-video (predeterminado), ai-image, stock-photo o stock-video Predeterminado `"ai-video"`.
`quality` body	"standard" \| "high"	Nivel del modelo de video AI: standard o high Predeterminado `"standard"`.
`resolution` body	"720p" \| "1080p"	1080p (1080×1920) o 720p Predeterminado `"1080p"`.
`style` body	"cinematic" \| "dreamy" \| "abstract" \| "surreal" \| "retro" \| "minimal" \| "dark" \| "vibrant" \| "nature" \| "urban"	Estilo visual opcional
`direction` body	string	Estado de ánimo, motivos o referencias opcionales; el concepto aún proviene de la portada
`feature_artist` body	"auto" \| "always" \| "never"	Si el Canvas muestra al artista: auto (el director decide), always o never (fuentes AI; necesita fotos de artista para "always") Predeterminado `"auto"`.
`seconds` body	integer 5–8	Duración del Canvas en segundos completos, 5–8 (predeterminado 8). Spotify lo repite, así que no se elige ninguna parte de la canción Predeterminado `8`.
`stock_id` body	string	Con una fuente de stock: la foto o video de Pexels (search_stock con seconds) para usar en lugar de la elección del director

Crear un video de letra

POST /api/v1/videos body {"type":"lyric-video"}

Haz el video de letra con el precio de la cita (gasta créditos). Envía la misma solicitud que la cita más su quote_id. Devuelve los ids de video de inmediato; consulta get_video hasta que el estado sea completed (o failed). Cada video tiene un archivo por formato.

CLI kinetune create lyric-video MCP create_lyric_video Scopes videos:write

Campo	Tipo	Descripción
`song_id` body · obligatorio	string	El id de la canción
`variations` body	integer 1–4	1–4 Nuevos Looks diferentes, un video cada uno (un Look Existente renderiza uno) Predeterminado `1`.
`callback_url` body	string	Una URL https para enviar el video terminado (firmada; ver Callbacks). Cotiza y crea con el mismo valor
`metadata` body	object	Tu propio JSON (un id de pedido, por ejemplo): se guarda con el video y se devuelve en su solicitud. Cotiza y crea con el mismo valor
`look` body · obligatorio	object	{"mode":"existing","id":"look_…"} para reutilizar un Look guardado (añade "lyric_style" para renderizarlo en otro estilo de letra, sin costo adicional), o {"mode":"new","category":"…","lyric_style":"…","background":{"source":"ai-image","quality":"high"},"visibility":"private","direction":"…"} para que se diseñe uno (background.source "upload-photo"/"upload-video" con background.upload_id de upload_background lo diseña alrededor de tu propio material; tal Look permanece privado. "stock-photo"/"stock-video" con background.stock_id de search_stock usa ese elemento de Pexels en lugar de la elección del director). lyric_style (opcional, de get_options) establece cómo se presentan y animan las letras: block-stack, punch, player, neon, terminal, cinematic… Omítelo y el director elige uno. background.scenes (2–4, solo imagen AI) hace esa cantidad de tomas del mismo mundo que cortan en las secciones de la canción, cada una con el mismo precio que la primera. El cantante se omite a menos que se pida: feature_artist "always" (predeterminado "never") lo convierte en el sujeto del fondo, reconocible por sus fotos de artista (add_artist_photos); necesita un fondo de imagen AI o video AI, un Look privado y display.cover false (la portada lo ocultaría), y ese Look entonces solo sirve las canciones de este artista. Un Look guardado que muestra a un artista (featured_artist) solo sirve las canciones de ese artista, también con display.cover false
`aspect_ratios` body	"9:16" \| "16:9" \| "1:1"[] (1–3)	Formatos para renderizar, cada uno su propio archivo: "9:16" (vertical), "16:9" (ancho), "1:1" (cuadrado) Predeterminado `["9:16"]`.
`display` body	object	Qué elementos se muestran (title, artist, cover, lyrics, badges, headline) y sus tamaños. cover debe ser false para mostrar al artista en el fondo Predeterminado `{"title":true,"artist":true,"cover":true,"lyrics":true,"badges":true}`.
`trim` body	object	Renderiza solo esta sección de la canción (al menos 8 segundos)
`quote_id` body · obligatorio	uuid	El quote_id de la cita correspondiente: la solicitud debe ser idéntica

Crear un Canvas

POST /api/v1/videos body {"type":"canvas"}

Haz el Canvas con el precio de la cita (gasta créditos). Envía la misma solicitud que la cita más su quote_id. Devuelve los ids de video de inmediato; consulta get_video hasta que el estado sea completed. Sube el archivo en Spotify for Artists.

CLI kinetune create canvas MCP create_canvas Scopes videos:write

Campo	Tipo	Descripción
`song_id` body · obligatorio	string	El id de la canción
`variations` body	integer 1–4	1–4 Canvases diferentes Predeterminado `1`.
`callback_url` body	string	Una URL https para enviar el video terminado (firmada; ver Callbacks). Cotiza y crea con el mismo valor
`metadata` body	object	Tu propio JSON (un id de pedido, por ejemplo): se guarda con el video y se devuelve en su solicitud. Cotiza y crea con el mismo valor
`source` body	"ai-video" \| "ai-image" \| "stock-photo" \| "stock-video"	ai-video (predeterminado), ai-image, stock-photo o stock-video Predeterminado `"ai-video"`.
`quality` body	"standard" \| "high"	Nivel del modelo de video AI: standard o high Predeterminado `"standard"`.
`resolution` body	"720p" \| "1080p"	1080p (1080×1920) o 720p Predeterminado `"1080p"`.
`style` body	"cinematic" \| "dreamy" \| "abstract" \| "surreal" \| "retro" \| "minimal" \| "dark" \| "vibrant" \| "nature" \| "urban"	Estilo visual opcional
`direction` body	string	Estado de ánimo, motivos o referencias opcionales; el concepto aún proviene de la portada
`feature_artist` body	"auto" \| "always" \| "never"	Si el Canvas muestra al artista: auto (el director decide), always o never (fuentes AI; necesita fotos de artista para "always") Predeterminado `"auto"`.
`seconds` body	integer 5–8	Duración del Canvas en segundos completos, 5–8 (predeterminado 8). Spotify lo repite, así que no se elige ninguna parte de la canción Predeterminado `8`.
`stock_id` body	string	Con una fuente de stock: la foto o video de Pexels (search_stock con seconds) para usar en lugar de la elección del director
`quote_id` body · obligatorio	uuid	El quote_id de la cita correspondiente: la solicitud debe ser idéntica

Listar videos

GET /api/v1/videos

Videos, los más recientes primero, con estado y miniaturas.

CLI kinetune videos list MCP list_videos Scopes videos:read

Campo	Tipo	Descripción
`song_id` query	string	Solo los videos de esta canción
`type` query	"lyric-video" \| "canvas"	—
`limit` query	integer 1–100	—

Obtener un video

GET /api/v1/videos/{video_id}

Estado, progreso, créditos y, cuando se complete, los enlaces de descarga. El estado puede ser queued (en cola), processing (procesando), completed (completado), failed (fallido) o cancelled (cancelado). Los videos completados tienen salidas con download_url (calidad completa), web_url (720p) y poster_url, firmadas por 7 días.

CLI kinetune videos get MCP get_video Scopes videos:read

Campo	Tipo	Descripción
`video_id` ruta · obligatorio	string	El id del video

Cancelar un video

POST /api/v1/videos/{video_id}/cancel

Detiene un video en cola o en procesamiento (los créditos se liberan).

CLI kinetune videos cancel MCP cancel_video Scopes videos:write

Campo	Tipo	Descripción
`video_id` ruta · obligatorio	string	El id del video

Volver a hacer un video

POST /api/v1/videos/{video_id}/retry

Ejecuta nuevamente un video finalizado, fallido o cancelado (nuevo cargo). Reutiliza su Look, medios de fondo y bucles, por lo que nada de lo ya creado se vuelve a pagar.

CLI kinetune videos retry MCP retry_video Scopes videos:write

Campo	Tipo	Descripción
`video_id` ruta · obligatorio	string	El id del video

Eliminar un video

DELETE /api/v1/videos/{video_id}

Elimina un video finalizado y sus archivos.

CLI kinetune videos delete MCP delete_video Scopes videos:write

Campo	Tipo	Descripción
`video_id` ruta · obligatorio	string	El id del video