> ## 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.

# Instruções de integração da API de geração de músicas Suno

> Suno Music Generation API guide - Ace Data Cloud

Com a aplicação da IA se tornando mais ampla, vários programas de IA já se popularizaram gradualmente. A IA já se aprofundou gradualmente em todos os aspectos do trabalho e da vida das pessoas. E os setores envolvidos pela IA também estão se tornando cada vez mais numerosos, desde a escrita inicial, passando pela saúde e educação, até agora a música.

Suno é uma plataforma profissional e de alta qualidade de criação de músicas e composições musicais com IA. Os usuários só precisam inserir simples palavras de instrução em texto para gerar músicas com vocais de acordo com o estilo do gênero e as letras. Este gerador de música com IA foi desenvolvido por membros de equipe de conhecidas empresas de tecnologia como Meta, TikTok, Kensho etc., com o objetivo de não precisar de nenhuma ferramenta instrumental, permitindo que todos possam criar músicas maravilhosas.

A seguir está o progresso das atualizações do modelo:

| Versão | model | Data de lançamento | Limite de lyric | Limite de style | Duração máxima da música |
| - | - | - | - | - | - |
| v6 | chirp-v6 | 2026.09.09 | — | — | — |
| v6 Wild | chirp-v6-wild | 2026.09.09 | — | — | — |
| v6 Mini | chirp-v6-mini | 2026.09.09 | — | — | — |
| v5.5 | chirp-v5-5 | 2026.03.27 | 5000 | 1000 | 8 minutos |
| v5 | chirp-v5 | 2025.09.23 | 5000 | 1000 | 8 minutos |
| v4.5+ | chirp-v4-5-plus | 2025.07.17 | 5000 | 1000 | 8 minutos |
| v4.5 | chirp-v4-5 | 2025.05.03 | 5000 | 1000 | 4 minutos |
| v4 | chirp-v4 | 2024.12.17 | 3000 | 200 | 150 segundos |
| v3.5 | chirp-v3-5 | --- | 3000 | 200 | 120 segundos |

> Os limites de `lyric` e `style` na tabela acima são os limites máximos no modo personalizado (`custom` é `true`). O modo de inspiração não personalizado (`custom` é `false`) preenche apenas `prompt`, cujo limite de comprimento é de 500 caracteres (igual para todos os modelos).

Suno agora oferece suporte a `chirp-v6`, `chirp-v6-wild` e `chirp-v6-mini`. Recomenda-se usar `chirp-v6`; os nomes de modelos antigos continuam compatíveis.

No entanto, a Suno oficialmente não fornece uma API. A AceDataCloud fornece um conjunto de APIs da Suno, simulando a integração oficial da Suno, permitindo gerar de forma prática e rápida a música desejada.

## Solicitação e uso

