action na requisição determina o tipo de operação. A chave primária do Project usa id de forma unificada; version_id representa a versão atual do projeto, e todas as operações de modificação e exportação devem enviar a versão mais recente para evitar sobrescritas simultâneas.
Visão geral das operações
As operações assíncronas retornam imediatamente um
task_id. Use a interface gratuita /suno/tasks para consultar, ou envie callback_url para receber o resultado em estado final.
Criar e ler
Idempotency-Key exclusivo. Após a criação bem-sucedida, o data.id na resposta é o ID do Project. Um novo projeto vazio pode não ter version_id antes do primeiro salvamento.
state completo. Um novo projeto vazio retorna {"tracks":[],"timing":{"bps":2}}, que pode ser usado diretamente para o primeiro salvamento. timing.bps representa as batidas por segundo, com padrão de 2 (120 BPM), e deve ser positivo; startBeats, endBeats e readStartBeats dos trechos usam a unidade de batidas do projeto, e não é possível tratar diretamente as posições de compassos na análise de áudio como coordenadas da linha do tempo.
Salvar o estado completo
version_id; após o primeiro salvamento gerar uma versão, os salvamentos subsequentes devem enviar o valor mais recente. Se a versão tiver mudado, a interface retornará HTTP 409. Nesse caso, execute retrieve novamente, mescle as modificações e envie-as com uma nova chave de idempotência; não tente novamente cegamente a solicitação antiga.
Carregar e adicionar faixas
response.data.candidate.audio_id. Em seguida, adicione-o ao projeto:
timing.bps do projeto. Após cada save, add_track, commit_candidate ou remove_track, o novo version_id na resposta deve ser usado.
Gerar e substituir
generate_track gera candidatos de faixa de áudio para um intervalo do projeto; replace_section retorna dois candidatos de substituição local. Nenhuma das duas operações seleciona automaticamente o resultado artístico. O modelo deve usar nomes públicos: chirp-v3-5, chirp-v4, chirp-v4-5, chirp-v4-5-plus, chirp-v5, chirp-v5-5, chirp-v6, chirp-v6-wild ou chirp-v6-mini; a disponibilidade para operações específicas ainda depende do estado final da tarefa, e nomes não suportados retornarão 400 antes do envio. Não haverá mudança automática para outro modelo.
generate_track também deve fornecer render_audio_id (áudio de exportação do projeto concluído), stem_control_tags e o áudio de origem source_audio_id. batch_size é de 1–4, com padrão de 2; start_seconds e end_seconds são os segundos do áudio de origem. O intervalo de substituição com fixed=true deve ser menor que 26 segundos.
Após selecionar um candidato, confirme-o:
start_beats nem end_beats. Candidatos de nova faixa devem ser confirmados em uma faixa vazia salva antecipadamente, usando por padrão o ponto inicial do trecho de origem, ou enviando explicitamente um intervalo sem sobreposição; trechos existentes sobrepostos na mesma faixa retornarão 400. Não gere primeiro e crie uma nova faixa depois, caso contrário a mudança de versão fará o candidato expirar.
Exportar a música completa
start_beats e end_beats são omitidos, o padrão é exportar desde o ponto inicial mais cedo até o ponto final mais tardio de todos os trechos audíveis; faixas/trechos silenciosos não participam e, quando existem faixas solo, apenas as faixas solo são selecionadas. Um projeto vazio ou sem faixas audíveis válidas retorna 400. O resultado em estado final contém render_id, audio_id, audio_url e duração. O projeto é vinculado ao ambiente de execução no momento da criação, e não pode ser migrado entre ambientes ou ter failover automático.
Apenas faça upload ou processe áudios para os quais você tenha direito legal de uso. A API de projetos está atualmente em Beta; persista as URLs finais de áudio nos resultados importantes.
Consulta e recuperação de falhas
/suno/tasks. As tarefas de Projects indicam sucesso quando finished_at existe e response.success=true; response.success=false indica falha. O retorno HTTP 200 ou task_id na submissão apenas representa que foi aceita, não que o áudio está concluído.
A mesma Idempotency-Key com a mesma solicitação retornará o resultado original (incluindo falhas), e não gerará novamente nem cobrará em duplicidade automaticamente. Para tentar novamente explicitamente uma operação que falhou, primeiro consulte a tarefa original para confirmar a falha e, então, use uma nova chave; não reenvie enquanto a tarefa original ainda estiver em processamento ou o resultado for incerto.
As categorias de erro incluem studio_unavailable / studio_model_unavailable (503, temporariamente incapaz de processar ou modelo indisponível), studio_model_unsupported (400, o modelo não oferece suporte à operação), studio_state_invalid (400, o estado do projeto ou o escopo de exportação é inválido), too_many_requests (429), studio_audio_unavailable (403, o áudio referenciado não pode ser usado para exportação do projeto) e content_rejected (403). Preserve trace_id para investigação.