Referência da APIUsuários avançadosAtualizado em
POST/v1/music/generations

API de geração de música do Suno

Use o Suno V6 para gerar músicas a partir de uma descrição ou letra própria. Também é possível gerar faixas instrumentais.

Use https://api.icodeeasy.cc como URL base. Se a conexão estiver lenta, use https://jp.icodeeasy.cc ou https://sg.icodeeasy.cc com as mesmas rotas. Envie Authorization: Bearer <sua chave de API> nas duas requisições.

Enviar uma tarefa de geração

bash
curl -X POST https://api.icodeeasy.cc/v1/music/generations \
  -H "Authorization: Bearer $ICODEEASY_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: music-demo-001' \
  -d '{"model":"suno","version":"v6","prompt":"A warm jazz trio with brushed drums","instrumental":true,"audio_format":"mp3"}'

A resposta é HTTP 202. Guarde data[0].task_id para consultar a tarefa. As faixas ficam disponíveis quando a geração termina.

json
{"code":202,"data":[{"task_id":"mus_0123456789abcdef0123456789abcdef","status":"submitted","progress":0}]}

Parâmetros da requisição

CampoUso
modelUse suno ou omita o campo.
versionv6 (padrão), v6-wild ou v6-mini.
customfalse (padrão) gera a partir de uma descrição. true usa uma letra própria.
promptDescrição de até 3.000 caracteres ou letra de até 5.000 caracteres. Pode ser omitido quando custom e instrumental forem true.
instrumentaltrue gera música instrumental.
title / styleTítulo e estilo opcionais no modo personalizado, com até 80 e 1.000 caracteres, respectivamente.
audio_formatmp3 (padrão), m4a ou wav.

Use um Idempotency-Key único de até 128 bytes para cada tarefa. Se o envio expirar ou a resposta se perder, reenvie o mesmo corpo com a mesma chave para recuperar a tarefa existente. Reutilizar a chave com outro corpo retorna HTTP 409.

Consultar a tarefa e baixar as faixas

bash
curl https://api.icodeeasy.cc/v1/music/tasks/mus_0123456789abcdef0123456789abcdef \
  -H "Authorization: Bearer $ICODEEASY_API_KEY"

Consulte a cada 10 segundos, aproximadamente. A consulta retorna HTTP 200. Leia data.status para verificar o estado da tarefa.

  • pending, submitted e processing indicam que você pode continuar consultando.
  • completed disponibiliza todas as faixas em data.result.music. A quantidade de faixas pode variar.
  • failed indica falha. unknown indica que o envio não pôde ser confirmado. Guarde o ID da tarefa e a chave de idempotência e evite o reenvio automático com uma chave nova.

Cada faixa tem audio_index, duration em segundos e um audio_url assinado para reprodução. Use download_url para baixar a faixa, quando disponível. O resultado também pode incluir title e lyrics. Links assinados dispensam a chave de API, por isso mantenha-os em sigilo. Se o link expirar, consulte a tarefa novamente.

Exemplo de resposta de uma tarefa concluída. O valor serve apenas para ilustrar o formato do campo.

json
{
  "code": 200,
  "data": {
    "id": "mus_0123456789abcdef0123456789abcdef",
    "status": "completed",
    "model": "suno",
    "version": "v6",
    "progress": 100,
    "cost_rmb": 0.50,
    "result": {
      "music": [
        {
          "audio_index": 1,
          "duration": 138.5,
          "audio_url": "https://audio.example/track-1.mp3?signature=example",
          "download_url": "https://audio.example/track-1.mp3?download=1&signature=example"
        },
        {
          "audio_index": 2,
          "duration": 146.2,
          "audio_url": "https://audio.example/track-2.mp3?signature=example",
          "download_url": "https://audio.example/track-2.mp3?download=1&signature=example"
        }
      ]
    }
  }
}

Cobrança

Cada tarefa concluída com sucesso é cobrada uma vez. O valor final em yuan chinês (RMB) está em data.cost_rmb. O envio reserva saldo e, em caso de falha, a reserva é devolvida. Consultar ou baixar não gera cobrança adicional. Saldo insuficiente retorna HTTP 402.