Música

Criar Música

Cria uma tarefa de geração de música, letra ou som

POST
/v1/music/generations

Use GET /v1/models?recommended_for=music para obter os modelos de música atuais.

Gere música, letras e som com IA. Esta é uma API assíncrona. As respostas de criação retornam uma identidade de tarefa. Consulte GET /v1/tasks/{id} com ela para obter o status.

Os modelos diferem nos campos que aceitam. Verifique GET /v1/models/{model} antes de enviar campos opcionais; um campo que o modelo não lista pode retornar 400 unsupported_parameter. Os campos do Suno (mv, title, tags, negative_tags, audio_operation e os campos associados a eles) se aplicam aos modelos Suno. user não é suportado e retorna 400.

Corpo da Requisição

modelstringpadrão: suno-music

ID do modelo de música, como suno-music ou stable-audio-3. Envie-o explicitamente. Apenas para letras, escolha um modelo cujas operações públicas atuais incluam lyrics.

promptstring

Descrição da música ou texto de substituição. Obrigatório para music, lyrics, upload-cover, upload-extend e replace-section; opcional para add-instrumental e separação de stems.

titlestring

Título para a música gerada.

tagsstring

Tags de estilo (por exemplo, "pop, upbeat, electronic").

negative_tagsstring

Estilos a serem evitados. Obrigatório quando audio_operation for add-instrumental.

actionstring

Valor opcional MUSIC ou LYRICS. Escolha um modelo que suporte a operação pública correspondente; este campo não adiciona suporte a letras a um modelo apenas de música.

mvstring

Seletor de versão do Suno. Obrigatório para geração, upload-cover, upload-extend, add-instrumental e substituição a partir de audio_url. Omita-o para letras, substituição a partir de task_id + audio_id e separação de stems. Valores aceitos: chirp-v6, chirp-v6-mini, chirp-v6-wild.

make_instrumentalboolean

Defina como true para gerar saída instrumental sem vocais.

audio_urlstring

URL de áudio de referência publicamente acessível ou carregada. Quando fornecida sem audio_operation, o TokenLab usa o fluxo upload-cover.

audio_operationstring

Operação de áudio: upload-cover, upload-extend, add-instrumental, replace-section, vocal-separate, multi-stem-separation, advanced-split.

vocal-separate, multi-stem-separation e advanced-split exigem task_id + audio_id; advanced-split também exige stem_name. upload-extend exige continue_at maior que 0. add-instrumental exige audio_url, title, tags e negative_tags.

Para replace-section, envie prompt, tags, title, infill_start_s, infill_end_s e full_lyrics. Escolha exatamente uma fonte: task_id + audio_id, ou audio_url + mv. O intervalo de substituição deve ser de 6 a 60 segundos.

task_idstring

ID da tarefa de origem pertencente à sua organização, para substituição de áudio gerado ou separação de stems.

audio_idstring

ID do áudio de origem retornado no resultado da tarefa de origem. Obrigatório com task_id para substituição de áudio gerado e separação de stems.

infill_start_snumber

Tempo de início da substituição em segundos, pelo menos 0. Obrigatório para replace-section.

infill_end_snumber

Tempo de término da substituição em segundos. Obrigatório para replace-section; deve ser de 6 a 60 segundos após infill_start_s.

full_lyricsstring

Letra completa para a música resultante. Obrigatório para replace-section.

stem_namestring

Nome do stem. Obrigatório para advanced-split.

continue_clip_idstring

ID de um clipe anterior a partir do qual continuar.

continue_atnumber

Tempo em segundos a partir do qual continuar. Obrigatório e maior que 0 para upload-extend.

durationinteger

Duração do áudio gerado em segundos, de 1 a 380. Apenas para modelos que o listam, como stable-audio-3; os detalhes do modelo fornecem seu próprio limite.

output_formatstring

Formato do arquivo de áudio listado pelo modelo, por exemplo mp3, wav ou flac. Apenas para modelos que o listam.

seedinteger

Seed para saída reproduzível, de 0 a 4294967294. Apenas para modelos que a listam.

stepsinteger

Número de passos de geração. O intervalo depende do modelo (por exemplo, 4 a 8 para stable-audio-3). Apenas para modelos que o listam.

Alguns modelos listam mais campos, como negative_prompt, n, seconds e guidance_scale. Envie-os apenas quando os detalhes do modelo os listarem; um campo que o modelo selecionado não aceita retornará 400.

cfg_scalenumber

Intensidade de orientação do prompt, de 1 a 25. Apenas para modelos que a listam.

prompt aceita até 5000 caracteres; tags e negative_tags aceitam até 1000 caracteres cada. As operações e parâmetros suportados dependem dos detalhes atuais do modelo selecionado.

Resposta

idstring

ID da tarefa para consultar o status.

task_idstring

Alias do mesmo ID de tarefa assíncrona, quando retornado.

poll_urlstring

URL de status para esta tarefa. Consulte GET /v1/tasks/{id} com id.

statusstring

Status da tarefa: pending, processing, completed ou failed.

createdinteger

Horário de criação da tarefa como um timestamp Unix, quando retornado.

Requisição

curl -X POST "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 electronic dance track with heavy bass",
    "title": "Night Drive",
    "tags": "electronic, EDM, energetic"
  }'

Exemplo de geração de som para um modelo que aceita duration e output_format em vez dos campos do Suno:

{
  "model": "stable-audio-3",
  "prompt": "Warm lo-fi beat with soft vinyl crackle",
  "duration": 30,
  "output_format": "mp3"
}

Resposta

Response
{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "model": "suno-music"
}

Autorização

BearerAuth
AuthorizationBearer <token>

Autenticação por Chave de API. Crie ou gerencie chaves de API em Dashboard > API > API Keys.

Local: header

Cabeçalhos

X-TokenLab-Delivery-Policy?string

Política de entrega por solicitação. Substitui os padrões da API key e do Workspace. Tenta automaticamente o TokenLab Verified primeiro e pode alternar uma vez para Official apenas antes da saída, aceitação da solicitação ou criação de recurso persistente.

Valores permitidos

  • "auto"
  • "verified"
  • "official"
Idempotency-Key?string

Chave opcional que torna uma requisição de criação segura para novas tentativas. Envie um novo valor único, como um UUID, para cada tarefa. Uma nova tentativa com a mesma chave e o mesmo corpo retorna o resultado da requisição de criação original, geralmente a tarefa original, e não cria, despacha ou cobra uma segunda tarefa. Um corpo diferente com uma chave que já foi aceita é rejeitado com 409. Uma chave com mais de 255 caracteres é ignorada e a requisição não terá proteção de idempotência. Veja Tente novamente com segurança usando uma chave de idempotência.

Comprimento1 <= length <= 255

Corpo da requisição

application/json

Resposta

application/json

application/json

application/json

application/json

application/json

application/json