Kinetune

Transforme músicas em vídeos de letras sincronizadas com as palavras (9:16, 16:9, 1:1) e loops para Spotify Canvas. Envie uma faixa, explore Looks, receba uma cotação de crédito exata e depois renderize e baixe.

Ver em kinetune.comExperimente este MCPPatrocinado

Servidor MCP hospedado

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

Instala no Claude Code, Codex, Cursor e outros

Documentação

Visão geral

Um único servidor atende tudo, e cada superfície executa as mesmas operações com a mesma validação e os mesmos preços exatos do aplicativo.

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

Descoberta OAuth

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

Como um vídeo é feito

Adicione uma música: o áudio master e sua capa quadrada. Ela é analisada (letras, batidas, seções) em cerca de um minuto.
Faça o orçamento do vídeo que você quer. O orçamento é o número exato de créditos; nada é cobrado.
Crie com a mesma solicitação mais o quote_id. Os créditos são retidos e cobrados somente quando o vídeo é entregue.
Aguarde o status: "completed": consulte o vídeo ou receba um callback assinado.
Baixe os arquivos: um MP4 por formato, links válidos por 7 dias (solicite novamente para obter novos).

Início rápido

A mesma solicitação de três maneiras. Escolha a que corresponde ao local onde seu código ou agente é executado.

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

Autenticação

Dois tipos de credenciais, ambos enviados como token Bearer e ambos limitados a uma organização.

Chaves de API — servidores, CI e n8n

Crie uma na página API do aplicativo (proprietários e administradores). O segredo é mostrado uma vez; armazenamos apenas um HMAC. As chaves agem em nome da organização e são limitadas pelo seu plano.

Cabeçalho

Authorization: Bearer kt_live_YOUR_KEY

Escopos

videos:read

Ver vídeos, orçamentos e seu saldo de créditos

videos:write

Orçar, criar, cancelar, tentar novamente e excluir vídeos (gasta créditos)

music:read

Ver artistas, suas fotos e músicas

music:write

Adicionar, renomear e arquivar artistas e músicas, enviar músicas e fotos de artistas

library:read

Navegar pelos Looks

library:write

Renomear, excluir e publicar seus Looks

Endpoints OAuth

Servidor de autorização

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

Recurso MCP

https://kinetune.com/mcp · metadados em /.well-known/oauth-protected-resource/mcp

Recurso REST

https://kinetune.com/api/v1 · metadados em /.well-known/oauth-protected-resource/api/v1

Autorizar · token

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

Envie resource (RFC 8707) com a URL MCP ou REST para que o público do token corresponda; chamadas não autenticadas respondem 401 com um cabeçalho WWW-Authenticate que aponta para os metadados do recurso.

Servidor MCP

Agentes remotos usam o Kinetune por meio do Model Context Protocol: uma ferramenta por operação de API, HTTP Streamable, login com sua conta.

URL do servidor

https://kinetune.com/mcp

Também listado no Registro MCP oficial (com.kinetune/kinetune), no Smithery, no Glama e no Cursor Directory.

No ChatGPT, abra Configurações → Aplicativos e Conectores → Avançado e ative o Modo de desenvolvedor (depende do seu plano e das configurações do espaço de trabalho).
Escolha Criar, nomeie como Kinetune, cole a URL do servidor e selecione OAuth.
Faça login, escolha a organização e aprove. Em seguida, ative-o em um chat pelo menu de ferramentas.

Ferramentas

O servidor é sem estado (respostas JSON, protocolo 2025-11-25). As ferramentas que criam vídeos gastam créditos, então os agentes são instruídos a orçar primeiro e perguntar. wait_for_video aguarda até 55 segundos por chamada.

