Guias de mídia
Geração de Música
Crie tarefas de música ou letras, consulte o áudio final e armazene as saídas de música voltadas para o usuário de forma segura.
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-10spara tarefas longas, depois pare emcompletedoufailed. - Não exiba um player final até que a tarefa esteja
completede umaudio_urlexista. - 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_idarmazenado 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 |