Referência da API

Música

Modelos deste endpoint (1)

POST/v1/music/generations

GET/v1/music/tasks/{task_id}

GET/v1/music/tasks/{task_id}/content

Geração de música assíncrona para fluxos de canções e instrumentais. O envio retorna um task_id imediatamente; consulte a tarefa ou aceite um callback de webhook e depois leia o áudio concluído em /content.

#Parâmetros da requisição

modelstringobrigatório
ID de um modelo de música da página de modelos, por exemplo suno.
promptstringobrigatório
Descreva a música, o clima, a instrumentação ou a direção da letra.
titlestringopcional
Título opcional da faixa, repassado às famílias de modelos que o suportam.
tagsstring | arrayopcional
Dicas opcionais de gênero ou estilo, como cinematic, pop ou ambient.
versionstringopcional
Seletor de versão da família de modelos quando o provedor oferece várias gerações.
mvstringopcional
Seletor de modo de música específico do provedor; mantenha no servidor, a menos que os usuários precisem de controle explícito.
instrumentalbooleanopcional
Gera saída instrumental sem vocais quando o modelo suporta.
make_instrumentalbooleanopcional
Flag alternativa do provedor para saída instrumental; alguns provedores a usam no lugar de instrumental.
continue_clip_idstringopcional
Continua ou estende um clipe anterior em vez de começar uma faixa nova.
continue_atnumberopcional
Ponto de retomada em segundos nos fluxos de continuação.
webhook_urlstringopcional
URL HTTPS chamada quando a tarefa chega a um estado final.
webhook_secretstringopcional
Se definido, as entregas trazem X-Xiaoxiang-Signature: sha256=hex(HMAC-SHA256(body, secret)).

Comece simples

Na maioria dos produtos, prompt basta para a primeira integração. Os campos title, tags, version e de continuação são controles avançados que só devem ser adicionados quando o produto tiver uma necessidade clara.

Mesmo contrato assíncrono das outras tarefas de mídia

A música segue o mesmo padrão envio → consulta ou webhook → /content das tarefas de imagem e vídeo, então um único executor de tarefas no backend geralmente dá conta dos três.

#Erros relacionados

404 not_foundCaminho desconhecido, nome de modelo desconhecido ou um task_id expirado ou de outra conta.
422 unprocessable_entityO provedor rejeitou valores de parâmetros que o gateway repassou (por exemplo, tamanho ou duração não suportados).
401Bearer token inválido ou ausente. Não há error.code neste caminho — verifique o status.
402 insufficient_user_quotaO saldo da carteira não cobre a estimativa pré-reservada.
429Limitação por chave. Corpo vazio; aguarde o Retry-After. Um 429 que traz insufficient_user_quota indica, na verdade, o limite de gastos diário.
503 model_not_foundModelo desconhecido, ou nenhum canal saudável o atende no momento.

Tabela completa de códigos de erro →

#Exemplo de requisição

# submit
curl https://www.aisplice.store/v1/music/generations \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno",
    "prompt": "a warm cinematic piano theme",
    "instrumental": true
  }'

# poll every 5s
curl https://www.aisplice.store/v1/music/tasks/$TASK_ID -H "Authorization: Bearer sk-YOUR_KEY"

# fetch the finished track
curl -L https://www.aisplice.store/v1/music/tasks/$TASK_ID/content \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -o song.mp3

#Resposta

response.json

// POST — submit accepted
{"task_id": "task_xxx", "status": "queued"}

// GET /v1/music/tasks/{task_id}
{
  "task_id": "task_xxx",
  "status": "in_progress",
  "progress": "42%"
}

// GET /v1/music/tasks/{task_id}/content
{
  "task_id": "task_xxx",
  "status": "completed",
  "metadata": {
    "audio_url": "https://…",
    "lyric": "…"
  }
}

Ainda com problemas?

Envie para nós o ID da requisição ou a mensagem de erro e vamos investigar.

AnteriorVídeos PróximoModelos 3D