Ferramenta	O que faz
get_account	Quem está conectado, a organização e seu saldo de créditos
get_options	Tipos de vídeo, categorias de Look, fontes de fundo, formatos e os preços atuais em créditos
list_artists	Artistas por nome, com contagens de músicas e fotos e uma imagem
create_artist	Adicionar um artista por nome
get_artist	Um artista
rename_artist	Alterar o nome de um artista
archive_artist destrutivo	Remover um artista que não tem músicas
set_artist_picture	Escolher qual foto é a imagem do artista e como ela é cortada em um quadrado
list_artist_photos	As fotos do artista (referências de identidade, até 6)
add_artist_photos	Enviar uma ou mais fotos do artista (JPEG, PNG ou WebP)
delete_artist_photo destrutivo	Remover uma foto
list_songs	Músicas com capa, duração e status de análise
create_song	Adicionar uma música: áudio master e capa quadrada
get_song	Uma música e seu status de análise
rename_song	Alterar o título de uma música
archive_song destrutivo	Remover uma música (seus vídeos permanecem)
get_song_analysis	Letras com tempo por palavra, andamento, batidas, seções e refrão
reanalyze_song	Tentar novamente uma análise com falha
list_looks	Navegar pelos Looks Oficiais, da Comunidade e seus próprios
get_look	Um Look com seu design e imagens de pré-visualização
rename_look	Renomear um dos seus Looks
delete_look destrutivo	Remover um dos seus Looks (vídeos feitos com ele permanecem)
set_look_visibility	Tornar um dos seus Looks público (ganha 10 créditos) ou privado
upload_background	Enviar sua própria foto ou vídeo para criar um Novo Look em torno dele
search_stock	Encontrar fotos ou clipes do Pexels para usar como fundo de banco de imagens
quote_lyric_video	Os créditos exatos para um vídeo de letras, antes de qualquer cobrança
quote_canvas	Os créditos exatos para um Spotify Canvas, antes de qualquer cobrança
create_lyric_video	Criar o vídeo de letras com o preço do orçamento (gasta créditos)
create_canvas	Criar o Canvas com o preço do orçamento (gasta créditos)
list_videos	Vídeos, do mais recente ao mais antigo, com status e miniaturas
get_video	Status, progresso, créditos e, quando concluído, os links de download
cancel_video destrutivo	Parar um vídeo na fila ou em processamento (créditos liberados)
retry_video	Executar novamente um vídeo concluído, com falha ou cancelado (nova cobrança)
delete_video destrutivo	Excluir um vídeo concluído e seus arquivos
wait_for_video	Aguarda um vídeo terminar (até 55 s por chamada) e o retorna como get_video

Prompts e recursos

Clientes que mostram prompts como comandos recebem três inícios prontos: make_lyric_video, make_canvas e browse_looks. Cada um segue o fluxo de orçar primeiro.

Recursos somente leitura espelham as leituras da API: kinetune://account e kinetune://options, além de modelos para kinetune://songs/{song_id}, …/analysis, kinetune://looks/{look_id}, kinetune://videos/{video_id} e kinetune://artists/{artist_id}, todos retornados como JSON.

CLI

kinetune executa todas as operações pelo terminal. Ele imprime JSON sempre que a saída é canalizada, para que agentes locais e scripts leiam diretamente.

Instalação (Node 20+)

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

Fazer login

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

Trabalhando com ele

Os comandos seguem a API: kinetune songs list --q "tide" --limit 20, kinetune looks get LOOK_ID, kinetune quote lyric-video --song-id SONG_ID. IDs de caminho são argumentos, campos são flags, e --input file.json (ou - para stdin) recebe a solicitação inteira. Arquivos são enviados por caminho ou URL https: --audio ./song.wav.

kinetune create … sempre orça primeiro e pergunta antes de cobrar; passe --yes ou um teto com --max-credits 120 em scripts. kinetune videos wait e kinetune videos download concluem o trabalho.

Dê a um agente local (Codex, Cursor, opencode, Claude Code…) a habilidade Kinetune para que ele conheça o fluxo de trabalho: npx skills add kinetune/skills. É open source em 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

Ambiente e códigos de saída

KINETUNE_API_KEY

Uma chave de API da organização; vence o login armazenado (CI, servidores).

KINETUNE_URL

Outra implantação do aplicativo (padrão é este site).

KINETUNE_CONFIG_DIR

Onde as credenciais ficam; padrão ~/.config/kinetune (modo 600).

Códigos de saída

0 concluído · 1 erro de API ou rede · 2 uso inválido ou acima de --max-credits · 3 não conectado ou não permitido

API REST

JSON sobre HTTPS. Cada solicitação carrega uma credencial Bearer; IDs são strings prefixadas; horários são ISO 8601.

Fundamentos

URL base

https://kinetune.com/api/v1

Autenticação

Authorization: Bearer … — uma chave de API ou um token de acesso OAuth

Uploads

multipart/form-data arquivos, ou JSON com URLs https públicas (audio_url, cover_art_url, photo_urls, file_url)

Seu próprio fundo

POST /backgrounds aceita sua foto ou vídeo; um Novo Look com background.source upload-photo ou upload-video e seu upload_id é criado em torno dele, sem custo de mídia. Esse Look permanece privado.

Banco de imagens que você escolhe

