> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Convenções Gerais e Consulta de Tarefas do Suno

>  - Notas comuns das interfaces de música do Suno: autenticação, ciclo de vida de tarefas assíncronas, model / version, referência à faixa de áudio de origem
- Consulta de tarefa: GET /v1/music/tasks/:task_id, faça polling até completed / failed 

<Info>
  Esta página contém as convenções comuns de todas as interfaces de música do Suno, usada em conjunto com a documentação individual de cada endpoint. Todas as interfaces de geração / edição são **tarefas assíncronas**: envie para obter o `task_id` e, em seguida, faça polling na interface de consulta desta página para obter o resultado.
</Info>

## Autenticação

Todas as requisições precisam incluir no cabeçalho:

```
Authorization: Bearer <sua API Key>
Content-Type: application/json
```

Acesse a [página de gerenciamento de API Key](https://apimart.ai/keys) para obter sua API Key.

## Ciclo de vida da tarefa (todas as interfaces são assíncronas)

<Steps>
  <Step title="Enviar">
    `POST /v1/music/generations/<operação>` → retorna imediatamente o nosso `task_id`:

    ```json theme={null}
    { "code": 200, "data": [ { "status": "submitted", "task_id": "task_xxx" } ] }
    ```
  </Step>

  <Step title="Fazer polling">
    `GET /v1/music/tasks/:task_id` até que `status` seja `completed` ou `failed`. Durante a geração, `status` é `pending` e `progress` vai de na fila `10` → pronto `50` → concluído `100`. Recomenda-se um intervalo de polling de 3–5s; a geração de música normalmente leva 30–120s.
  </Step>

  <Step title="Obter resultado">
    Após a conclusão, obtenha `audio_url` / `image_url` / `video_url`, etc. de `data.result.music[]`.
  </Step>
</Steps>

Fluxo de estados da tarefa: `submitted` → `pending` → `completed` / `failed`. **Em caso de falha, `data.error.message` informa o motivo e a cota pré-reservada é devolvida automaticamente.**

## Versão version

`v3.5` / `v4` / `v4.5` / `v4.5+` / `v4.5-all` / `v5` / `v5.5`, afeta a qualidade do áudio e a cobrança; se não for informado, usa-se o padrão. A disponibilidade e os valores padrão variam conforme o endpoint — alguns suportam apenas um subconjunto e outros não têm dimensão de versão; consulte a documentação de cada endpoint.

## Referência à faixa de origem: task\_id + audio\_index

Operações baseadas em músicas já existentes (continuação / cover / separação de faixas / adição de vocais / recorte…) **não** exigem que você guarde nenhum id upstream, basta informar:

* `task_id`: o nosso `task_id` da tarefa que produziu a faixa de origem
* `audio_index`: qual faixa dentro do `music[]` do resultado dessa tarefa (baseado em 1, padrão `1`; uma geração normalmente produz 2 músicas: 1 e 2)

<Warning>
  Se a origem não puder ser resolvida (tarefa não concluída / índice fora do intervalo / `task_id` inexistente), um `400` é retornado no momento do envio.
</Warning>

## Consultar tarefa: GET /v1/music/tasks/:task\_id

<ParamField path="task_id" type="string" required>
  O nosso `task_id` retornado pela interface de envio.
</ParamField>

Faça polling nessa interface até que `status` seja `completed` ou `failed`. Após a conclusão, obtenha os produtos de `data.result.music[]`.

## Response

<ResponseField name="task_id" type="string">
  Identificador único da tarefa
</ResponseField>

<ResponseField name="status" type="string">
  Estado da tarefa: `submitted` / `pending` / `completed` / `failed`
</ResponseField>

<ResponseField name="progress" type="integer">
  Progresso: na fila `10` → pronto `50` → concluído `100`
</ResponseField>

<ResponseField name="data" type="object">
  Dados do resultado

  <Expandable title="Propriedades">
    <ResponseField name="result" type="object">
      Presente quando `status` é `completed`

      <Expandable title="Propriedades de result">
        <ResponseField name="music" type="array">
          Lista de produtos (uma geração normalmente produz 2 músicas)

          <Expandable title="Propriedades de music[]">
            <ResponseField name="audio_id" type="string">
              id da faixa, usado para localizar em operações posteriores com `audio_index`
            </ResponseField>

            <ResponseField name="title" type="string">
              Título
            </ResponseField>

            <ResponseField name="duration" type="number">
              Duração (segundos)
            </ResponseField>

            <ResponseField name="lyrics" type="string">
              Letra
            </ResponseField>

            <ResponseField name="tags" type="string">
              Etiquetas de estilo
            </ResponseField>

            <ResponseField name="audio_url" type="string">
              URL do arquivo de áudio
            </ResponseField>

            <ResponseField name="image_url" type="string">
              URL da imagem de capa
            </ResponseField>

            <ResponseField name="image_large_url" type="string">
              URL da capa em imagem grande
            </ResponseField>

            <ResponseField name="video_url" type="string">
              URL do vídeo MV (se já gerado)
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="error" type="object">
      Presente quando `status` é `failed`

      <Expandable title="Propriedades de error">
        <ResponseField name="message" type="string">
          Motivo da falha (a cota pré-reservada é devolvida automaticamente)
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json completed theme={null}
  {
    "task_id": "task_01ABC...",
    "status": "completed",
    "progress": 100,
    "data": {
      "result": {
        "music": [
          {
            "audio_id": "<track id, used with audio_index to locate it for subsequent operations>",
            "title": "Summer Breeze",
            "duration": 128.5,
            "lyrics": "……",
            "tags": "electronic, upbeat",
            "audio_url": "https://.../xxx.mp3",
            "image_url": "https://.../cover.png",
            "image_large_url": "https://.../cover_large.png",
            "video_url": "https://.../mv.mp4"
          }
        ]
      }
    }
  }
  ```

  ```json failed theme={null}
  {
    "task_id": "task_01ABC...",
    "status": "failed",
    "progress": 100,
    "data": {
      "error": {
        "message": "generation failed"
      }
    }
  }
  ```
</ResponseExample>