Geração de Música

A geração de música é assíncrona. POST /v1/music/generations cria uma tarefa pública do TokenLab e retorna id / task_id, status e geralmente poll_url. Seu aplicativo deve armazenar essa identidade de tarefa, mostrar o progresso e consultar até um status terminal.

Escolha O Fluxo de Trabalho

Fluxo de Trabalho	Campos principais	Notas
Música completa ou instrumental	`model`, `mv`, `prompt`, `title` opcional, `tags`, `action: "MUSIC"`	Use quando o usuário espera áudio final
Apenas letras	`model`, `prompt`, `action: "LYRICS"`	Use apenas com modelos que expõem a geração de letras
Continuar um clipe existente	`continue_clip_id`, `continue_at` opcional	Armazene a identidade do clipe/tarefa pública anterior antes de oferecer a continuação

Consulte o catálogo de modelos atual antes de enviar uma lista de modelos codificada:

curl "https://api.tokenlab.sh/v1/models?recommended_for=music" \
  -H "Authorization: Bearer sk-your-api-key"

Os exemplos públicos atuais usam suno_music para geração de música e incluem mv com uma versão oficial do modelo Suno, como chirp-v4. Para fluxos apenas de letras, envie action: "LYRICS" com um modelo cujo detalhes do modelo documente a geração de letras e omita mv. Trate os IDs de modelo como IDs públicos do TokenLab, não como uma garantia de que campos específicos do provedor são campos de detalhes do modelo.

Criar Uma Tarefa de Música

curl https://api.tokenlab.sh/v1/music/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno_music",
    "mv": "chirp-v4",
    "prompt": "Uma faixa de synth-pop animada com vocais quentes e um refrão limpo",
    "title": "Estática da Manhã",
    "tags": "synth-pop, animado",
    "action": "MUSIC"
  }'

Mantenha prompts, títulos e tags visíveis para o usuário e seguros para armazenar. Não coloque chaves de API, URLs privadas ou informações privadas de diagnóstico em nenhum campo de prompt.

Consultar Para Conclusão

Use poll_url primeiro. Se seu cliente precisar de uma rota fixa, chame GET /v1/tasks/{id} com o id ou task_id retornado.

curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"

Formato da resposta

A resposta de criação é um registro de tarefa consultável, não o áudio final:

{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "created": 1706000000,
  "model": "suno_music"
}

Uma resposta de polling concluída pode incluir os campos de mídia finais:

{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "completed",
  "audio_url": "https://cdn.example.com/music/abc123.mp3",
  "video_url": "https://cdn.example.com/music/abc123.mp4",
  "stream_audio_url": "https://cdn.example.com/music/abc123-stream.mp3",
  "image_url": "https://cdn.example.com/music/cover.jpg",
  "title": "Morning Static",
  "lyrics": "[Verse 1]\n..."
}

Os campos de mídia finais ficam ausentes até que status seja completed. Tarefas com falha retornam status: "failed" com error. Os status públicos esperados são pending, processing, completed e failed. Uma tarefa de música concluída pode incluir audio_url, video_url, title, lyrics e metadados normalizados. Armazene URLs finais em seu próprio banco de dados para que o usuário possa reabrir o resultado sem reiniciar a geração.

UI E Manipulação de Estado

Mostre um estado pendente imediatamente após a criação da tarefa.
Consulte a cada 5-10s para tarefas longas, depois pare em completed ou failed.
Não exiba um player final até que a tarefa esteja completed e um audio_url exista.
Para tarefas apenas de letras, renderize a saída de texto separadamente das tarefas de áudio para que os usuários entendam o que estão comprando.
Ao atualizar, retome do task_id armazenado em vez de criar uma nova tarefa.

Cobrança E Reconciliação

Tarefas de música podem reservar um valor estimado no momento da criação e liquidar após o status terminal ser conhecido. Armazene request_id, task_id, modelo, endpoint e billing_transaction_id quando aparecer. Use registros de uso da API de Gerenciamento para reconciliação em vez de IDs de tarefas do provedor.

Erros Comuns

Sintoma	Causa provável	Correção
Tarefa criada, mas sem player	A tarefa ainda está pendente ou concluída sem `audio_url`	Continue consultando até o terminal, depois trate a saída ausente como um trabalho de usuário falhado
Músicas duplicadas após atualização	A UI recriou a tarefa em vez de retomar	Persista e reutilize `task_id`
Tarefa de letra não retorna áudio	`action: "LYRICS"` é apenas texto	Separe os caminhos de UI de letras e música
Parâmetro não suportado	Campo não está nos detalhes do modelo do modelo	Remova campos específicos do provedor ou escolha um modelo que os documente

Referência da API

Tópico	Referência
Criar Música	Criar Música
Obter Status da Música	Obter Status da Música
Obter Status da Tarefa	Obter Status da Tarefa
Listar Modelos	Listar Modelos
Cobrança & Preços	Cobrança & Preços

Primeiros passos

Guias principais

Guias de mídia

Geração de Música

Escolha O Fluxo de Trabalho

Criar Uma Tarefa de Música

Consultar Para Conclusão

Formato da resposta

UI E Manipulação de Estado

Cobrança E Reconciliação

Erros Comuns

Referência da API

​Escolha O Fluxo de Trabalho

​Criar Uma Tarefa de Música

​Consultar Para Conclusão

​Formato da resposta

​UI E Manipulação de Estado

​Cobrança E Reconciliação

​Erros Comuns

​Referência da API

Escolha O Fluxo de Trabalho

Criar Uma Tarefa de Música

Consultar Para Conclusão

Formato da resposta

UI E Manipulação de Estado

Cobrança E Reconciliação

Erros Comuns

Referência da API