GET /stock?kind=photo&q=…&orientation=portrait pesquisa no Pexels (24 por página; landscape quando 16:9 está entre os formatos, seconds para um clipe de Canvas). Uma fonte de banco de imagens com look.background.stock_id (ou um stock_id de Canvas) usa esse item em vez da escolha do diretor, o que remove a escolha do orçamento. Dê crédito ao fotógrafo sempre que exibir um item.

Orçamentos

Válidos por tempo limitado e uma única vez; crie com a solicitação idêntica mais quote_id. Reenviar o mesmo orçamento retorna os vídeos que ele já criou.

Links de download

Assinados, válidos por 7 dias; GET /videos/{id} retorna novos

Imagens

Mantidas nos tamanhos em que são usadas, não como enviadas: o cover_art.url de uma música (1536 px JPEG), preview_url (640 px) e thumbnail_url (160 px WebP); o url de uma foto de artista (1536 px) e thumbnail_url; o backgrounds.previews de um Look (480 px de largura). Links de imagem são assinados por 7 dias e permanecem os mesmos o dia todo, então têm bom cache.

Estilos de letras

Um Novo Look aceita look.lyric_style: como as letras são apresentadas e animadas (block-stack, punch, player, neon, terminal …). GET /options os lista; deixe de fora e o diretor escolhe um. Um Look Existente também aceita, para renderizar o mesmo design em outro estilo sem custo extra. GET /looks?lyric_style= filtra a Biblioteca.

Cenas

Um fundo de imagem com IA pode ter 2–4 tomadas do mesmo mundo que cortam nas seções da música: look.background.scenes (1 por padrão). Cada cena é precificada como a primeira.

Orçar um vídeo de letras com um Novo Look em um 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" }
  }'

Enviar arquivos (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

Passe callback_url (https, público) com o orçamento e a chamada de criação, e o vídeo é enviado a você via POST quando conclui, falha ou é cancelado.

Entrega

Corpo

O vídeo, exatamente como GET /videos/{id} o retorna

Cabeçalhos

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

Tentativas

Qualquer 2xx dentro de 10 segundos conta. Caso contrário, tenta novamente após 30 s, 2 min, 10 min, 30 min e 2 h.

Segredo de assinatura

Na página API do aplicativo (whsec_…); gire-o lá.

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));
}

Erros e limites

Erros são JSON: {"error": "…"} mais detalhes quando úteis (erros de campo, créditos necessários e disponíveis).

Códigos de status

400

Solicitação inválida; details.fieldErrors nomeia os campos.

401

Credenciais ausentes, inválidas ou expiradas (clientes OAuth atualizam e tentam novamente).

402

Créditos insuficientes: required e available informam quantos.

403

As credenciais não têm o escopo, ou a ação é reservada ao aplicativo.

404

Não encontrado nesta organização.

409

Um conflito de estado: a música ainda está sendo analisada, ou o orçamento expirou, foi usado ou não corresponde mais.

Renderizações simultâneas são limitadas pelo seu plano; vídeos extras aguardam na fila.

n8n

O nó da comunidade cobre as mesmas operações: músicas, artistas e fotos, Looks, orçamentos, vídeos e downloads.

Em um n8n auto-hospedado, abra Configurações → Nós da comunidade → Instalar e insira @kinetune/n8n-nodes-kinetune.
Crie uma credencial Kinetune API com uma chave de API do aplicativo; a URL base é https://kinetune.com.
Escolha artistas e músicas de uma lista pesquisável, ou alterne o campo para Por ID para um id ou uma expressão. Listar artistas e Listar músicas pesquisam e paginam como a API.
Faça uma cotação e depois crie com o id da cotação. Para continuar quando o vídeo estiver pronto, defina a URL de callback para um nó Webhook do n8n.

Referência da API

Cada operação com sua chamada REST, comando CLI e ferramenta MCP. Gerado a partir das mesmas definições que a API valida.

Conta

Obter a conta

GET /api/v1/account

Quem você é como usuário autenticado, a organização e seu saldo de créditos. Retorna a organização para a qual as credenciais atuam, como elas autenticam e seus escopos, e o saldo de créditos (disponível, mensal, recargas). Verifique antes de criar vídeos.

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

Sem parâmetros.

Listar as opções

GET /api/v1/options

Tipos de vídeo, categorias de Look, fontes de fundo, formatos e os preços atuais de créditos. Tudo o que uma solicitação pode escolher, com a tabela de créditos. Use para escolher uma categoria ou fonte e para explicar preços.

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

Sem parâmetros.

Artistas e fotos

