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 criarCampos principaisNotas
Música completa ou instrumentalmodel, mv, prompt, opcional title, tags, action: "MUSIC"Use quando o usuário espera o áudio final
Apenas letrasmodel, prompt, action: "LYRICS"Use apenas com modelos que oferecem geração de letras
Continuar um clipe existentemodel, mv, prompt, continue_clip_id, opcional continue_atMantenha o ID do clipe anterior
Fazer cover ou estender seu próprio áudiomodel, mv, prompt, audio_url, opcional audio_operationaudio_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 stemsaudio_operation: add-instrumental, replace-section, vocal-separate, multi-stem-separation ou advanced-splitCada 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-10s para tarefas longas e pare quando o status for completed ou failed.
  • Não exiba um player final até que a tarefa esteja completed e uma 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 adquirindo.
  • Ao atualizar a página, retome a partir do task_id armazenado 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

SintomaCausa provávelSolução
Tarefa criada, mas sem playerA tarefa ainda está pendente ou foi concluída sem audio_urlContinue 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 atualizarA interface recriou a tarefa em vez de retomarPersista e reutilize o task_id
Tarefa de letra não retorna áudioaction: "LYRICS" é apenas textoSepare os caminhos de interface de letras e música
Parâmetro não suportadoO modelo selecionado não aceita o campoRemova-o ou escolha um modelo que o documente

Referência da API

TópicoReferência
Criar MúsicaCriar Música
Obter Status da MúsicaObter Status da Música
Obter Status da TarefaObter Status da Tarefa
Listar ModelosListar Modelos
Faturamento e PreçosFaturamento e Preços

Nesta página