Para usar a Suno Audios Generation API, primeiro acesse o [console Ace Data Cloud](https://platform.acedata.cloud/console/applications) para obter seu API Token e guarde-o para uso posterior.

![](https://cdn.acedata.cloud/dvc3cg.jpg)

Se você ainda não tiver feito login ou se registrado, será automaticamente redirecionado para a página de login, onde será convidado a se registrar e fazer login; após concluir, retornará automaticamente à página atual.

**Um único API Token pode chamar todos os serviços da plataforma, não sendo necessário solicitar um separadamente para cada serviço.** Na primeira solicitação, será concedida uma cota gratuita, permitindo uma experiência gratuita; quando a cota for insuficiente, você poderá recarregar o saldo geral no [console](https://platform.acedata.cloud/console/coin).

> 📘 Documentação completa: [Suno Audios Generation API →](https://platform.acedata.cloud/documents/suno-audios)

## Uso básico

Que tipo de música você quer? Você pode inserir livremente um trecho de texto. Por exemplo, se eu quiser gerar uma música sobre o Natal, posso inserir `a song for Christmas`, como mostrado na imagem:

![](https://cdn.acedata.cloud/2kuuup.png)

Podemos ver que aqui configuramos os Request Headers, incluindo:

* `accept`: qual formato de resultado de resposta se deseja receber; aqui é preenchido como `application/json`, ou seja, o formato JSON.
* `authorization`: a chave para chamar a API, que pode ser selecionada diretamente na lista suspensa após a solicitação.

Além disso, configuramos o Request Body, incluindo:

* `action`: tipo de tarefa de áudio, o padrão é `generate`. Suporta operações como geração, continuação, cover, concatenação, separação de faixas, adição de faixa de áudio, extração de uma faixa de áudio especificada, geração de efeitos sonoros e ajuste de velocidade, todas chamadas de forma unificada por meio de `POST /suno/audios`.
* `prompt`: prompt do modo de inspiração oficial do Suno (válido quando `custom` é `false`), máximo de 500 caracteres.
* `model`: o modelo para esta tarefa de geração de música. A série v6 inclui `chirp-v6`, `chirp-v6-wild` e `chirp-v6-mini`; os nomes de modelos antigos continuam compatíveis.
* `max_mode`: modo de geração aprimorado. `generate` é habilitado apenas quando `custom` e `max_mode` são ambos `true`, com custo de 1.12 Credits; `add_stem` pode ser habilitado diretamente, com custo de 1.344 Credits. Quando desativado ou omitido, os custos são 0.56 e 0.672 Credits, respectivamente.
* `variety`: intensidade da diversidade dos resultados gerados, com opções `off`, `normal`, `high`, `extra`, `max`. Usado apenas para `generate` e `add_stem`; passá-lo para outros actions retornará 400.
* `lyric`: conteúdo da letra no modo personalizado oficial do Suno. `chirp-v3-5` e `chirp-v4` têm máximo de 3000 caracteres; `chirp-v4-5` e superiores (incluindo `chirp-v5`, `chirp-v5-5`) têm máximo de 5000 caracteres.
* `custom`: se deve usar o modo personalizado, o padrão é: `false`.
* `instrumental`: opção de música instrumental no modo de inspiração oficial do Suno.
* `title`: título da música no modo personalizado oficial do Suno. `chirp-v3-5`, `chirp-v4` têm máximo de 80 caracteres; `chirp-v4-5` e superiores têm máximo de 100 caracteres.
* `style`: estilo musical do modo personalizado oficial do Suno. `chirp-v3-5` e `chirp-v4` têm máximo de 200 caracteres; `chirp-v4-5` e superiores (incluindo `chirp-v5`, `chirp-v5-5`) têm máximo de 1000 caracteres.
* `negative_tags`: estilos musicais ou gêneros que se deseja excluir dos resultados gerados no modo personalizado (`custom` é `true`).
* `audio_weight`: peso de influência de características de áudio ou voz, intervalo de 0-1, sendo que `0` também é um valor válido. Pode ser usado em operações como geração, continuação, cover, adição de faixa de áudio e consistência de voz; quando não há áudio de referência ou características de voz, o modelo pode enfraquecer ou ignorar esse valor.
* `audio_id`: ID da música de referência.
* `overpainting_start`/`overpainting_end`: horários de início e fim para adicionar vocais a uma música instrumental existente, em segundos.
* `underpainting_start`/`underpainting_end`: horários de início e fim para adicionar acompanhamento a uma performance a cappella, em segundos.
* `persona_id`: ID da música do artista.
* `continue_at`: limite de continuação, em segundos. Por exemplo, 213.5 indica gerar o trecho seguinte a partir de 3 minutos e 33.5 segundos. `lyric` e `style` orientam apenas o novo conteúdo após o limite e não substituem a letra ou o canto antes do limite no áudio de origem.
* `style_influence`: influência de estilo no modo personalizado, intervalo de 0-1; quanto maior, geralmente mais fiel será ao estilo selecionado; `0` será transmitido como um valor válido.
* `replace_section_end`: tempo final do trecho de substituição.
* `replace_section_start`: tempo inicial do trecho de substituição.
* `vocal_gender`: controla a preferência por voz feminina ou masculina, voz feminina `f`, voz masculina `m`, válido para modelos 4.5 e superiores; é um item de preferência, não sendo garantido que seja seguido rigorosamente.
* `weirdness`: grau de estranheza no modo personalizado, intervalo de 0-1; quanto maior, geralmente mais criativo e experimental; `0` será transmitido como um valor válido.
* `duration`: duração esperada da música, em segundos, deve ser um inteiro, com intervalo de 10 a 360. Este parâmetro é usado para geração de música no modo personalizado (`custom` é `true`). É uma sugestão de preferência e não uma restrição rígida: o modelo a considerará, mas não garante atingi-la; a duração real do produto final é determinada pelo campo `duration` na resposta e normalmente é menor que o valor esperado.

### Escopo de aplicação dos parâmetros avançados

| Parâmetro | Valores | actions suportadas | Descrição |
| - | - | - | - |
| `weirdness` | 0-1 | Opcional | Ajusta a experimentalidade, `0` é um valor válido; o efeito depende da operação, modo e modelo |
| `style_influence` | 0-1 | Opcional | Ajusta a tendência de seguir o estilo, `0` é um valor válido; o efeito depende da operação, modo e modelo |
| `audio_weight` | 0-1 | Opcional | Ajusta a influência de características de áudio ou voz; pode ser ignorado pelo modelo sem informações de referência |
| `variety` | `off` / `normal` / `high` / `extra` / `max` | `generate`, `add_stem` | Ajusta a diversidade de estilos entre os resultados |
| `max_mode` | boolean | `generate` (requer `custom=true`), `add_stem` | Aprimora a consistência e cobra de acordo com o modo aprimorado |
| `vocal_gender` | `f` / `m` | Operações de geração que suportam controle vocal | Item de preferência, não sendo garantido que seja seguido rigorosamente |
| `duration` | Inteiro 10-360 | Opcional | Duração esperada; a operação, modo ou modelo específico pode ignorá-la |

A plataforma validará os tipos de parâmetros e os intervalos numéricos, mas não rejeitará esses itens de ajuste opcionais apenas porque o action é diferente; os efeitos específicos são determinados pela operação, modo e modelo.

* `lyric_prompt`: prompt para gerar letras, válido se e somente se `custom` for `true` e `lyric` não for enviado.
* `callback_url`: URL para a qual os resultados precisam ser retornados por callback.
* `async`: opcional; quando definido como `true`, a interface retorna imediatamente `task_id`, sem necessidade de fornecer `callback_url`, e os resultados podem ser obtidos posteriormente por polling por meio da interface de consulta de tarefa correspondente.

O código gerado é o seguinte:

![](https://cdn.acedata.cloud/1xehwl.png)

Você pode clicar no botão «Try» para testar a API diretamente, aguardar 1-2 minutos, e o resultado será o seguinte:

```json theme={null}
{
  "success": true,
  "task_id": "e72fb249-bd5b-4e2a-b20c-8a06fea5ac14",
  "trace_id": "7dbc5b6a-b2c0-4d85-9d39-fa8a8a785ccf",
  "data": [
    {
      "id": "b481b17a-bf50-4e10-8adc-4d5635050893",
      "title": "Sob o Visco",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-001",
      "lyric": "[Verso]\nFlocos de neve caindo no chão\nLuzes cintilantes por toda parte\nO aroma de pinho preenche o ar\nMagia de Natal em todos os lugares\n[Refrão]\nSob o visco esta noite\nCorações brilhando sob a suave luz do luar\nRisadas ecoam\nEspíritos radiantes\nÉ tempo de Natal\nParece tão certo\n[Verso 2]\nMeias penduradas ao brilho da lareira\nCalor por dentro enquanto os ventos frios sopram\nBiscoitos assando\nDoce deleite\nUma temporada de alegria brilhando intensamente\n[Refrão]\nSob o visco esta noite\nCorações brilhando sob a suave luz do luar\nRisadas ecoam\nEspíritos radiantes\nÉ tempo de Natal\nParece tão certo\n[Ponte]\nCanções natalinas cantadas à luz de velas\nEstrelas acima fazem o mundo parecer acolhedor\nPaz e amor\nUm credo da temporada\nPreenchendo corações com tudo de que precisamos\n[Refrão]\nSob o visco esta noite\nCorações brilhando sob a suave luz do luar\nRisadas ecoam\nEspíritos radiantes\nÉ tempo de Natal\nParece tão certo",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T15:59:32.468Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "prompt": "Uma canção para o Natal",
      "style": "festivo, alegre, vocais masculinos",
      "duration": 154.92
    },
    {
      "id": "fbf22dab-5e2b-4e02-84c0-6d7605f14c3d",
      "title": "Sob o Visco",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-002",
      "lyric": "[Verso]\nFlocos de neve caindo no chão\nLuzes cintilantes por toda parte\nO aroma de pinho preenche o ar\nMagia de Natal em todos os lugares\n[Refrão]\nSob o visco esta noite\nCorações brilhando sob a suave luz do luar\nRisadas ecoam\nEspíritos radiantes\nÉ tempo de Natal\nParece tão certo\n[Verso 2]\nMeias penduradas ao brilho da lareira\nCalor por dentro enquanto os ventos frios sopram\nBiscoitos assando\nDoce deleite\nUma temporada de alegria brilhando intensamente\n[Refrão]\nSob o visco esta noite\nCorações brilhando sob a suave luz do luar\nRisadas ecoam\nEspíritos radiantes\nÉ tempo de Natal\nParece tão certo\n[Ponte]\nCanções natalinas cantadas à luz de velas\nEstrelas acima fazem o mundo parecer acolhedor\nPaz e amor\nUm credo da temporada\nPreenchendo corações com tudo de que precisamos\n[Refrão]\nSob o visco esta noite\nCorações brilhando sob a suave luz do luar\nRisadas ecoam\nEspíritos radiantes\nÉ tempo de Natal\nParece tão certo",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T15:59:32.468Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "prompt": "Uma canção para o Natal",
      "style": "festivo, alegre, vocais masculinos",
      "duration": 158.48
    }
  ]
}
```

Pode-se ver que, neste momento, obtivemos o conteúdo de duas músicas, incluindo título, imagem de pré-visualização, letra, áudio, vídeo e outros conteúdos.

A descrição dos campos é a seguinte:

* success: se a geração foi bem-sucedida; se for bem-sucedida, será `true`, caso contrário será `false`
* data: é uma lista que contém as informações detalhadas das músicas geradas.
  * state: estado de geração da música, contendo principalmente quatro tipos, especificamente os seguintes:
    * succeeded: geração bem-sucedida
    * pending: na fila
    * running: em execução
    * error: falha
  * id: ID da música
  * title: o título da música
  * image\_url: a imagem de capa da música
  * lyric: a letra da música
  * audio\_url: o endereço de áudio final da música. A plataforma retornará prioritariamente o endereço do Ace Data Cloud CDN; se a persistência falhar, poderá retornar o endereço de mídia original, faça o download a tempo.
  * video\_url: o arquivo de vídeo da música; ao abri-lo, será um vídeo mp4.
  * created\_at: o horário de criação
  * model: o modelo usado, geralmente o modelo v3 mais recente
  * style: o estilo

## Geração personalizada

Se quiser gerar letras personalizadas, você pode inserir a letra:

Neste momento, o campo `lyric` pode receber conteúdo semelhante ao seguinte:

```
[Verse]\nSnowflakes falling all around\nGlistening white\nCovering the ground\nChildren laughing\nFull of delight\nIn this winter wonderland tonight\nSanta's sleigh\nUp in the sky\nRudolph's nose shining bright\nOh my\nHear the jingle bells\nRinging so clear\nBringing joy and holiday cheer\n[Verse 2]\nRoasting chestnuts by the fire's glow\nChristmas lights\nThey twinkle and show\nFamilies gathering with love and cheer\nSpreading warmth to everyone near
```

> Observação: na letra aqui, `\n` é um caractere de quebra de linha. Se você não souber como gerar a letra, pode usar a API de geração de letras fornecida pelo AceDataCloud para gerar letras por meio de um prompt; a API é [Suno Lyrics Generation API](https://platform.acedata.cloud/documents/suno-lyrics).

Em seguida, para gerar uma música personalizada com base na letra, no título e no estilo, você pode especificar o seguinte conteúdo:

* lyric: texto da letra
* custom: preencha como `true`, representando a geração personalizada; este parâmetro é, por padrão, false, representando a geração usando `prompt`.
* title: o título da música.
* style: o estilo da música, opcional.

O exemplo de preenchimento é o seguinte:

![](https://cdn.acedata.cloud/qp3iba.png)

Após o preenchimento, o código é gerado automaticamente da seguinte forma:

![](https://cdn.acedata.cloud/o5haei.png)

O código correspondente:

```shell theme={null}
curl -X POST 'https://api.acedata.cloud/suno/audios' \
-H 'accept: application/json' \
-H 'authorization: Bearer {token}' \
-H 'content-type: application/json' \
-d '{
  "action": "generate",
  "prompt": "A song for Christmas",
  "model": "chirp-v4-5",
  "lyric": "[Verse]\\nSnowflakes falling all around\\nGlistening white\\nCovering the ground\\nChildren laughing\\nFull of delight\\nIn this winter wonderland tonight\\nSanta's sleigh\\nUp in the sky\\nRudolph's nose shining bright\\nOh my\\nHear the jingle bells\\nRinging so clear\\nBringing joy and holiday cheer\\n[Verse 2]\\nRoasting chestnuts by the fire's glow\\nChristmas lights\\nThey twinkle and show\\nFamilies gathering with love and cheer\\nSpreading warmth to everyone near",
  "custom": true
}'
```

O teste é permitido, e o efeito gerado é semelhante.

## Funcionalidade de geração personalizada de estilo de cantor

Se você quiser usar o estilo de cantor para gerar músicas, primeiro gere uma música por meio do uso básico acima,
por fim, é necessário configurar esta música como estilo de cantor, então é necessário acessar a [Suno Persona API](https://platform.acedata.cloud/documents/suno-persona) para gerar um parâmetro de id de estilo de cantor `persona_id` com base no ID da música gerada oficialmente `audio_id`, os parâmetros específicos são mostrados na imagem abaixo:

![](https://cdn.acedata.cloud/pmzo3l.png)

Após preencher, o código é gerado automaticamente da seguinte forma:

![](https://cdn.acedata.cloud/a5g0nj.png)

O código Python correspondente:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/persona"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "audio_id": "97efc9f4-0e8d-4b3e-88df-14568fa1b11f",
    "name": "test"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

Clique em executar e você poderá ver que obterá um resultado, como segue:

```json theme={null}
{
  "success": true,
  "task_id": "7628b754-4fe7-4e79-bda4-806d0dd8bf6e",
  "data": {
    "persona_id": "e0d7319e-aa2a-44cb-b00a-916218d7cb0b"
  }
}
```

Usamos o `audio_id` e o `persona_id` acima, respectivamente `97efc9f4-0e8d-4b3e-88df-14568fa1b11f` e `e0d7319e-aa2a-44cb-b00a-916218d7cb0b`, como dados de exemplo desta vez. Em seguida, você pode definir o parâmetro `action` como `artist_consistency` (se for o novo estilo de cantor Persona-v2-vox, `action` deve ser definido como `artist_consistency_vox`), e inserir o ID da música que precisa continuar sendo gerada e o ID do estilo de cantor, o exemplo de preenchimento é o seguinte:

![](https://cdn.acedata.cloud/fukijq.png)

Após preencher, o código é gerado automaticamente da seguinte forma:

![](https://cdn.acedata.cloud/5uzk9d.png)

O código Python correspondente:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "artist_consistency",
    "prompt": "A song for Christmas",
    "model": "chirp-v4-5",
    "persona_id": "e0d7319e-aa2a-44cb-b00a-916218d7cb0b",
    "audio_id": "97efc9f4-0e8d-4b3e-88df-14568fa1b11f"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

Clique em executar e você poderá ver que obterá um resultado, como segue:

```json theme={null}
{
  "success": true,
  "task_id": "9b732b1a-bd67-48bc-95e4-90140e06836f",
  "trace_id": "30fcd88e-7687-4137-92d7-913b58115204",
  "data": [
    {
      "id": "727a36e2-8dce-4df7-99e5-14e44635c80f",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-003",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T16:27:33.979Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 244.4
    },
    {
      "id": "3b33301a-b17e-4b25-8842-09b46dab1a36",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-004",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T16:27:33.979Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 229.88
    }
  ]
}
```

Pode-se ver que o conteúdo do resultado é consistente com o acima, o que implementa a funcionalidade de gerar músicas usando o estilo de cantor.

## Funcionalidade de continuar gerando

Se quiser continuar gerando uma música Suno já gerada, você pode definir o parâmetro `action` como `extend` e inserir o ID da música que precisa continuar sendo gerada. O ID da música é obtido com base no uso básico; pelo texto acima, pode-se saber que, neste momento, o ID da música é:

```
"id": "97efc9f4-0e8d-4b3e-88df-14568fa1b11f"
```

> Observe que aqui o `id` na letra é o ID da música após a geração. Se você não souber como gerar uma música, pode consultar o uso básico acima para gerar uma música.

Se quiser continuar gerando uma música enviada por você mesmo, você pode definir o parâmetro `action` como `upload_extend` e inserir o ID da música enviada personalizada que precisa continuar sendo gerada. O ID da música é obtido usando a [Suno Upload Generation API](https://platform.acedata.cloud/documents/suno-upload), como mostrado na imagem abaixo:

![](https://cdn.acedata.cloud/a0mn5e.png)

Em seguida, é necessário preencher a letra do trecho de continuação, e é possível especificar o estilo:

* lyric: usado apenas para orientar a letra do trecho recém-gerado após `continue_at`, não substituirá a letra antes desse ponto no tempo no áudio de origem.
* custom: preencha com `true`, representando a geração personalizada; esse parâmetro é false por padrão, representando a geração usando `prompt`.
* style: o estilo da música do trecho de continuação, opcional.
* continue\_at: limite de continuação, em segundos. Por exemplo, 213.5 representa gerar o trecho subsequente a partir de 3 minutos e 33,5 segundos.

> `extend` é usado para continuar criando a partir de uma música existente, não para trocar a letra de toda a música. Se desejar usar uma nova letra para toda a música desde o início, use `generate` para gerar novamente; se desejar reinterpretar com referência a uma música existente, pode usar `cover`. Ao enviar uma letra nova completa, a letra original antes de `continue_at` ainda não será substituída.

O exemplo de preenchimento é o seguinte:

![](https://cdn.acedata.cloud/zp9s42.png)

Após preencher, o código é gerado automaticamente da seguinte forma:

![](https://cdn.acedata.cloud/wwpw78.png)

O que se mantém abaixo é um instantâneo de uma chamada histórica real, em que `continue_at` é de 2 segundos; portanto, apenas os primeiros 2 segundos pertencem ao conteúdo original antes do limite da continuação. Ao continuar próximo ao final da música, esse valor deve ser definido como o segundo esperado para iniciar a continuação, e apenas o novo trecho a ser cantado após o limite deve ser fornecido em `lyric`.

O código Python correspondente:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "extend",
    "prompt": "A song for Christmas",
    "model": "chirp-v4-5",
    "audio_id": "97efc9f4-0e8d-4b3e-88df-14568fa1b11f",
    "continue_at": 2,
    "lyric": "[Verse]\\nSnowflakes falling all around\\nGlistening white\\nCovering the ground\\nChildren laughing\\nFull of delight\\nIn this winter wonderland tonight\\nSanta's sleigh\\nUp in the sky\\nRudolph's nose shining bright\\nOh my\\nHear the jingle bells\\nRinging so clear\\nBringing joy and holiday cheer\\n[Verse 2]\\nRoasting chestnuts by the fire's glow\\nChristmas lights\\nThey twinkle and show\\nFamilies gathering with love and cheer\\nSpreading warmth to everyone near",
    "custom": True,
    "instrumental": False
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

Clique em executar e será possível ver que um resultado será obtido, como segue:

```json theme={null}
{
  "success": true,
  "task_id": "75b835d9-30d1-4641-8524-0aeedbdc9e1a",
  "trace_id": "44c41045-a2e1-4d19-aafc-7abd239d0d5c",
  "data": [
    {
      "id": "0a1e1b10-c36a-41c9-9bfb-b26d9d25db98",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-005",
      "lyric": "[Verse]\\nSnowflakes falling all around\\nGlistening white\\nCovering the ground\\nChildren laughing\\nFull of delight\\nIn this winter wonderland tonight\\nSanta's sleigh\\nUp in the sky\\nRudolph's nose shining bright\\nOh my\\nHear the jingle bells\\nRinging so clear\\nBringing joy and holiday cheer\\n[Verse 2]\\nRoasting chestnuts by the fire's glow\\nChristmas lights\\nThey twinkle and show\\nFamilies gathering with love and cheer\\nSpreading warmth to everyone near",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T16:38:35.509Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 165.92
    },
    {
      "id": "4334c5b4-0a44-4b26-a8f6-66cc4dbb8fc3",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-006",
      "lyric": "[Verse]\\nSnowflakes falling all around\\nGlistening white\\nCovering the ground\\nChildren laughing\\nFull of delight\\nIn this winter wonderland tonight\\nSanta's sleigh\\nUp in the sky\\nRudolph's nose shining bright\\nOh my\\nHear the jingle bells\\nRinging so clear\\nBringing joy and holiday cheer\\n[Verse 2]\\nRoasting chestnuts by the fire's glow\\nChristmas lights\\nThey twinkle and show\\nFamilies gathering with love and cheer\\nSpreading warmth to everyone near",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T16:38:35.509Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 158.84
    }
  ]
}
```

É possível ver que `lyric` no resultado retornará o texto da letra usado nesta tarefa de continuação. Esse campo não é uma transcrição literal do áudio final completo; para `extend`, o áudio de origem antes de `continue_at` continua usando a letra original, e a nova letra é usada apenas para orientar o trecho de continuação.

## Obter a música completa

O resultado de `extend` do modelo atual normalmente já inclui o áudio de origem antes de `continue_at` e o novo conteúdo após o limite; primeiro, determine se já é a música completa com base na duração real e no conteúdo do áudio retornado. Se o retorno for um trecho de continuação independente, ou se for necessário mesclar explicitamente o histórico de várias continuações em uma única música, use então a funcionalidade de concatenação:

* action: o conteúdo é `concat`.
* audio\_id: o ID do último trecho de continuação.

Por exemplo, se o ID da música expandida for: 0a1e1b10-c36a-41c9-9bfb-b26d9d25db98, então os parâmetros podem ser definidos da seguinte forma:

```json theme={null}
{
  "action": "concat",
  "audio_id": "0a1e1b10-c36a-41c9-9bfb-b26d9d25db98"
}
```

Os outros parâmetros permanecem inalterados, e o retorno será uma música completa, ou seja, o resultado da concatenação de todos os trechos da música, mas o resultado terá apenas uma música, como no exemplo a seguir:

```json theme={null}
{
  "success": true,
  "task_id": "0f794915-8418-4124-93f5-b7eb3a417167",
  "trace_id": "62afcce0-e7e5-44b8-8c2e-4bba12a4f414",
  "data": [
    {
      "id": "0efec7e0-11bf-4313-9981-2c0e7218d7dd",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-007",
      "lyric": "[Verse]\\nSnowflakes falling all around\\nGlistening white\\nCovering the ground\\nChildren laughing\\nFull of delight\\nIn this winter wonderland tonight\\nSanta's sleigh\\nUp in the sky\\nRudolph's nose shining bright\\nOh my\\nHear the jingle bells\\nRinging so clear\\nBringing joy and holiday cheer\\n[Verse 2]\\nRoasting chestnuts by the fire's glow\\nChristmas lights\\nThey twinkle and show\\nFamilies gathering with love and cheer\\nSpreading warmth to everyone near\n[Verse]\\nSnowflakes falling all around\\nGlistening white\\nCovering the ground\\nChildren laughing\\nFull of delight\\nIn this winter wonderland tonight\\nSanta's sleigh\\nUp in the sky\\nRudolph's nose shining bright\\nOh my\\nHear the jingle bells\\nRinging so clear\\nBringing joy and holiday cheer\\n[Verse 2]\\nRoasting chestnuts by the fire's glow\\nChristmas lights\\nThey twinkle and show\\nFamilies gathering with love and cheer\\nSpreading warmth to everyone near",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T16:43:06.718Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 167.91997916666668,
      "concat_history": [
        {
          "continue_at": 2,
          "id": "97efc9f4-0e8d-4b3e-88df-14568fa1b11f",
          "infill": false,
          "source": "web",
          "type": "gen"
        },
        {
          "id": "0a1e1b10-c36a-41c9-9bfb-b26d9d25db98"
        }
      ]
    }
  ]
}
```

## Versão cover da música

Quando uma música é gerada com base em uma música original, o estilo da música retornada pode não ser muito adequado. Se quiser fazer uma versão cover da música gerada anteriormente (também há suporte para músicas personalizadas enviadas), é necessário usar o método de versão cover da música, e então é possível especificar o seguinte conteúdo:

* action: o conteúdo é `cover`; quando for realizar uma operação de versão cover em música personalizada enviada, deve obrigatoriamente especificar o conteúdo como: `upload_cover`.
* audio\_id: o ID da música gerada anteriormente.

Por exemplo, se o ID da música após a geração original for: 0a1e1b10-c36a-41c9-9bfb-b26d9d25db98, então os parâmetros podem ser definidos da seguinte forma:

```json theme={null}
{
  "action": "cover",
  "audio_id": "0a1e1b10-c36a-41c9-9bfb-b26d9d25db98",
  "prompt": "A song for Christmas",
  "model": "chirp-v4-5"
}
```

Os outros parâmetros permanecem inalterados, e o retorno será uma música após a versão cover, ou seja, o resultado da criação de uma versão cover da música gerada originalmente, conforme o exemplo a seguir:

```json theme={null}
{
  "success": true,
  "task_id": "b9d43d06-2e0a-4b5e-9e0d-7dfab32e00ab",
  "trace_id": "6c5e567d-0fdc-4c44-9b36-4090d9a75ff5",
  "data": [
    {
      "id": "6988fa57-f810-41cf-afab-7838db2c77dc",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-008",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T16:44:13.007Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 182.4
    },
    {
      "id": "ce98b991-0258-4f05-8245-e43d4efa8fb8",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-009",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-17T16:44:13.007Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 179.72
    }
  ]
}
```

O resultado gerado é semelhante ao descrito acima, concluindo assim o processo de geração de uma versão cover da música gerada originalmente.

## Substituir trecho

Quando, após gerar uma música, for necessário realizar uma segunda criação substituindo separadamente um trecho da música, é possível realizar uma operação de substituição em um determinado trecho da música.

> ⚠️ **Observação**: `replace_section_result_mode` tem como padrão `full_song`: o sistema concatena separadamente 2 candidatos recém-gerados e retorna 2 músicas completas. Se forem necessários apenas candidatos de trechos substituídos que ainda não foram concatenados, defina explicitamente como `candidates` e, em seguida, selecione um candidato para chamar [Concatenação de música](#音乐拼接).

A descrição dos parâmetros é a seguinte:

* action: o conteúdo é `replace_section`.
* audio\_id: o ID da música original (a música-fonte a ser substituída).
* model: modelo de geração de música.
* lyric: a letra completa após a substituição (incluindo o trecho substituído e seu contexto, mantendo-se consistente com o conteúdo em `prompt`).
* prompt: o novo trecho de letra que precisa ser substituído.
* style: o estilo da música, opcional.
* replace\_section\_start: o tempo inicial (segundos) do trecho substituído na música original.
* replace\_section\_end: o tempo final (segundos) do trecho substituído na música original.
* replace\_section\_result\_mode: modo de retorno, cujo padrão é `full_song`. `full_song` concatena separadamente 2 candidatos e retorna 2 músicas completas; `candidates` retorna 2 trechos candidatos que ainda não foram concatenados.

### Etapa um: iniciar a tarefa de substituição de trecho

Por exemplo, se o ID da música após a geração original for: 18db7ed0-2b8a-41db-91c1-b0781dcca0d4 (com duração de 94,12 segundos), e você desejar substituir o refrão entre o segundo 30 e o segundo 60 por uma nova letra, então os parâmetros podem ser definidos da seguinte forma:

```json theme={null}
{
  "action": "replace_section",
  "audio_id": "18db7ed0-2b8a-41db-91c1-b0781dcca0d4",
  "model": "chirp-v5-5",
  "custom": false,
  "instrumental": false,
  "lyric": "[Introdução]\nTambores e gongos ressoam, lanternas vermelhas estão penduradas bem alto\n[Verso 1]\nO som dos fogos de artifício despede o ano velho\nA brisa da primavera aquece e entra em milhares de lares\nEnvelopes vermelhos de Ano-Novo trazem sorrisos aos rostos\nA serpente dourada dança para celebrar a chegada da primavera\n[Refrão]\nFlores de ameixeira desabrocham, a atmosfera da primavera enche o chão\nFlores de ameixeira desabrocham, a atmosfera da primavera enche o chão\nFlores de ameixeira desabrocham, a atmosfera da primavera enche o chão\nFlores de ameixeira desabrocham, a atmosfera da primavera enche o chão\n[Verso 2]\nBolinho chinês perfumado no jantar de véspera de Ano-Novo\nLanternas balançam iluminando a reunião familiar",
  "prompt": "Flores de ameixeira desabrocham, a atmosfera da primavera enche o chão\nFlores de ameixeira desabrocham, a atmosfera da primavera enche o chão\nFlores de ameixeira desabrocham, a atmosfera da primavera enche o chão\nFlores de ameixeira desabrocham, a atmosfera da primavera enche o chão",
  "replace_section_start": 30.0,
  "replace_section_end": 60.0,
  "replace_section_result_mode": "full_song"
}
```

Por padrão, são retornadas 2 músicas completas, cada uma concatenada a partir de dois candidatos. Se `replace_section_result_mode` for definido como `candidates`, serão retornados 2 trechos de substituição ainda não concatenados, com a estrutura consistente com o exemplo abaixo:

```json theme={null}
{
  "success": true,
  "task_id": "dd067075-a295-4160-8375-d5504327d55b",
  "trace_id": "c34f589b-9195-4d0b-af78-9c890e77609c",
  "data": [
    {
      "id": "364f9d8b-ca25-463b-9a5e-d0b7139e2d6a",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-010",
      "image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-011",
      "lyric": "[Introdução]\nTambores e gongos ressoam, lanternas vermelhas estão penduradas bem alto\n[Verso 1]\nO som dos fogos de artifício despede o ano velho\nA brisa da primavera aquece e entra em milhares de lares\nEnvelopes vermelhos de Ano-Novo trazem sorrisos aos rostos\nA serpente dourada dança para celebrar a chegada da primavera\n[Refrão]\nFlores de ameixeira desabrocham, a atmosfera da primavera enche o chão\nFlores de ameixeira desabrocham, a atmosfera da primavera enche o chão\nFlores de ameixeira desabrocham, a atmosfera da primavera enche o chão\nFlores de ameixeira desabrocham, a atmosfera da primavera enche o chão\n[Verso 2]\nBolinho chinês perfumado no jantar de véspera de Ano-Novo\nLanternas balançam iluminando a reunião familiar",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2026-05-06T06:55:00.000Z",
      "model": "chirp-v5-5",
      "state": "succeeded",
      "style": "",
      "duration": 45.16
    },
    {
      "id": "fae966ea-5f7f-4e80-9962-1c57963c7f8a",
      "title": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "model": "chirp-v5-5",
      "state": "succeeded",
      "duration": 33.8
    }
  ]
}
```

No modo `candidates`, as durações dos dois áudios retornados (45,16 segundos, 33,8 segundos) são muito menores do que a música original (94,12 segundos). Eles são trechos de substituição que incluem uma pequena quantidade de contexto e **não são** a música completa. É possível selecionar um candidato satisfatório e continuar a concatená-lo manualmente. O modo padrão `full_song`, por sua vez, concluirá duas concatenações e retornará diretamente 2 músicas completas.

### Retornar diretamente músicas completas

Se desejar obter diretamente músicas completas, você pode definir `replace_section_result_mode` como `full_song` na etapa um. A interface concatenará separadamente os dois candidatos e retornará 2 músicas completas; nesse caso, não é necessário chamar `concat` novamente.

### Etapa dois: concatenar o trecho de substituição de volta à música original

Para o trecho selecionado acima (por exemplo, `364f9d8b-ca25-463b-9a5e-d0b7139e2d6a`), inicie uma tarefa `concat` conforme o método da seção [Concatenação de música](#concatenação-de-música):

```json theme={null}
{
  "action": "concat",
  "audio_id": "364f9d8b-ca25-463b-9a5e-d0b7139e2d6a",
  "model": "chirp-v5-5"
}
```

O retorno é a música completa já concatenada, conforme o exemplo abaixo:

```json theme={null}
{
  "success": true,
  "task_id": "5dbd4a78-0197-4ef3-9c16-8bddaf4f0c94",
  "trace_id": "580bd1da-2ad3-4d75-be1f-6c14bd4b489d",
  "data": [
    {
      "id": "365a9640-0452-4567-80f0-4f5a2a17ddd5",
      "title": "Feliz Ano-Novo",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-012",
      "lyric": "[Introdução]\nTambores e gongos ressoam, lanternas vermelhas estão penduradas bem alto\n[Verso 1]\nO som dos fogos de artifício despede o ano velho\nA brisa da primavera aquece e entra em milhares de lares\nEnvelopes vermelhos de Ano-Novo trazem sorrisos aos rostos\nA serpente dourada dança para celebrar a chegada da primavera\n[Refrão]\nFlores de ameixeira desabrocham, a atmosfera da primavera enche o chão\nFlores de ameixeira desabrocham, a atmosfera da primavera enche o chão\nFlores de ameixeira desabrocham, a atmosfera da primavera enche o chão\nFlores de ameixeira desabrocham, a atmosfera da primavera enche o chão\n[Verso 2]\nBolinho chinês perfumado no jantar de véspera de Ano-Novo\nLanternas balançam iluminando a reunião familiar",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2026-05-06T06:56:46.057Z",
      "model": "chirp-v5-5",
      "state": "succeeded",
      "style": "Ano-Novo chinês tradicional, festivo, vocais femininos, animado",
      "duration": 105.28
    }
  ]
}
```

Neste momento, `duration` foi restaurado para a duração completa da música (105,28 segundos, aproximadamente igual à duração da música original), e `audio_url` aponta para a música completa após a substituição. Isso conclui o processo de criação secundária de "gerar → substituir trecho → unir música completa".

## Separação de vocais e música

Quando, após gerar uma música, for necessário realizar uma criação secundária com operações separadas de acompanhamento e vocais, é possível separar o acompanhamento puramente instrumental e os vocais a cappella. É possível especificar o seguinte conteúdo:

* action: o conteúdo é `stems`.
* audio\_id: o ID da música gerada anteriormente.

Por exemplo, se o ID da música gerada anteriormente for: ec13e502-d043-4eb2-92ee-e900c6da69d1, então os parâmetros podem ser definidos da seguinte forma:

```json theme={null}
{
  "action": "stems",
  "audio_id": "ec13e502-d043-4eb2-92ee-e900c6da69d1"
}
```

Por meio dos parâmetros acima, é possível obter o resultado da separação de vocais e música, conforme segue:

```json theme={null}
{
  "success": true,
  "task_id": "4050affc-f8a6-4cba-a86c-bf201eed053d",
  "trace_id": "5107ee58-687d-422f-9195-fa0e82e1fcc8",
  "data": [
    {
      "id": "e3de0928-085a-42c4-b982-3b24738d1989",
      "title": "Deck the Sky - Vocals",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-013",
      "lyric": "[Verse]\nSnowflakes dance on rooftops high\nChildren's laughter fills the sky\nCarols ring from church bells loud\nHolidays a joyful crowd\n[Verse 2]\nCandy canes and cocoa warm\nWrapped up tight in our own storm\nStockings hung with dreams and cheer\nMagic growing every year\n[Chorus]\nDeck the sky with twinkling stars\nHoliday joy feels ours and ours\nSing the songs of love and light\nChristmas glows so pure and bright\n[Verse 3]\nFireside tales of long ago\nReindeer prance in icy glow\nEvergreen and tinsel’s gleam\nChristmas time a lovely dream\n[Bridge]\nHearts are full with friends and kin\nMistletoe for love to win\nGifts of love and hope we share\nChristmas spirit everywhere\n[Chorus]\nDeck the sky with twinkling stars\nHoliday joy feels ours and ours\nSing the songs of love and light\nChristmas glows so pure and bright",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-001",
      "created_at": "2025-01-05T07:49:16.881Z",
      "model": "",
      "state": "succeeded",
      "style": "holiday, jolly",
      "duration": 174.16
    },
    {
      "id": "ad5d7c89-709c-4eb4-a5a6-72f9f5e57fdb",
      "title": "Deck the Sky - Instrumental",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-014",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-002",
      "created_at": "2025-01-05T07:49:16.892Z",
      "model": "",
      "state": "succeeded",
      "style": "holiday, jolly",
      "duration": 174.16
    }
  ]
}
```

O resultado gerado é semelhante ao acima, concluindo assim o processo de separação de vocais e música da música originalmente gerada.

## Separação de vocais e música em todas as faixas

Quando, após gerar uma música, for necessário realizar uma operação de separação de vocais e música em todas as faixas, é possível especificar o seguinte conteúdo:

* action: o conteúdo é `all_stems`.
* audio\_id: o ID da música gerada anteriormente.

Por exemplo, se o ID da música gerada anteriormente for: bdf23a5a-59f5-4103-b452-054a824a7f9f, então os parâmetros podem ser definidos da seguinte forma:

```json { theme={null}
  "success": true,
  "task_id": "f4b16fb9-8478-4857-88c7-b9a1f0bb9518",
  "trace_id": "9c560ebd-4fc6-4bdb-988a-8890160a92fb",
  "data": [
    {
      "id": "f86ca64a-9519-4ea7-a592-52438e001412",
      "title": "安全之弦 (Vocals)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-015",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "99e649a7-a394-47b9-a915-d7f847285a36",
      "title": "安全之弦 (Backing Vocals)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-016",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "6d710bf7-809f-4fdc-bb63-b8cb3a456d42",
      "title": "安全之弦 (Drums)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-017",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    },
{
      "id": "e05f07e3-7d80-4713-8e51-7f176c733543",
      "title": "Cordas de Segurança (Baixo)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-018",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "93fe7cd8-62fd-4739-b78e-142c7e0b8562",
      "title": "Cordas de Segurança (Guitarra)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-019",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "8367d71c-fdd3-441c-8ebe-70c33cca821b",
      "title": "Cordas de Segurança (Teclado)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-020",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "28c03590-731c-416e-8fd3-95cdb3d75043",
      "title": "Cordas de Segurança (Percussão)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-021",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "3d4c1a28-4e1c-485a-8201-d21bb93aca2f",
      "title": "Cordas de Segurança (Cordas)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-022",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "b9db8ded-01ec-4e37-b8a5-64aab3a814c2",
      "title": "Cordas de Segurança (Sintetizador)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-023",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "10a5248e-32e6-42b9-8da1-678a8a392aef",
      "title": "Cordas de Segurança (FX)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-024",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "2d272128-111f-4901-8f62-5ae1eb43095a",
      "title": "Cordas de Segurança (Metais)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-025",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "4a7c19a5-f8d4-4e4a-add9-aa0bad9307cc",
      "title": "Cordas de Segurança (Madeiras)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-026",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "1ca774f9-3e75-48a6-941b-808875eadcd2",
      "title": "Cordas de Segurança (Vozes)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-027",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.770Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    },
{
      "id": "14c5ffc7-addf-4fee-afd2-4b8b3e7ee470",
      "title": "Cordas de Segurança (Vocais de Apoio)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-028",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "9d044557-450d-48ab-90dc-8eaf6f1cdb6c",
      "title": "Cordas de Segurança (Bateria)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-029",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "efd052d0-c12f-47b3-8282-1f3ef7610e1f",
      "title": "Cordas de Segurança (Baixo)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-030",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "5775372b-292e-4420-96ef-60e57a60cc1f",
      "title": "Cordas de Segurança (Guitarra)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-031",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "dab3f220-19cd-408e-9b96-30ec18f5b049",
      "title": "Cordas de Segurança (Teclado)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-032",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "2d0cd6d4-af82-4bb5-86fe-d92bdb367157",
      "title": "Cordas de Segurança (Percussão)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-033",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "f3191a1a-5e8d-4afe-b638-3add222d52cd",
      "title": "Cordas de Segurança (Cordas)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-034",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "a8834ea5-200b-4206-a812-9780ef336660",
      "title": "Cordas de Segurança (Sintetizador)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-035",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "f50d1a31-ef72-400a-b8ae-0367849d007d",
      "title": "Cordas de Segurança (Efeitos)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-036",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }, {
      "id": "cb581673-23cc-40d6-9f9b-0f76720f0d18",
      "title": "Cordas de Segurança (Metais)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-037",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    },
{
      "id": "d91cfb52-f0a3-4546-bf8a-2ad14c3775a5",
      "title": "安全之弦 (Woodwinds)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-038",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-06-11T02:40:30.771Z",
      "model": "chirp-ahi-stem-12-t1",
      "state": "succeeded",
      "duration": 154.92
    }
  ]
}
```

O resultado gerado é semelhante ao acima, concluindo assim o processo de separação de voz e música da canção gerada anteriormente.

## Adicionar faixa de áudio

`add_stem` gera uma faixa de instrumento ou voz de destino para o áudio especificado, por meio da chamada `POST /suno/audios`.

* Obrigatórios: `action`, `audio_id`, `stem_type`.
* Opcionais: `model`, `prompt`, `title`, `style`, `negative_tags`, `weirdness`, `style_influence`, `audio_weight`, `max_mode`, `variety`.
* Cobrança: 0.672 Credits no modo normal; 1.344 Credits quando `max_mode` for `true`.

```json theme={null}
{
  "action": "add_stem",
  "audio_id": "dead4ee5-df4d-417b-8f7e-717722fae51a",
  "stem_type": "bass",
  "model": "chirp-v6",
  "prompt": "Add warm bass guitar",
  "style": "minimal piano pulse with warm bass guitar",
  "negative_tags": "vocals",
  "variety": "normal",
  "max_mode": false,
  "async": true
}
```

Resposta em estado final:

```json theme={null}
{
  "success": true,
  "task_id": "82851953-9590-4334-8bb8-ae30ccadc815",
  "trace_id": "862bbcce-1678-44ff-982d-8b439c126a5e",
  "data": [
    {
      "id": "0adc26ca-2720-4c69-b237-457a986d70e3",
          "audio_url": "https://cdn.acedata2.cloud/suno/0adc26ca-2720-4c69-b237-457a986d70e3.mp3",
      "model": "chirp-v6",
      "state": "succeeded",
      "duration": 12.8
    },
    {
      "id": "e2d39a6c-1d20-4a40-adaf-b2551815d869",
          "audio_url": "https://cdn.acedata2.cloud/suno/e2d39a6c-1d20-4a40-adaf-b2551815d869.mp3",
      "model": "chirp-v6",
      "state": "succeeded",
      "duration": 12.36
    }
  ],
  "cost": {"amount": 0.6048, "currency": "credit", "list_amount": 0.672}
}
```

## Extrair faixa de áudio

`extract_stem` extrai a faixa de áudio de destino do áudio especificado e, ao mesmo tempo, retorna a versão complementar após a remoção dessa faixa de áudio, por meio da chamada `POST /suno/audios`.

* Obrigatórios: `action`, `audio_id`, `stem_type`.
* Opcional: `audio_format`, o contrato público atual de canal duplo suporta apenas `mp3`.
* Cobrança: 1.12 Credits.

```json theme={null}
{
  "action": "extract_stem",
  "audio_id": "dead4ee5-df4d-417b-8f7e-717722fae51a",
  "stem_type": "bass",
  "audio_format": "mp3",
  "async": true
}
```

O `data` na resposta em estado final mantém uma lista plana de áudios, e `stem_sets` representa a relação correspondente entre a faixa de áudio de destino e a faixa de áudio complementar:

```json theme={null}
{
  "success": true,
  "task_id": "ae9557d0-4ff7-4a35-bcde-d881e78fbfe5",
  "trace_id": "82c51a55-7627-41a5-b72b-1b9775ca25f2",
  "data": [
    {"id":"3084d7e1-4278-4733-8b56-56f7ecf3f859","title":"(Bass)","audio_url":"https://cdn.acedata2.cloud/suno/3084d7e1-4278-4733-8b56-56f7ecf3f859.mp3","model":"chirp-v6","state":"succeeded","duration":12.8,"stem_set":1},
    {"id":"19b83ca9-a51d-494f-a41d-5b0957f3295e","title":"(Without Bass)","audio_url":"https://cdn.acedata2.cloud/suno/19b83ca9-a51d-494f-a41d-5b0957f3295e.mp3","model":"chirp-v6","state":"succeeded","duration":12.8,"stem_set":1},
    {"id":"7eb431e8-f4db-4915-902e-0e89d2b3185a","title":"(Bass)","audio_url":"https://cdn.acedata2.cloud/suno/7eb431e8-f4db-4915-902e-0e89d2b3185a.mp3","model":"chirp-v6","state":"succeeded","duration":12.8,"stem_set":2},
    {"id":"495d29cc-5790-4d0a-8b95-9551a6127b61","title":"(Without Bass)","audio_url":"https://cdn.acedata2.cloud/suno/495d29cc-5790-4d0a-8b95-9551a6127b61.mp3","model":"chirp-v6","state":"succeeded","duration":12.8,"stem_set":2}
  ],
  "stem_sets": [
    {"stem_type":"bass","isolated":{"id":"3084d7e1-4278-4733-8b56-56f7ecf3f859","state":"succeeded","stem_set":1},"remainder":{"id":"19b83ca9-a51d-494f-a41d-5b0957f3295e","state":"succeeded","stem_set":1}},
    {"stem_type":"bass","isolated":{"id":"7eb431e8-f4db-4915-902e-0e89d2b3185a","state":"succeeded","stem_set":2},"remainder":{"id":"495d29cc-5790-4d0a-8b95-9551a6127b61","state":"succeeded","stem_set":2}}
  ],
  "cost": {"amount": 1.008, "currency": "credit", "list_amount": 1.12}
}
```

## Gerar efeitos sonoros

`sounds` gera efeitos sonoros de uso único ou repetíveis com base em descrições textuais, por meio da chamada `POST /suno/audios`.

* Obrigatórios: `action`, `sound`, `sound_type`.
* Opcionais: `model`, `bpm`, `key`, `audio_format`; atualmente, `audio_format` suporta apenas `mp3`.
* `sound_type`: `one-shot` ou `loop`.
* Cobrança: 0.112 Credits.

```json theme={null}
{
  "action": "sounds",
  "sound": "single soft analog synth pluck, no reverb",
  "sound_type": "one-shot",
  "model": "chirp-v6",
  "bpm": 120,
  "key": "C",
  "audio_format": "mp3",
  "async": true
}
```

```json theme={null}
{
  "success": true,
  "task_id": "f6716546-d118-40a0-ad15-09999f9f22ba",
  "trace_id": "da4c7895-e494-4bd8-83bd-132e006c94e3",
  "data": [
    {"id":"b3cd3e7d-96e4-48ef-abde-73c7ddee8b4a","title":"single soft analog synth pluck, no reverb","audio_url":"https://cdn.acedata2.cloud/suno/b3cd3e7d-96e4-48ef-abde-73c7ddee8b4a.mp3","model":"chirp-v6","state":"succeeded","duration":10},
    {"id":"f1517867-b76a-4cdf-b006-9ce6e653e0a5","title":"single soft analog synth pluck, no reverb","audio_url":"https://cdn.acedata2.cloud/suno/f1517867-b76a-4cdf-b006-9ce6e653e0a5.mp3","model":"chirp-v6","state":"succeeded","duration":10}
  ],
  "cost": {"amount": 0.1008, "currency": "credit", "list_amount": 0.112}
}
```

## Ajustar a velocidade do áudio

`adjust_speed` ajusta a velocidade de reprodução do áudio especificado, por meio da chamada `POST /suno/audios`.

* Obrigatório: `action`, `audio_id`, `speed_multiplier`, `title`.
* Opcional: `keep_pitch`.
* `speed_multiplier`: intervalo de 0.25–4.
* Cobrança: 0.28 Credits.

```json theme={null}
{
  "action": "adjust_speed",
  "audio_id": "dead4ee5-df4d-417b-8f7e-717722fae51a",
  "speed_multiplier": 1.1,
  "keep_pitch": true,
  "title": "Suno contract verification speed 1.1x",
  "async": true
}
```

A duração do áudio de origem é de 9.8 segundos, e o resultado em 1.1x de velocidade é de 8.909090909 segundos:

```json theme={null}
{
  "success": true,
  "task_id": "c5860fdd-76b1-40a1-b5b5-ec047e471c8a",
  "trace_id": "292ed097-3631-441c-ac80-52f326b62726",
  "data": [
    {
      "id": "02534b52-45a7-4961-834a-f473a407e62c",
      "title": "Suno contract verification speed 1.1x",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3?example=audio-001",
      "model": "chirp-v6",
      "state": "succeeded",
      "duration": 8.909090909090908
    }
  ],
  "cost": {
    "amount": 0.252,
    "currency": "credit",
    "list_amount": 0.28
  }
}
```

O modelo de geração possui aleatoriedade. A interface garante a consistência da semântica dos parâmetros, do estado da tarefa e da estrutura da resposta, mas não garante que solicitações diferentes gerem formas de onda completamente idênticas.

## Parâmetros avançados para geração personalizada

O oficial permite usar os parâmetros avançados `weirdness`==>`Weirdness`, `style_influence`==>`Style Influence`, `audio_weight`==>`Audio Influence` no modo personalizado para realizar a geração, correspondendo aos seguintes exemplos oficiais:

![](https://cdn.acedata.cloud/1xonxy.png)

Os intervalos dos parâmetros avançados estão todos entre 0-1, e os parâmetros específicos são mostrados na imagem abaixo:

![](https://cdn.acedata.cloud/7i94ih.png)

Após o preenchimento, o código foi gerado automaticamente da seguinte forma:

![](https://cdn.acedata.cloud/2dlbo6.png)

O código Python correspondente:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "generate",
    "model": "chirp-v4-5",
    "lyric": "Hello Hello Hello ",
    "custom": True,
    "weirdness": 0.4,
    "style_influence": 0.4,
    "audio_weight": 0.4
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

Ao clicar em executar, é possível descobrir que será obtido um resultado, conforme abaixo:

```json theme={null}
{
  "success": true,
  "task_id": "2f3aa682-e1a7-43a9-9fbb-ed0ce8668a4b",
  "trace_id": "07408194-7deb-4a52-a36d-9a9a13143b5f",
  "data": [
    {
      "id": "c66e2077-7580-43f2-9937-c67a8afcd8bd",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-039",
      "lyric": "Hello Hello Hello ",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-07-10T12:54:35.199Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 187.92
    },
    {
      "id": "a922f97b-307c-4c4d-aae3-a47ba8202a10",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-040",
      "lyric": "Hello Hello Hello ",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-07-10T12:54:35.199Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "style": "",
      "duration": 229.64
    }
  ]
}
```

Dessa forma, os parâmetros avançados foram usados para gerar músicas personalizadas, e o resultado é semelhante ao descrito acima.

## Controlar a duração da música

Por padrão, a duração da música gerada é determinada pelo próprio modelo, geralmente entre 30 segundos e 4 minutos. Se for necessário um produto final mais longo ou mais curto, é possível especificar a duração desejada por meio do parâmetro `duration`, em segundos, com valores inteiros entre 10 e 360.

Este parâmetro é usado para a geração de músicas no modo personalizado (`custom` como `true`). É necessário destacar que `duration` é uma **indicação de tendência, e não uma restrição rígida**: o modelo fará referência a esse valor durante a criação, mas não garante que o atingirá. Em testes reais, a duração efetiva geralmente é significativamente menor que o valor esperado, e as durações das duas músicas retornadas pela mesma solicitação também podem diferir por várias vezes. Mesmo para solicitações completamente idênticas, as durações obtidas após vários envios também podem ter grandes diferenças. Portanto, não o utilize como um controle preciso de duração; se forem necessárias durações fixas para o negócio, corte ou tente novamente por conta própria após obter o produto final.

O código Python correspondente:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "generate",
    "model": "chirp-v5-5",
    "custom": True,
    "title": "Under the City Lights",
    "style": "lo-fi piano",
    "lyric": "[Verse]\nSunrise creepin\nGold on the floor\n[Chorus]\nUnder the city lights\n",
    "duration": 330
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

É importante observar que `duration` na solicitação é a **duração esperada**, enquanto o campo `duration` de cada música em `data` na resposta é a **duração real** daquela música. Os dois possuem o mesmo nome, mas significados diferentes; não é garantido que a duração real seja igual ao valor esperado. O comprimento da letra é um dos principais fatores que afetam a duração do produto final; se for necessário um produto final mais longo, recomenda-se também fornecer letras mais completas.

A interface validará que `duration` deve ser um número inteiro entre 10 e 360; ele ainda é apenas um objetivo de geração, não uma garantia da duração do produto final.

## Funcionalidade Add Instrumental

Em agosto de 2025, o Suno lançou a funcionalidade Add Instrumental. Primeiro, é necessário enviar uma música a cappella sem acompanhamento para que o Suno adicione a música. Primeiro, você pode acessar a [Suno Upload API](https://platform.acedata.cloud/documents/suno-upload) para enviar uma música a cappella sem acompanhamento; a operação correspondente é mostrada na imagem abaixo:

![](https://cdn.acedata.cloud/fxl914.png)

Em seguida, é necessário registrar o `audio_id` após o envio; o resultado específico é mostrado na imagem abaixo:

![](https://cdn.acedata.cloud/47t6wj.png)

Por fim, foi obtido um `audio_id`: 92254cab-3372-4d9e-bce9-cdcfdbc39070. Em seguida, também precisamos preencher os seguintes parâmetros:

* action: o conteúdo é `underpainting`.
* underpainting\_start: o horário de início para adicionar acompanhamento à música enviada; o valor padrão é 0.
* underpainting\_end: o horário de término para adicionar acompanhamento à música enviada; deve ser menor que a duração total da música.
* audio\_id: o ID da música a cappella sem acompanhamento enviada.
* style: o estilo do acompanhamento; é melhor não usar letras, afinal é para o acompanhamento.

Após preencher, o código é gerado automaticamente conforme abaixo:

![](https://cdn.acedata.cloud/8x1ic6.png)

O código Python correspondente:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "underpainting",
    "model": "chirp-v4-5",
    "style": "Pop rap, uplifting, magnetic male vocals, piano, synth, electric guitar, driving bass, clear structure",
    "audio_id": "92254cab-3372-4d9e-bce9-cdcfdbc39070",
    "underpainting_end": 120
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

Clique em executar e será possível ver que um resultado será obtido, conforme abaixo:

```json theme={null}
{
  "success": true,
  "task_id": "822d2e14-c535-4d48-a4e5-1b6ab00b04a7",
  "trace_id": "257eac2c-8e4f-44d0-8454-5e215111eefa",
  "data": [
    {
      "id": "2788cd21-bd84-422d-beb5-859c60fbf5b6",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-041",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-08-27T15:25:42.548Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "style": "Pop rap, uplifting, magnetic male vocals, piano, synth, electric guitar, driving bass, clear structure",
      "duration": 10.16
    },
    {
      "id": "a4bb7220-e971-4cbf-a626-b86c648bcf55",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-042",
      "lyric": "",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-08-27T15:25:42.548Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "style": "Pop rap, uplifting, magnetic male vocals, piano, synth, electric guitar, driving bass, clear structure",
      "duration": 2.52
    }
  ]
}
```

Dessa forma, a operação de adicionar acompanhamento à música a cappella sem acompanhamento enviada foi concluída, e o resultado é semelhante ao descrito acima.

## Funcionalidade Add Vocals

Em agosto de 2025, o Suno lançou a funcionalidade Add Vocals. Primeiro, é necessário enviar uma música puramente instrumental para que o Suno escreva a letra e gere vocais cantados. Primeiro, você pode acessar a [Suno Upload API](https://platform.acedata.cloud/documents/suno-upload) para enviar uma música a cappella sem acompanhamento; a operação correspondente é mostrada na imagem abaixo:

![](https://cdn.acedata.cloud/fxl914.png)

Em seguida, é necessário registrar o `audio_id` após o envio; o resultado específico é mostrado na imagem abaixo:

![](https://cdn.acedata.cloud/47t6wj.png)

Por fim, foi obtido um `audio_id`: 92254cab-3372-4d9e-bce9-cdcfdbc39070. Em seguida, também precisamos preencher os seguintes parâmetros:

* action: o conteúdo é `overpainting`.
* overpainting\_start: o horário de início para adicionar vocais à música enviada; o valor padrão é 0.
* overpainting\_end: o horário de término para adicionar vocais à música enviada; deve ser menor que a duração total da música.
* audio\_id: o ID da música a cappella sem acompanhamento enviada.
* custom: neste modo, é obrigatório usar o modo personalizado para inserir a letra.
* lyric: a letra preenchida no modo personalizado.
* style: o estilo do acompanhamento.

Após preencher, o código é gerado automaticamente conforme abaixo:

![](https://cdn.acedata.cloud/a4pbes.png)

O código Python correspondente:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "overpainting",
    "model": "chirp-v4-5",
    "lyric": "Yea your were the best I could get \\nBut I knew that it couldn’t last \\nStayed down since we were friends \\nHad to leave those thoughts in the past \\nMade like 40k just last week \\nOn top of the 20 with my babe\\ndon’t care for what niggas say",
    "custom": True,
    "audio_id": "92254cab-3372-4d9e-bce9-cdcfdbc39070",
    "overpainting_end": 120
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

Clique em executar, e você poderá ver que obterá um resultado, conforme abaixo:

```json theme={null}
{
  "success": true,
  "task_id": "31bb250e-6614-49ec-ac85-631f224daeba",
  "trace_id": "efe8e7f3-9a65-4f13-a9f8-51e8478899df",
  "data": [
    {
      "id": "a597f945-64df-4722-a631-d436450832bd",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-043",
      "lyric": "Yea your were the best I could get \\nBut I knew that it couldn’t last \\nStayed down since we were friends \\nHad to leave those thoughts in the past \\nMade like 40k just last week \\nOn top of the 20 with my babe\\ndon’t care for what niggas say",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-08-27T15:33:51.550Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "style": "",
      "duration": 105.32
    },
    {
      "id": "b41a8b91-3d88-4ebd-a6cf-732764b24954",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-044",
      "lyric": "Yea your were the best I could get \\nBut I knew that it couldn’t last \\nStayed down since we were friends \\nHad to leave those thoughts in the past \\nMade like 40k just last week \\nOn top of the 20 with my babe\\ndon’t care for what niggas say",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-08-27T15:33:51.550Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "style": "",
      "duration": 148.16
    }
  ]
}
```

Dessa forma, a operação de adicionar voz à música a cappella sem acompanhamento enviada foi concluída, e o resultado é semelhante ao anterior.

## Funcionalidade Remaster

Em dezembro de 2025, o suno lançou a funcionalidade Remaster. Essa funcionalidade pode gerar novamente músicas, não sendo possível entre contas, e então também precisamos preencher os seguintes parâmetros:

* action: o conteúdo é `remaster`.
* audio\_id: o ID da música que precisa ser gerada novamente.
* model: suporta apenas v4.5+ e v5.
* variation\_category: compatível apenas com versões v5 ou superiores, e possui apenas 3 valores: high, normal, subtle.

Após preencher, o código é gerado automaticamente conforme abaixo:

![](https://cdn.acedata.cloud/7h4zmw.png)

O código Python correspondente:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "remaster",
    "variation_category": "high",
    "audio_id": "21fd46d4-45c3-4826-bec9-3f3df667902e"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

Clique em executar, e você poderá ver que obterá um resultado, conforme abaixo:

```json theme={null}
{
  "success": true,
  "task_id": "791ee74c-9363-4352-afe7-babb19b89899",
  "trace_id": "77acda57-c3d4-4e11-a506-4f50e0609916",
  "data": [
    {
      "id": "b0515cdf-9cb5-46cd-b0fe-10a239dc9274",
      "title": "Navidad en costura  (Remastered)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-045",
      "image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-046",
      "lyric": "En Teror las clases siguen,\nni en Navidad hay parón;\ncose el grupo entre villancicos\ny un buen trocito de turrón.\nLa Popular abre sus puertas,\ny el taller suena mejor;\nhilo, aguja y canto alegre\nlo pasaremos mejor\nSeguimos en las costuras,\ncon música y diversión;\nlos alumnos comeremos\nGolosinas un montón ",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-12-04T13:09:59.936Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "style": "Villancico",
      "duration": 32.2
    },
    {
      "id": "06edab94-a4f9-4c0c-abac-a2e8a97c76a8",
      "title": "Navidad en costura  (Remastered)",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-047",
      "image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-048",
      "lyric": "En Teror las clases siguen,\nni en Navidad hay parón;\ncose el grupo entre villancicos\ny un buen trocito de turrón.\nLa Popular abre sus puertas,\ny el taller suena mejor;\nhilo, aguja y canto alegre\nlo pasaremos mejor\nSeguimos en las costuras,\ncon música y diversión;\nlos alumnos comeremos\nGolosinas un montón ",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2025-12-04T13:09:59.936Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "style": "Villancico",
      "duration": 32.2
    }
  ]
}
```

Dessa forma, a operação de gerar novamente uma música já gerada foi concluída, e o resultado é semelhante ao anterior.

## Funcionalidade de geração de mixagem Mashup

Em dezembro de 2025, o suno lançou a funcionalidade Mashup. Essa funcionalidade pode gerar músicas com base em duas músicas de referência, e então também precisamos preencher os seguintes parâmetros:

* action: o conteúdo é `mashup`.
* mashup\_audio\_ids: os IDs das duas músicas de referência.
  Após o preenchimento, o código a seguir foi gerado automaticamente:

![](https://cdn.acedata.cloud/8mo82l.png)

O código Python correspondente:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "mashup",
    "lyric": "Sambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nSambuy come, Sambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\nSambuy come back",
    "model": "chirp-v4-5",
    "custom": True,
    "instrumental": False,
    "mashup_audio_ids": ["9f102969-0024-479e-b38f-c0c5db21383d","6aebb715-701c-433f-b976-a7ff5cf16255"]
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

Clique em executar, e será possível ver que um resultado será obtido, conforme a seguir:

```json theme={null}
{
  "success": true,
  "task_id": "3fe070eb-2ab1-4424-909c-acfe3ca761af",
  "trace_id": "2b220382-7a84-4853-ae43-05cdcad233a9",
  "data": [
    {
      "id": "5ff751dc-0e72-4de9-a54b-2cad50984b47",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-049",
      "image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-050",
      "lyric": "Sambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nSambuy come, Sambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\nSambuy come back",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2026-01-25T15:13:30.181Z",
      "model": "chirp-v4-5",
      "state": "succeeded",
      "style": "",
      "duration": 219.08
    },
    {
      "id": "19c515c4-d7b3-4a17-8ab0-dd1ebd4861b8",
      "title": "",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-051",
      "image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-052",
      "lyric": "Sambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nSambuy come, Sambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\n\\nSambuy come  \\nSambuy come back  \\nBluespawn, greenspawn are making you a spawn  \\nSambuy come back",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2026-01-25T15:13:30.181Z",
      "model": "chirp-v4-5",
      "state": "succeeded",
      "style": "",
      "duration": 163.12
    }
  ]
}
```

Dessa forma, a operação de geração de mixagem de músicas de referência foi concluída, e o resultado é semelhante ao acima.

## Samples Geração de músicas por amostragem

Aqui, `samples` refere-se à amostragem de um intervalo de áudio único: selecione os horários de início e término em um áudio existente e use esse trecho como material de amostragem para criação. Isso é diferente da função de criação por inspiração Inspo, que utiliza de 1 a 4 áudios de referência completos, mencionada abaixo. É necessário preencher os seguintes parâmetros:

* action: o conteúdo é `samples`.
* samples\_start: horário de início da amostragem.
* samples\_end: horário de término da amostragem.
* audio\_id: o ID da música de referência que precisa ser amostrada.

Após o preenchimento, o código a seguir foi gerado automaticamente:

![](https://cdn.acedata.cloud/vkzumz.png)

O código Python correspondente:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "samples",
    "model": "chirp-v5",
    "lyric": "[Verse 1]\\nPhone lit up\\nHeadline in my hand\\nFeels made up\\nStill says “you won’t understand”\\nYour name\\nMy name\\nSide by side in the scroll\\nCold black text\\nOn a story I used to hold\\n\\n[Chorus]\\nYou’re breaking news\\nAnd I’m just breaking\\nFront-page truth\\nHeart still shaking\\nEverybody reads\\nWhat we already knew\\nYou’re a story now\\nAnd I’m the one you broke it to\\n\\n[Verse 2]\\nNeighbors talk\\nThrough a half-closed door\\nCoffee cools\\nOn a cracked old floor\\nYour suitcase snaps\\nLike a camera flash\\nOne last quote\\nThen you cut to black\\n\\n[Chorus]\\nYou’re breaking news\\nAnd I’m just breaking\\nFront-page truth\\nHeart still shaking\\nEverybody reads\\nWhat we already knew\\nYou’re a story now\\nAnd I’m the one you broke it to\\n\\n[Bridge]\\nIs there a line\\nWhere we rewind\\nOr just a feed\\nThat leaves us behind\\nTell me\\nWho gets\\nThe final view\\nWhen I stop trending\\nWith you\\n\\n[Chorus]\\nYou’re breaking news\\nAnd I’m just breaking\\nFront-page truth\\nHeart still shaking\\nEverybody reads\\nWhat we already knew\\nYou’re a story now\\nAnd I’m the one you broke it to (yeah)",
    "custom": True,
    "instrumental": False,
    "audio_id": "0fa07665-6b8e-4a8b-8bd3-7e0cfcdada88",
    "samples_end": 102.16,
    "samples_start": 59.88
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

Clique em executar, e será possível ver que um resultado será obtido, conforme a seguir:

```json theme={null}
{
  "success": true,
  "task_id": "12135a45-6384-4683-9bb1-64f19933915a",
  "trace_id": "683e559d-340e-4c72-8fae-e683442ac7e9",
  "data": [
    {
      "id": "9a0b680f-a9ea-4a36-8695-8ea777ab6ee7",
      "title": "Whistle in the Wind",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-053",
      "image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-054",
      "lyric": "[Verse 1]\nPhone lit up\nHeadline in my hand\nFeels made up\nStill says “you won’t understand”\nYour name\nMy name\nSide by side in the scroll\nCold black text\nOn a story I used to hold\n[Chorus]\nYou’re breaking news\nAnd I’m just breaking\nFront-page truth\nHeart still shaking\nEverybody reads\nWhat we already knew\nYou’re a story now\nAnd I’m the one you broke it to\n[Verse 2]\nNeighbors talk\nThrough a half-closed door\nCoffee cools\nOn a cracked old floor\nYour suitcase snaps\nLike a camera flash\nOne last quote\nThen you cut to black\n[Chorus]\nYou’re breaking news\nAnd I’m just breaking\nFront-page truth\nHeart still shaking\nEverybody reads\nWhat we already knew\nYou’re a story now\nAnd I’m the one you broke it to\n[Bridge]\nIs there a line\nWhere we rewind\nOr just a feed\nThat leaves us behind\nTell me\nWho gets\nThe final view\nWhen I stop trending\nWith you\n[Chorus]\nYou’re breaking news\nAnd I’m just breaking\nFront-page truth\nHeart still shaking\nEverybody reads\nWhat we already knew\nYou’re a story now\nAnd I’m the one you broke it to (yeah)",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2026-01-31T14:34:45.043Z",
      "model": "chirp-v5",
      "state": "succeeded",
      "style": "acoustic with a hint of optimism,folk-pop,female vocals",
      "duration": 176.92
    },
    {
      "id": "66473dee-3aaf-43b2-80fd-76568b3abbb1",
      "title": "Whistle in the Wind",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-055",
      "image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-056",
      "lyric": "[Verse 1]\nPhone lit up\nHeadline in my hand\nFeels made up\nStill says “you won’t understand”\nYour name\nMy name\nSide by side in the scroll\nCold black text\nOn a story I used to hold\n[Chorus]\nYou’re breaking news\nAnd I’m just breaking\nFront-page truth\nHeart still shaking\nEverybody reads\nWhat we already knew\nYou’re a story now\nAnd I’m the one you broke it to\n[Verse 2]\nNeighbors talk\nThrough a half-closed door\nCoffee cools\nOn a cracked old floor\nYour suitcase snaps\nLike a camera flash\nOne last quote\nThen you cut to black\n[Chorus]\nYou’re breaking news\nAnd I’m just breaking\nFront-page truth\nHeart still shaking\nEverybody reads\nWhat we already knew\nYou’re a story now\nAnd I’m the one you broke it to\n[Bridge]\nIs there a line\nWhere we rewind\nOr just a feed\nThat leaves us behind\nTell me\nWho gets\nThe final view\nWhen I stop trending\nWith you\n[Chorus]\nYou’re breaking news\nAnd I’m just breaking\nFront-page truth\nHeart still shaking\nEverybody reads\nWhat we already knew\nYou’re a story now\nAnd I’m the one you broke it to (yeah)",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "",
      "created_at": "2026-01-31T14:34:45.043Z",
      "model": "chirp-v5",
      "state": "succeeded",
      "style": "acoustic with a hint of optimism,folk-pop,female vocals",
      "duration": 177.48
    }
  ]
}
```

Dessa forma, a operação de geração de músicas por amostragem é concluída, e o resultado é semelhante ao descrito acima.

## Funcionalidade de criação por inspiração Inspo

A funcionalidade de criação por inspiração Inspo pode gerar novas músicas com base em 1 a 4 áudios de referência completos, oferecendo suporte para arrastar e soltar ou enviar áudios como fonte de inspiração. A API usa a action `inspo` existente: o cliente fornece URLs de áudio acessíveis publicamente, e o serviço conclui automaticamente a preparação dos áudios de referência e a criação, sem que o cliente precise ler separadamente letras, estilo ou duração e depois montar a solicitação. Ela é diferente da amostragem de intervalo descrita acima e também diferente do Cover que replica o estilo da música original. Ao usar, é necessário preencher os seguintes parâmetros:

* action：o conteúdo é `inspo`。
* audio\_urls：lista de URLs dos áudios de referência; é necessário fornecer de 1 a 4 endereços de áudio acessíveis publicamente。
* model：o modelo utilizado; recomenda-se `chirp-v6`。
* prompt：letras ou texto de sugestão criativa (opcional)。

> Observação：os áudios de referência devem ser arquivos de áudio acessíveis publicamente. Se o áudio de referência corresponder exatamente a uma gravação conhecida no catálogo da plataforma, o Suno poderá recusar a geração devido à verificação de direitos autorais; recomenda-se usar áudios próprios ou gerados pelo Suno como fonte de inspiração。

O código Python correspondente:

```python theme={null}
import requests

url = "https://api.acedata.cloud/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "inspo",
    "model": "chirp-v6",
    "audio_urls": [
        "https://cdn.acedata.cloud/uploads/a0bc051f-42c2-4a46-aeb4-582dcc884ad2"
    ],
    "prompt": "Rework these references as warm acoustic folk with soft vocals"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)
```

Abaixo, mantemos uma captura de resposta histórica já verificada; a captura usa o `chirp-v5` daquela época, enquanto o exemplo de solicitação atual recomenda o `chirp-v6`; a estrutura de retorno é a mesma:

```json theme={null}
{
    "success": true,
    "task_id": "725e6b41-78d0-4adf-856c-05e81098c029",
    "trace_id": "8c2f0b3e-2f6a-4738-8b1d-c58068ca3dab",
    "data": [
        {
            "id": "20ca5628-86e0-4c32-8ae4-9f0c481e45f3",
            "title": "Inspo Demo",
            "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-057",
            "lyric": "",
            "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
            "video_url": "",
            "created_at": "2026-06-18T13:01:53.910Z",
            "model": "chirp-v5",
            "state": "succeeded",
            "style": "acoustic, folk, warm",
            "duration": 36.92
        },
        {
            "id": "8744a796-9961-45af-868d-4f3bc1c44257",
            "title": "Inspo Demo",
            "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-058",
            "lyric": "",
            "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
            "video_url": "",
            "created_at": "2026-06-18T13:01:53.910Z",
            "model": "chirp-v5",
            "state": "succeeded",
            "style": "acoustic, folk, warm",
            "duration": 84.16
        }
    ]
}
```

Dessa forma, a operação de criação por inspiração é concluída, e o resultado retornado é consistente com a geração comum de músicas.

## Retorno de chamada assíncrono

Como o Suno leva relativamente muito tempo para gerar música, cerca de 1 a 2 minutos, se a API ficar sem resposta por muito tempo, a solicitação HTTP permanecerá conectada, resultando em consumo adicional de recursos do sistema; portanto, esta API também fornece suporte para retornos de chamada assíncronos.

O processo geral é: quando o cliente inicia uma solicitação, ele especifica adicionalmente um campo `callback_url`; após o cliente iniciar a solicitação à API, a API retornará imediatamente um resultado, contendo um campo `task_id`, que representa o ID da tarefa atual. Quando a tarefa for concluída, o resultado da geração de música será enviado em formato POST JSON para o `callback_url` especificado pelo cliente, que também inclui o campo `task_id`, para que os resultados da tarefa possam ser associados por meio do ID.

A seguir, vamos entender como operar especificamente por meio de um exemplo.

Primeiro, o retorno de chamada Webhook é um serviço que pode receber solicitações HTTP, e o desenvolvedor deve substituí-lo pela URL do servidor HTTP criado por ele mesmo. Aqui, para facilitar a demonstração, é usado um site público de exemplo de Webhook [https://webhook.site/](https://webhook.site/); ao abrir esse site, é possível obter uma URL de Webhook, como mostrado na imagem:

![](https://cdn.acedata.cloud/fwfqin.png)

Copie esta URL, e ela poderá ser usada como Webhook; o exemplo aqui é [https://webhook.site/03e60575-3d96-4132-b681-b713d78116e2。](https://webhook.site/03e60575-3d96-4132-b681-b713d78116e2。)

Em seguida, podemos definir o campo `callback_url` como a URL de Webhook acima e, ao mesmo tempo, preencher `prompt`, como mostrado na imagem:

![](https://cdn.acedata.cloud/x8xql1.png)

Clique em executar, e será possível ver que um resultado será obtido imediatamente, conforme abaixo:

```
{
  "task_id": "44472ab8-783b-4054-b861-5bf14e462f60"
}
```

Aguarde um momento, e poderemos observar o resultado da geração da música em [https://webhook.site/03e60575-3d96-4132-b681-b713d78116e2](https://webhook.site/03e60575-3d96-4132-b681-b713d78116e2), como mostrado na imagem:

![](https://cdn.acedata.cloud/f9kosb.png)

O conteúdo é o seguinte:

```json theme={null}
{
  "success": true,
  "task_id": "44472ab8-783b-4054-b861-5bf14e462f60",
  "data": [
    {
      "id": "da4324e5-84b2-484b-b0e9-dd261381c594",
      "title": "Winter Whispers",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-059",
      "lyric": "[Verse]\nSnow falling gently from the sky\nChildren giggling as they pass by\nFire crackling\nCozy and warm\nChristmas spirit begins to swarm\n[Verse 2]\nTwinkling lights\nA sight to behold\nStockings hung\nWaiting to be filled with gold\nGifts wrapped with love\nPiled high\nExcitement in the air\nYou can't deny\n[Chorus]\nWinter whispers in the wind\nJoy and love it brings\nLet's celebrate this season\nWith the ones we're missing",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-003",
      "created_at": "2024-05-11T07:33:05.430Z",
      "model": "chirp-v3",
      "prompt": "A song for Christmas",
      "style": "pop"
    },
    {
      "id": "b878a87b-a0db-4046-8ccd-ecd2fb3d4372",
      "title": "Winter Whispers",
      "image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-060",
      "lyric": "[Verse]\nSnow falling gently from the sky\nChildren giggling as they pass by\nFire crackling\nCozy and warm\nChristmas spirit begins to swarm\n[Verse 2]\nTwinkling lights\nA sight to behold\nStockings hung\nWaiting to be filled with gold\nGifts wrapped with love\nPiled high\nExcitement in the air\nYou can't deny\n[Chorus]\nWinter whispers in the wind\nJoy and love it brings\nLet's celebrate this season\nWith the ones we're missing",
      "audio_url": "https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3",
      "video_url": "https://cdn.acedata.cloud/assets/examples/gemini/04a043bd-6b23-4b4e-945c-ce48158c3eee-3a89912507c7.mp4?example=video-004",
      "created_at": "2024-05-11T07:33:05.430Z",
      "model": "chirp-v3",
      "prompt": "A song for Christmas",
      "style": "pop"
    }
  ]
}
```

Pode-se ver que há um campo `task_id` no resultado, e os outros campos são semelhantes aos descritos acima; por meio desse campo, é possível realizar a associação da tarefa.

É claro que também podemos obter o resultado por meio de chamada em streaming; basta definir o valor de `accept` no cabeçalho da solicitação como `application/x-ndjson`. A seguir, usaremos uma entrada de exemplo como demonstração:

![](https://cdn.acedata.cloud/vgffvk.png)

Durante a espera, podemos obter a seguinte saída:

```json theme={null}
{"success":true,"task_id":"1af4b454-ce84-4512-a0a2-de3f8574ecd8","data":[{"id":"1f610752-f426-4fd5-89a8-ba2ad0370881","title":"Flocos de Neve e Visco","lyric":"[Verso]\nAs luzes estão emaranhadas na árvore de novo\nO gato derrubou a guirlanda\nBiscoitos queimando no forno também\nMas ainda estou sorrindo com os dentes cerrados\n[Pré-refrão]\nA neve está caindo como glitter no céu\nTenho a sensação de que este ano vai voar\n[Refrão]\nFlocos de neve e visco\nPor toda parte aonde vou\nEu sei\nO amor é o presente\nO brilho\nFlocos de neve e visco\n[Verso 2]\nA vovó está cantando um pouco fora do tom\nAs crianças estão rindo alto demais\nO cachorro roubou uma coxa de peru\nO caos é uma multidão de Natal\n[Pré-refrão]\nMas o fogo está crepitando\nQuente e brilhante\nE meu coração é uma vela esta noite\n[Refrão]\nFlocos de neve e visco\nPor toda parte aonde vou\nEu sei\nO amor é o presente\nO brilho\nFlocos de neve e visco","audio_url":"","video_url":"","created_at":"2025-12-13T11:29:25.101Z","model":"chirp-v5","state":"pending","prompt":"Uma canção para o Natal","style":"animado, orquestral com sinos e violão acústico"},{"id":"d1a3109d-799b-401e-b032-4b501bcf26f3","title":"Flocos de Neve e Visco","lyric":"[Verso]\nAs luzes estão emaranhadas na árvore de novo\nO gato derrubou a guirlanda\nBiscoitos queimando no forno também\nMas ainda estou sorrindo com os dentes cerrados\n[Pré-refrão]\nA neve está caindo como glitter no céu\nTenho a sensação de que este ano vai voar\n[Refrão]\nFlocos de neve e visco\nPor toda parte aonde vou\nEu sei\nO amor é o presente\nO brilho\nFlocos de neve e visco\n[Verso 2]\nA vovó está cantando um pouco fora do tom\nAs crianças estão rindo alto demais\nO cachorro roubou uma coxa de peru\nO caos é uma multidão de Natal\n[Pré-refrão]\nMas o fogo está crepitando\nQuente e brilhante\nE meu coração é uma vela esta noite\n[Refrão]\nFlocos de neve e visco\nPor toda parte aonde vou\nEu sei\nO amor é o presente\nO brilho\nFlocos de neve e visco","audio_url":"","video_url":"","created_at":"2025-12-13T11:29:25.101Z","model":"chirp-v5","state":"pending","prompt":"Uma canção para o Natal","style":"animado, orquestral com sinos e violão acústico"}]}
{"success":true,"task_id":"1af4b454-ce84-4512-a0a2-de3f8574ecd8","trace_id":"4440342a-41c4-4140-8bb1-3537a598ca2e","data":[{"id":"1f610752-f426-4fd5-89a8-ba2ad0370881","title":"Flocos de Neve e Visco","image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-073","image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-074","lyric":"[Verso]\nAs luzes estão emaranhadas na árvore de novo\nO gato derrubou a guirlanda\nBiscoitos queimando no forno também\nMas ainda estou sorrindo com os dentes cerrados\n[Pré-refrão]\nA neve está caindo como glitter no céu\nTenho a sensação de que este ano vai voar\n[Refrão]\nFlocos de neve e visco\nPor toda parte aonde vou\nEu sei\nO amor é o presente\nO brilho\nFlocos de neve e visco\n[Verso 2]\nA vovó está cantando um pouco fora do tom\nAs crianças estão rindo alto demais\nO cachorro roubou uma coxa de peru\nO caos é uma multidão de Natal\n[Pré-refrão]\nMas o fogo está crepitando\nQuente e brilhante\nE meu coração é uma vela esta noite\n[Refrão]\nFlocos de neve e visco\nPor toda parte aonde vou\nEu sei\nO amor é o presente\nO brilho\nFlocos de neve e visco","audio_url":"https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3","video_url":"","created_at":"2025-12-13T11:29:25.101Z","model":"chirp-v5","state":"succeeded","prompt":"Uma canção para o Natal","style":"animado, orquestral com sinos e violão acústico","duration":129.92},{"id":"d1a3109d-799b-401e-b032-4b501bcf26f3","title":"Flocos de Neve e Visco","image_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-075","image_large_url": "https://cdn.acedata.cloud/e724d7f13d.png?example=image-076","lyric":"[Verso]\nAs luzes estão emaranhadas na árvore de novo\nO gato derrubou a guirlanda\nBiscoitos queimando no forno também\nMas ainda estou sorrindo com os dentes cerrados\n[Pré-refrão]\nA neve está caindo como glitter no céu\nTenho a sensação de que este ano vai voar\n[Refrão]\nFlocos de neve e visco\nPor toda parte aonde vou\nEu sei\nO amor é o presente\nO brilho\nFlocos de neve e visco\n[Verso 2]\nA vovó está cantando um pouco fora do tom\nAs crianças estão rindo alto demais\nO cachorro roubou uma coxa de peru\nO caos é uma multidão de Natal\n[Pré-refrão]\nMas o fogo está crepitando\nQuente e brilhante\nE meu coração é uma vela esta noite\n[Refrão]\nFlocos de neve e visco\nPor toda parte aonde vou\nEu sei\nO amor é o presente\nO brilho\nFlocos de neve e visco","audio_url":"https://cdn.acedata.cloud/assets/examples/fish/5ade0339-5f11-487e-aacc-06a908271706-8e3fcb0e5547.mp3","video_url":"","created_at":"2025-12-13T11:29:25.101Z","model":"chirp-v5","state":"succeeded","prompt":"Uma canção para o Natal","style":"animado, orquestral com sinos e violão acústico","duration":127.16}]}
```

A resposta em streaming enviará sequencialmente o estado de processamento e o resultado final para o mesmo `task_id`; acima, apenas a primeira e a última das respostas reais foram mantidas, com as atualizações intermediárias repetidas omitidas.

## Tratamento de erros

Se ocorrer um erro, você receberá uma mensagem de erro semelhante à seguinte:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "forbidden",
    "message": "A descrição da música continha nome de artista: eminem"
  },
  "trace_id": "9bb7c2f4-3b7b-4965-b50a-f663874b1b6f",
  "task_id": "9bb3a2a6-c438-436d-a9f3-fa466abc077c"
}
```

Abaixo está a lista de HTTP Status Code, `error.code`, `error.message`:

> Observação: os limites e as mensagens de erro de diferentes contas upstream podem variar. Normalmente, `chirp-v3-5`/`chirp-v4` têm um limite menor para `style` (200), enquanto `chirp-v4-5` e versões posteriores geralmente suportam até 1000; ao atingir um upstream antigo, podem aparecer mensagens de compatibilidade como `Tags muito longas.` ou `style deve ser menor ou igual a 120`.
> \| Código de Status | `error.code`  | `error.message`                                                 |
> \| ----------- | ------------- | --------------------------------------------------------------- |
> \| 400         | `bad_request` | `O id da música não existe ou foi removido.`                    |
> \| 400         | `bad_request` | `Prompt muito longo.`                                           |
> \| 400         | `bad_request` | `Tags muito longas.`                                            |
> \| 400         | `bad_request` | `O áudio enviado corresponde a uma obra de arte existente.`     |
> \| 400         | `bad_request` | `instrumental deve ser um booleano`                             |
> \| 400         | `bad_request` | `Título muito longo.`                                           |
> \| 400         | `bad_request` | `Tópico muito longo.`                                           |
> \| 400         | `bad_request` | `style deve ser menor ou igual a 120`                           |
> \| 400         | `bad_request` | `custom deve ser um booleano`                                   |
> \| 400         | `bad_request` | `audio_id é obrigatório ao estender áudio`                      |
> \| 400         | `bad_request` | `continue_at é obrigatório ao estender áudio`                   |
> \| 400         | `bad_request` | `continue_at deve ser um número maior que 0`                    |
> \| 400         | `bad_request` | `lyric é obrigatório ao estender áudio e instrumental é falso`  |
> \| 400         | `bad_request` | `prompt é obrigatório ao gerar áudio`                           |
> \| 400         | `bad_request` | `lyric é obrigatório ao gerar áudio personalizado`              |
> \| 403         | `forbidden`   | `Prompt provavelmente malformado`                               |
> \| 403         | `forbidden`   | `Prompt provavelmente protegido por direitos autorais`          |
> \| 403         | `forbidden`   | `Prompt continha material impróprio`                            |
> \| 403         | `forbidden`   | `Descrição da música sinalizada para moderação`                 |
> \| 403         | `forbidden`   | `Descrição da música continha nome de artista`                  |
> \| 403         | `forbidden`   | `Tags continham nome de artista`                                |
> \| 403         | `forbidden`   | `Letras continham material protegido por direitos autorais`     |
> \| 403         | `forbidden`   | `Descrição da música continha tag de produtor`                  |
> \| 403         | `forbidden`   | `Erro genérico do openAI`                                       |
> \| 403         | `forbidden`   | `Prompt sinalizado para moderação`                              |
> \| 500         | `api_error`   | `Não foi possível gerar letras a partir da descrição da música` |
> \| 500         | `api_error`   | `a tarefa falhou com erro desconhecido`                         |
> \| 500         | `api_error`   | `nenhum worker disponível no sistema`                           |
> \| 500         | `api_error`   | `serviço em manutenção, geração pausada`                        |
> \| 504         | `timeout`     | `tempo esgotado enquanto aguardava a geração de áudio`          |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.