Listar artistas

GET /api/v1/artists

Artistas por nome, com suas contagens de músicas e fotos e uma imagem. Músicas pertencem a um artista; crie o artista primeiro. Ordenado por nome, 50 por página por padrão: passe q para pesquisar por nome e limit/offset para paginar.

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

Campo	Tipo	Descrição
`q` consulta	string	Parte do nome do artista
`limit` consulta	inteiro 1–100	Resultados por página, 1-100 (padrão 50)
`offset` consulta	inteiro 0–9007199254740991	Quantos resultados pular

Criar um artista

POST /api/v1/artists

Adicione um artista por nome. Nomes são únicos por organização (409 quando já existir).

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

Campo	Tipo	Descrição
`name` corpo · obrigatório	string	O nome do artista

Obter um artista

GET /api/v1/artists/{artist_id}

Um artista.

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

Campo	Tipo	Descrição
`artist_id` caminho · obrigatório	string	O id do artista

Renomear um artista

PATCH /api/v1/artists/{artist_id}

Altere o nome de um artista.

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

Campo	Tipo	Descrição
`artist_id` caminho · obrigatório	string	O id do artista
`name` corpo · obrigatório	string	O novo nome

Arquivar um artista

DELETE /api/v1/artists/{artist_id}

Remova um artista que não tenha músicas. Recusado (409) enquanto o artista ainda tiver músicas.

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

Campo	Tipo	Descrição
`artist_id` caminho · obrigatório	string	O id do artista

Definir a imagem do artista

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

Escolha qual foto é a imagem do artista e como ela é cortada em um quadrado. A imagem (image_url no artista, um quadrado de 512 px) é cortada de uma das fotos do artista; a foto em si permanece inalterada. A primeira foto se torna a imagem automaticamente, centralizada. crop é em frações da foto (sua url): x/y é o canto superior esquerdo, size é o lado relativo ao lado menor da foto; omita para centralizar.

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

Campo	Tipo	Descrição
`artist_id` caminho · obrigatório	string	O id do artista
`photo_id` corpo · obrigatório	string	Uma das fotos do artista (list_artist_photos)
`crop` corpo	objeto	O quadrado a manter, em frações da foto; centralizado quando omitido

Listar fotos do artista

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

As fotos do artista (referências de identidade, até 6). As fotos mantêm o artista reconhecível quando um Look ou Canvas as exibe; a arte da capa permanece a fonte criativa. url é a foto em pé com até 1536 px (o que a IA recebe; largura e altura a descrevem), thumbnail_url é uma cópia de 320 px no lado menor para grades.

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

Campo	Tipo	Descrição
`artist_id` caminho · obrigatório	string	O id do artista

Adicionar fotos do artista

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

Envie uma ou mais fotos do artista (JPEG, PNG ou WebP). Até 6 por artista, pelo menos 512 px no lado menor, até 15 MB cada. Somente com os direitos de uso (rights_confirmed). São apenas referências de identidade: nunca exibidas publicamente ou usadas como estão. Cada uma é mantida em pé com até 1536 px, com uma miniatura pequena; o arquivo enviado em si não é mantido.

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

Arquivos: photos (multipart) ou photo_urls (JSON).

Campo	Tipo	Descrição
`artist_id` caminho · obrigatório	string	O id do artista
`photo_urls` corpo	URL[] (1–6)	URLs https públicas das fotos (ou envie arquivos com a CLI)
`rights_confirmed` corpo · obrigatório	true	Você tem os direitos de usar estas fotos do artista

Excluir uma foto do artista

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

Remova uma foto.

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

Campo	Tipo	Descrição
`artist_id` caminho · obrigatório	string	O id do artista
`photo_id` caminho · obrigatório	string	O id da foto

Músicas

Listar músicas

GET /api/v1/songs

Músicas com sua capa, duração e status de análise. Uma música deve ser analisada (analysis.status "ready") antes que vídeos possam ser criados. 50 por página por padrão: passe q para pesquisar e limit/offset para paginar. cover_art.url é a capa com até 1536 px (JPEG; largura e altura a descrevem), preview_url é um WebP de 640 px e thumbnail_url um WebP de 160 px. Links de imagem são assinados por 7 dias e permanecem os mesmos o dia todo, então podem ser armazenados em cache.

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

