Guias de mídia
Geração de música
Crie músicas ou letras e aguarde a conclusão do áudio
A geração de música é assíncrona. O endpoint POST /v1/music/generations retorna um ID de tarefa, status e, geralmente, uma poll_url. Realize o polling em GET /v1/tasks/{id} com esse ID até que a tarefa esteja completed ou failed.
Escolha o que criar
| O que criar | Campos principais | Notas |
|---|---|---|
| Música completa ou instrumental | model, mv, prompt, opcional title, tags, action: "MUSIC" | Use quando o usuário espera o áudio final |
| Apenas letras | model, prompt, action: "LYRICS" | Use apenas com modelos que oferecem geração de letras |
| Continuar um clipe existente | model, mv, prompt, continue_clip_id, opcional continue_at | Mantenha o ID do clipe anterior |
| Fazer cover ou estender seu próprio áudio | model, mv, prompt, audio_url, opcional audio_operation | audio_url deve ser uma URL pública. audio_operation é upload-cover por padrão; upload-extend também requer continue_at |
| Adicionar instrumental, substituir seção ou separar stems | audio_operation: add-instrumental, replace-section, vocal-separate, multi-stem-separation ou advanced-split | Cada operação possui seus próprios campos obrigatórios; consulte Criar Música |
Obtenha a lista atual de modelos de música em:
curl "https://api.tokenlab.sh/v1/models?recommended_for=music" \
-H "Authorization: Bearer sk-your-api-key"O exemplo abaixo utiliza suno-music com mv: "chirp-v6". Outros modelos de música, como stable-audio-3, utilizam campos diferentes, como duration e output_format; leia os detalhes do modelo primeiro. Para apenas letras, escolha um modelo que documente a geração de letras, envie action: "LYRICS" e omita o mv.
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-v6",
"prompt": "An upbeat synth-pop track with warm vocals and a clean chorus",
"title": "Morning Static",
"tags": "synth-pop, upbeat",
"action": "MUSIC"
}'Prompts, títulos e tags podem aparecer no histórico do seu produto. Nunca coloque chaves de API, URLs privadas ou dados de diagnóstico neles.
Obter o áudio finalizado
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, 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 final:
{
"id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"status": "completed",
"audio_url": "https://api.tokenlab.sh/v1/media-results/2d7e9a41-8c3b-4b6f-a1e5-7f0c3d9b8e26.mp3?token=…",
"video_url": "https://api.tokenlab.sh/v1/media-results/9a3f5c17-2e8d-4b0a-b6c4-1d7e8f2a5b39.mp4?token=…",
"image_url": "https://api.tokenlab.sh/v1/media-results/c4e8b2d6-7a1f-4e3c-9d5b-3f6a0e8c1b72.jpg?token=…",
"title": "Morning Static",
"lyrics": "[Verse 1]\n...",
"media_retention": {
"days": 30,
"items": [
{
"url": "https://api.tokenlab.sh/v1/media-results/2d7e9a41-8c3b-4b6f-a1e5-7f0c3d9b8e26.mp3?token=…",
"kind": "audio",
"status": "saving",
"expires_at": "2024-02-22T08:54:20.000Z"
},
{
"url": "https://api.tokenlab.sh/v1/media-results/9a3f5c17-2e8d-4b0a-b6c4-1d7e8f2a5b39.mp4?token=…",
"kind": "video",
"status": "saving",
"expires_at": "2024-02-22T08:54:20.000Z"
},
{
"url": "https://api.tokenlab.sh/v1/media-results/c4e8b2d6-7a1f-4e3c-9d5b-3f6a0e8c1b72.jpg?token=…",
"kind": "image",
"status": "saving",
"expires_at": "2024-02-22T08:54:20.000Z"
}
]
}
}Os campos de mídia final ficam ausentes até que o status seja completed. Tarefas com falha retornam status: "failed" com um error.
Os status são pending, processing, completed e failed. Uma tarefa concluída pode incluir audio_url, video_url, title, lyrics e outros metadados. As URLs de mídia são URLs da TokenLab que permanecem válidas por 30 dias; baixe ou salve qualquer resultado que você precise manter por mais tempo.
Exibir o estado correto
- Exiba um estado de "pendente" imediatamente após a criação da tarefa.
- Realize o polling a cada
5-10spara tarefas longas e pare quando o status forcompletedoufailed. - Não exiba um player final até que a tarefa esteja
completede umaaudio_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 adquirindo.
- Ao atualizar a página, retome a partir do
task_idarmazenado em vez de criar uma nova tarefa.
Registros de faturamento
Tarefas de música podem reservar um valor estimado quando criadas. O valor final é registrado após a conclusão ou falha. Salve o request_id, task_id, modelo, endpoint e billing_transaction_id quando aparecerem; use os registros de uso da Management API para a cobrança final.
Erros comuns
| Sintoma | Causa provável | Solução |
|---|---|---|
| Tarefa criada, mas sem player | A tarefa ainda está pendente ou foi concluída sem audio_url | Continue o polling até o estado final, depois trate a falta de saída como um trabalho de usuário com falha |
| Músicas duplicadas após atualizar | A interface recriou a tarefa em vez de retomar | Persista e reutilize o task_id |
| Tarefa de letra não retorna áudio | action: "LYRICS" é apenas texto | Separe os caminhos de interface de letras e música |
| Parâmetro não suportado | O modelo selecionado não aceita o campo | Remova-o ou escolha um modelo que o 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 |
| Faturamento e Preços | Faturamento e Preços |