> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # Guia de integração do projeto Suno Studio > Suno Music Generation API guide - Ace Data Cloud A API de projetos do Suno Studio gerencia projetos de música multifaixa por meio de um único endpoint: ```http theme={null} POST /suno/projects Authorization: Bearer YOUR_API_KEY Content-Type: application/json ``` O `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 | action | Modo | Finalidade | | - | - | - | | `create` | Síncrono | Criar um projeto vazio | | `retrieve` | Síncrono | Ler o projeto e o `state` completo editável | | `save` | Síncrono | Salvar o estado completo do projeto | | `upload` | Assíncrono | Inicializar, a partir de um endereço de áudio HTTPS, um material que pode ser adicionado ao projeto | | `add_track` | Assíncrono | Adicionar áudio existente ao projeto | | `generate_track` | Assíncrono | Gerar novos candidatos de faixa de áudio para um intervalo especificado | | `replace_section` | Assíncrono | Gerar candidatos de substituição local | | `commit_candidate` | Assíncrono | Confirmar o candidato selecionado no projeto | | `remove_track` | Síncrono | Excluir a faixa especificada | | `render` | Assíncrono | Exportar uma versão salva como uma música completa | 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 ```json theme={null} { "action": "create", "title": "My Studio Project" } ``` Todas as operações de modificação devem enviar um Header `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. ```json theme={null} {"action":"retrieve","id":"PROJECT_ID"} ``` A resposta de leitura contém o `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 ```json theme={null} { "action":"save", "id":"PROJECT_ID", "version_id":"CURRENT_VERSION_ID", "title":"Edited Project", "state":{"tracks":[],"timing":{"bps":2}} } ``` O primeiro salvamento de um novo projeto vazio pode omitir `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 ```json theme={null} { "action":"upload", "id":"PROJECT_ID", "version_id":"CURRENT_VERSION_ID", "audio_url":"https://cdn.example.com/reference.mp3", "async":true } ``` Após o upload bem-sucedido, leia o ID do áudio em `response.data.candidate.audio_id`. Em seguida, adicione-o ao projeto: ```json theme={null} { "action": "add_track", "id": "PROJECT_ID", "version_id": "CURRENT_VERSION_ID", "audio_id": "AUDIO_ID", "name": "Backing Vocals" } ``` A adição de faixa preserva por padrão a velocidade de reprodução do áudio e converte a duração do áudio em número de batidas de acordo com o `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. ```json theme={null} { "action":"replace_section", "id":"PROJECT_ID", "version_id":"CURRENT_VERSION_ID", "source_audio_id":"AUDIO_ID", "start_seconds":35.12, "end_seconds":48.76, "model":"chirp-v6", "replacement_lyrics":"novo trecho de letra", "async":true } ``` `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: ```json theme={null} { "action":"commit_candidate", "id":"PROJECT_ID", "version_id":"CURRENT_VERSION_ID", "operation_id":"OPERATION_ID", "candidate_id":"CANDIDATE_ID", "track_id":"TRACK_ID" } ``` Os candidatos estão vinculados à versão do projeto no momento da geração. Quando o projeto já tiver mudado, candidatos antigos não poderão ser confirmados diretamente. Candidatos de substituição local são confirmados na faixa original que contém o único trecho de origem; candidatos de take completo mantêm a posição original e substituem o trecho original; candidatos de intervalo substituem apenas o intervalo solicitado e preservam os trechos anteriores e posteriores. Quando não for possível corresponder de forma confiável à duração, é retornado 400 e o projeto original é preservado; nesse caso, não envie `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 ```json theme={null} { "action":"render", "id":"PROJECT_ID", "version_id":"CURRENT_VERSION_ID", "title":"Final Mix", "lyrics":"[Instrumental]", "async":true, "callback_url":"https://example.com/webhooks/suno" } ``` O servidor lê o estado autoritativo do projeto da versão especificada e monta os parâmetros de exportação. Quando `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 ```json theme={null} { "action": "retrieve", "id": "TASK_ID" } ``` Envie a solicitação acima para `/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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.