Campo	Tipo	Descrição
`artist_id` consulta	string	Apenas as músicas deste artista
`q` consulta	string	Parte do título da música ou nome do artista
`limit` consulta	inteiro 1–100	Resultados por página, 1-100 (padrão 50)
`offset` consulta	inteiro 0–9007199254740991	Quantos resultados pular
`status` consulta	"pending" \| "processing" \| "ready" \| "failed"	Apenas músicas cuja análise tem este status (ready = utilizável para vídeos)
`sort` consulta	"title" \| "newest"	title (padrão): por artista e depois título; newest: uploads mais recentes primeiro

Enviar uma música

POST /api/v1/songs

Adicione uma música: áudio master e arte de capa quadrada. Áudio: MP3, WAV ou M4A até 250 MB. Capa: um JPEG ou PNG quadrado, 1000–6000 px (3000×3000 recomendado), até 20 MB; é mantida em 1536, 640 e 160 px, não como enviada. A música é analisada em seguida (letras, batidas, seções): consulte get_song até analysis.status ser "ready", geralmente cerca de um minuto.

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

Arquivos: audio (multipart) ou audio_url (JSON), cover_art (multipart) ou cover_art_url (JSON).

Campo	Tipo	Descrição
`artist_id` corpo · obrigatório	string	O id do artista
`title` corpo · obrigatório	string	O título da música
`language` corpo	string	Idioma das letras (ISO 639-1, ex.: "en"); detectado quando omitido
`audio_url` corpo	URL	Uma URL https pública do áudio master
`cover_art_url` corpo	URL	Uma URL https pública da arte de capa quadrada

Obter uma música

GET /api/v1/songs/{song_id}

Uma música e seu status de análise. cover_art.url é a capa com até 1536 px (JPEG; largura e altura a descrevem), preview_url é um WebP de 640 px e thumbnail_url um WebP de 160 px. Links de imagem são assinados por 7 dias e permanecem os mesmos o dia todo, então podem ser armazenados em cache.

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

Campo	Tipo	Descrição
`song_id` caminho · obrigatório	string	O id da música

Renomear uma música

PATCH /api/v1/songs/{song_id}

Altere o título de uma música.

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

Campo	Tipo	Descrição
`song_id` caminho · obrigatório	string	O id da música
`title` corpo · obrigatório	string	O novo título

Arquivar uma música

DELETE /api/v1/songs/{song_id}

Remova uma música (seus vídeos permanecem).

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

Campo	Tipo	Descrição
`song_id` caminho · obrigatório	string	O id da música

Obter a análise de uma música

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

Letras com tempo por palavra, andamento, batidas, seções e refrão. Use os tempos das seções para escolher um corte para um vídeo de letras.

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

Campo	Tipo	Descrição
`song_id` caminho · obrigatório	string	O id da música

Analisar uma música novamente

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

Tente novamente uma análise que falhou.

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

Campo	Tipo	Descrição
`song_id` caminho · obrigatório	string	O id da música

Looks

Listar Looks

GET /api/v1/looks

Navegue por Looks Oficiais, da Comunidade e seus próprios. Um Look é um design completo e reutilizável de vídeo de letras. Passe seu id como {"mode":"existing","id":…} para reutilizá-lo exatamente. Um Look que mostra um artista (featured_artist) é privado e serve apenas às músicas desse artista: ao escolher para uma música, passe seu artist_id para deixar de fora Looks que mostram outro artista.

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

Campo	Tipo	Descrição
`scope` consulta	"all" \| "official" \| "community" \| "mine"	Qual biblioteca; padrão all
`category` consulta	string	Um id de categoria de get_options
`lyric_style` consulta	string	Um id de estilo de letras de get_options (como as letras se movem)
`artist_id` consulta	string	O artista da música para a qual você está escolhendo: Looks que mostram outro artista são deixados de fora
`q` consulta	string	Palavras de pesquisa
`sort` consulta	"newest" \| "popular"	—
`limit` consulta	inteiro 1–100	—
`offset` consulta	inteiro 0–9007199254740991	—

Obter um Look

GET /api/v1/looks/{look_id}

Um Look com seu design e imagens de pré-visualização. backgrounds.portrait e backgrounds.landscape são as placas de fundo que o vídeo usa; backgrounds.previews tem cópias de 480 px de largura delas para miniaturas (null para um Look sem fundo de foto ou vídeo).

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

Campo	Tipo	Descrição
`look_id` caminho · obrigatório	string	O id do Look

Renomear um Look

PATCH /api/v1/looks/{look_id}

Renomeie um dos seus Looks.

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

Campo	Tipo	Descrição
`look_id` caminho · obrigatório	string	O id do Look
`name` corpo · obrigatório	string	O novo nome

Excluir um Look

DELETE /api/v1/looks/{look_id}

Remova um dos seus Looks (vídeos feitos com ele permanecem).

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

Campo	Tipo	Descrição
`look_id` caminho · obrigatório	string	O id do Look

Publicar ou despublicar um Look

POST /api/v1/looks/{look_id}/visibility Make one of your Looks public (earns 10 credits) or private. Public Looks join the Community library under your @username. A Look that shows your artist stays private (409).

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

Campo	Tipo	Descrição
`look_id` path · obrigatório	string	O id do Look
`visibility` body · obrigatório	"public" \| "private"	—

Enviar um fundo

POST /api/v1/backgrounds

Envie sua própria foto ou vídeo para criar um Novo Look ao redor. Foto: JPEG, PNG ou WebP, com pelo menos 720 px no lado menor, até 25 MB. Vídeo: MP4, MOV ou WebM, de 4 a 180 segundos, com pelo menos 720 px no lado menor, até 300 MB; ele se torna um loop contínuo de até 20 s. Somente com os direitos de uso. Em seguida, faça uma cotação de lyric video com look {"mode":"new","category":"…","background":{"source":"upload-photo" ou "upload-video","upload_id":"…"},"visibility":"private"}.

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

Arquivos: file (multipart) ou file_url (JSON).

Campo	Tipo	Descrição
`file_url` body	URL	Uma URL pública https da foto ou do vídeo
`rights_confirmed` body · obrigatório	true	Você tem os direitos de usar esta foto ou vídeo

Quotes e vídeos

Cotar um lyric video

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

Os créditos exatos para um lyric video, antes de qualquer cobrança. Retorna quote_id, credits (total), credits_per_video e um detalhamento. Sempre faça a cotação primeiro e informe os créditos ao usuário antes de criar; os créditos são reservados na criação e cobrados somente quando o vídeo é entregue. Uma cotação é válida por 30 minutos.

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

Campo	Tipo	Descrição
`song_id` body · obrigatório	string	O id da música
`variations` body	inteiro 1–4	1–4 Novos Looks diferentes, um vídeo cada (um Look Existente renderiza um) Padrão `1`.
`callback_url` body	string	Uma URL https para enviar o vídeo finalizado (assinada; veja Callbacks). Cote e crie com o mesmo valor
`metadata` body	objeto	Seu próprio JSON (um id de pedido, por exemplo): mantido com o vídeo e retornado na solicitação. Cote e crie com o mesmo valor
`look` body · obrigatório	objeto	{"mode":"existing","id":"look_…"} para reutilizar um Look salvo (adicione "lyric_style" para renderizá-lo em outro estilo de letra, sem custo extra), ou {"mode":"new","category":"…","lyric_style":"…","background":{"source":"ai-image","quality":"high"},"visibility":"private","direction":"…"} para ter um criado (background.source "upload-photo"/"upload-video" com background.upload_id de upload_background cria ao redor da sua própria mídia; tal Look permanece privado. "stock-photo"/"stock-video" com background.stock_id de search_stock usa esse item do Pexels em vez da escolha do diretor). lyric_style (opcional, de get_options) define como as letras são apresentadas e animadas: block-stack, punch, player, neon, terminal, cinematic… Omita e o diretor escolhe um. background.scenes (2–4, somente AI image) cria essa quantidade de tomadas do mesmo mundo que cortam nas seções da música, cada uma com o preço da primeira. O cantor é deixado de fora, a menos que seja solicitado: feature_artist "always" (padrão "never") o torna o assunto do fundo, reconhecível pelas fotos do artista (add_artist_photos); isso requer um fundo AI image ou AI video, um Look privado e display.cover false (a capa o esconderia), e esse Look então atende apenas às músicas desse artista. Um Look salvo que mostra um artista (featured_artist) atende apenas às músicas desse artista, também com display.cover false
`aspect_ratios` body	"9:16" \| "16:9" \| "1:1"[] (1–3)	Formatos para renderizar, cada um com seu próprio arquivo: "9:16" (vertical), "16:9" (horizontal), "1:1" (quadrado) Padrão `["9:16"]`.
`display` body	objeto	Quais elementos aparecem (title, artist, cover, lyrics, badges, headline) e seus tamanhos. cover deve ser false para mostrar o artista no fundo Padrão `{"title":true,"artist":true,"cover":true,"lyrics":true,"badges":true}`.
`trim` body	objeto	Renderizar apenas esta seção da música (pelo menos 8 segundos)

Cotar um Canvas

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

Os créditos exatos para um Spotify Canvas, antes de qualquer cobrança. Retorna quote_id, credits e um detalhamento. Sempre faça a cotação primeiro e informe os créditos ao usuário antes de criar; os créditos são reservados na criação e cobrados somente quando o vídeo é entregue.

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

Campo	Tipo	Descrição
`song_id` body · obrigatório	string	O id da música
`variations` body	inteiro 1–4	1–4 Canvases diferentes Padrão `1`.
`callback_url` body	string	Uma URL https para enviar o vídeo finalizado (assinada; veja Callbacks). Cote e crie com o mesmo valor
`metadata` body	objeto	Seu próprio JSON (um id de pedido, por exemplo): mantido com o vídeo e retornado na solicitação. Cote e crie com o mesmo valor
`source` body	"ai-video" \| "ai-image" \| "stock-photo" \| "stock-video"	ai-video (padrão), ai-image, stock-photo ou stock-video Padrão `"ai-video"`.
`quality` body	"standard" \| "high"	Nível do modelo de AI video: standard ou high Padrão `"standard"`.
`resolution` body	"720p" \| "1080p"	1080p (1080×1920) ou 720p Padrão `"1080p"`.
`style` body	"cinematic" \| "dreamy" \| "abstract" \| "surreal" \| "retro" \| "minimal" \| "dark" \| "vibrant" \| "nature" \| "urban"	Estilo visual opcional
`direction` body	string	Humor, motivos ou referências opcionais; o conceito ainda vem da capa
`feature_artist` body	"auto" \| "always" \| "never"	Se o Canvas mostra o artista: auto (o diretor decide), always ou never (fontes de IA; precisa de fotos do artista para "always") Padrão `"auto"`.
`seconds` body	inteiro 5–8	Duração do Canvas em segundos inteiros, 5–8 (padrão 8). O Spotify o coloca em loop, então nenhuma parte da música é escolhida Padrão `8`.
`stock_id` body	string	Com uma fonte stock: a foto ou o vídeo do Pexels (search_stock com seconds) a usar em vez da escolha do diretor

Criar um lyric video

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

Crie o lyric video com o preço da cotação (gasta créditos). Envie a mesma solicitação da cotação mais o quote_id dela. Retorna os ids dos vídeos imediatamente; faça polling de get_video até que o status seja completed (ou failed). Cada vídeo tem um arquivo por formato.

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

Campo	Tipo	Descrição
`song_id` body · obrigatório	string	O id da música
`variations` body	inteiro 1–4	1–4 Novos Looks diferentes, um vídeo cada (um Look Existente renderiza um) Padrão `1`.
`callback_url` body	string	Uma URL https para enviar o vídeo finalizado (assinada; veja Callbacks). Cote e crie com o mesmo valor
`metadata` body	objeto	Seu próprio JSON (um id de pedido, por exemplo): mantido com o vídeo e retornado na solicitação. Cote e crie com o mesmo valor
`look` body · obrigatório	objeto	{"mode":"existing","id":"look_…"} para reutilizar um Look salvo (adicione "lyric_style" para renderizá-lo em outro estilo de letra, sem custo extra), ou {"mode":"new","category":"…","lyric_style":"…","background":{"source":"ai-image","quality":"high"},"visibility":"private","direction":"…"} para ter um criado (background.source "upload-photo"/"upload-video" com background.upload_id de upload_background cria ao redor da sua própria mídia; tal Look permanece privado. "stock-photo"/"stock-video" com background.stock_id de search_stock usa esse item do Pexels em vez da escolha do diretor). lyric_style (opcional, de get_options) define como as letras são apresentadas e animadas: block-stack, punch, player, neon, terminal, cinematic… Omita e o diretor escolhe um. background.scenes (2–4, somente AI image) cria essa quantidade de tomadas do mesmo mundo que cortam nas seções da música, cada uma com o preço da primeira. O cantor é deixado de fora, a menos que seja solicitado: feature_artist "always" (padrão "never") o torna o assunto do fundo, reconhecível pelas fotos do artista (add_artist_photos); isso requer um fundo AI image ou AI video, um Look privado e display.cover false (a capa o esconderia), e esse Look então atende apenas às músicas desse artista. Um Look salvo que mostra um artista (featured_artist) atende apenas às músicas desse artista, também com display.cover false
`aspect_ratios` body	"9:16" \| "16:9" \| "1:1"[] (1–3)	Formatos para renderizar, cada um com seu próprio arquivo: "9:16" (vertical), "16:9" (horizontal), "1:1" (quadrado) Padrão `["9:16"]`.
`display` body	objeto	Quais elementos aparecem (title, artist, cover, lyrics, badges, headline) e seus tamanhos. cover deve ser false para mostrar o artista no fundo Padrão `{"title":true,"artist":true,"cover":true,"lyrics":true,"badges":true}`.
`trim` body	objeto	Renderizar apenas esta seção da música (pelo menos 8 segundos)
`quote_id` body · obrigatório	uuid	O quote_id da cotação correspondente: a solicitação deve ser idêntica

Criar um Canvas

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

Crie o Canvas com o preço da cotação (gasta créditos). Envie a mesma solicitação da cotação mais o quote_id dela. Retorna os ids dos vídeos imediatamente; faça polling de get_video até que o status seja completed. Envie o arquivo no Spotify for Artists.

CLI kinetune create canvas MCP create_canvas Scopes videos:write

Campo	Tipo	Descrição
`song_id` body · obrigatório	string	O id da música
`variations` body	inteiro 1–4	1–4 Canvases diferentes Padrão `1`.
`callback_url` body	string	Uma URL https para enviar o vídeo finalizado (assinada; veja Callbacks). Cote e crie com o mesmo valor
`metadata` body	objeto	Seu próprio JSON (um id de pedido, por exemplo): mantido com o vídeo e retornado na solicitação. Cote e crie com o mesmo valor
`source` body	"ai-video" \| "ai-image" \| "stock-photo" \| "stock-video"	ai-video (padrão), ai-image, stock-photo ou stock-video Padrão `"ai-video"`.
`quality` body	"standard" \| "high"	Nível do modelo de AI video: standard ou high Padrão `"standard"`.
`resolution` body	"720p" \| "1080p"	1080p (1080×1920) ou 720p Padrão `"1080p"`.
`style` body	"cinematic" \| "dreamy" \| "abstract" \| "surreal" \| "retro" \| "minimal" \| "dark" \| "vibrant" \| "nature" \| "urban"	Estilo visual opcional
`direction` body	string	Humor, motivos ou referências opcionais; o conceito ainda vem da capa
`feature_artist` body	"auto" \| "always" \| "never"	Se o Canvas mostra o artista: auto (o diretor decide), always ou never (fontes de IA; precisa de fotos do artista para "always") Padrão `"auto"`.
`seconds` body	inteiro 5–8	Duração do Canvas em segundos inteiros, 5–8 (padrão 8). O Spotify o coloca em loop, então nenhuma parte da música é escolhida Padrão `8`.
`stock_id` body	string	Com uma fonte stock: a foto ou o vídeo do Pexels (search_stock com seconds) a usar em vez da escolha do diretor
`quote_id` body · obrigatório	uuid	O quote_id da cotação correspondente: a solicitação deve ser idêntica

Listar vídeos

GET /api/v1/videos

Vídeos, do mais recente para o mais antigo, com status e miniaturas.

CLI kinetune videos list MCP list_videos Scopes videos:read

Campo	Tipo	Descrição
`song_id` query	string	Somente os vídeos desta música
`type` query	"lyric-video" \| "canvas"	—
`limit` query	inteiro 1–100	—

Obter um vídeo

GET /api/v1/videos/{video_id}

Status, progresso, créditos e, quando concluído, os links de download. status é queued, processing, completed, failed ou cancelled. Vídeos concluídos têm outputs com download_url (qualidade total), web_url (720p) e poster_url, assinados por 7 dias.

CLI kinetune videos get MCP get_video Scopes videos:read

Campo	Tipo	Descrição
`video_id` path · obrigatório	string	O id do vídeo

Cancelar um vídeo

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

Interrompe um vídeo em fila ou em processamento (créditos liberados).

CLI kinetune videos cancel MCP cancel_video Scopes videos:write

Campo	Tipo	Descrição
`video_id` path · obrigatório	string	O id do vídeo

Refazer um vídeo

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

Executa novamente um vídeo concluído, falho ou cancelado (nova cobrança). Reutiliza seu Look, mídia de fundo e loops, então nada já feito é pago novamente.

CLI kinetune videos retry MCP retry_video Scopes videos:write

Campo	Tipo	Descrição
`video_id` path · obrigatório	string	O id do vídeo

Excluir um vídeo

DELETE /api/v1/videos/{video_id}

Exclui um vídeo concluído e seus arquivos.

CLI kinetune videos delete MCP delete_video Scopes videos:write

Campo	Tipo	Descrição
`video_id` path · obrigatório	string	O id do vídeo