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

# Convenciones generales de Suno y consulta de tareas

>  - Notas comunes de la API de música Suno: autenticación, ciclo de vida de las tareas asíncronas, model / version, referencia a la pista de audio de origen
- Consulta de tareas: GET /v1/music/tasks/:task_id, sondear hasta completed / failed 

<Info>
  Esta página contiene las convenciones comunes de todas las interfaces de música Suno y se usa junto con la documentación individual de cada endpoint. Todas las interfaces de generación / edición son **tareas asíncronas**: al enviar se obtiene un `task_id`, y luego se sondea la interfaz de consulta de esta página para obtener el resultado.
</Info>

## Autenticación

Todas las solicitudes deben incluir en los encabezados:

```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

Visita la [página de gestión de API Key](https://apimart.ai/keys) para obtener tu API Key.

## Ciclo de vida de la tarea (todas las interfaces son asíncronas)

<Steps>
  <Step title="Enviar">
    `POST /v1/music/generations/<operación>` → devuelve de inmediato nuestro `task_id`:

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

  <Step title="Sondear">
    `GET /v1/music/tasks/:task_id` hasta que `status` sea `completed` o `failed`. Durante la generación, `status` es `pending` y `progress` avanza en cola `10` → listo `50` → hecho `100`. Se recomienda un intervalo de sondeo de 3–5s; la generación de música suele tardar 30–120s.
  </Step>

  <Step title="Obtener el resultado">
    Al completarse, obtén `audio_url` / `image_url` / `video_url`, etc. desde `data.result.music[]`.
  </Step>
</Steps>

Flujo de estados de la tarea: `submitted` → `pending` → `completed` / `failed`. **En caso de fallo, `data.error.message` indica el motivo y el saldo retenido previamente se reembolsa automáticamente.**

## Versión

`v3.5` / `v4` / `v4.5` / `v4.5+` / `v4.5-all` / `v5` / `v5.5`, afecta la calidad del audio y la facturación; si no se pasa, se usa el valor por defecto. La disponibilidad y los valores por defecto varían según el endpoint: algunos solo admiten un subconjunto y otros no tienen dimensión de versión en absoluto; consulta la documentación de cada endpoint.

## Referenciar la pista de audio de origen: task\_id + audio\_index

Las operaciones basadas en una canción existente (continuar / versionar / separar pistas / añadir voces / recortar…) **no requieren** recordar ningún id ascendente, solo se pasa:

* `task_id`: nuestro `task_id` de la tarea que produjo la pista de audio de origen
* `audio_index`: qué canción del resultado `music[]` de esa tarea (basado en 1, por defecto `1`; una generación suele producir 2 canciones: 1 y 2)

<Warning>
  Si no se puede resolver el origen (tarea no completada / índice fuera de rango / `task_id` inexistente), se devuelve un `400` en el momento del envío.
</Warning>

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

<ParamField path="task_id" type="string" required>
  Nuestro `task_id` devuelto por la interfaz de envío.
</ParamField>

Sondea esta interfaz hasta que `status` sea `completed` o `failed`. Tras completarse, obtén los productos desde `data.result.music[]`.

## Response

<ResponseField name="task_id" type="string">
  Identificador único de la tarea
</ResponseField>

<ResponseField name="status" type="string">
  Estado de la tarea: `submitted` / `pending` / `completed` / `failed`
</ResponseField>

<ResponseField name="progress" type="integer">
  Progreso: en cola `10` → listo `50` → hecho `100`
</ResponseField>

<ResponseField name="data" type="object">
  Datos del resultado

  <Expandable title="Propiedades">
    <ResponseField name="result" type="object">
      Presente cuando `status` es `completed`

      <Expandable title="Propiedades de result">
        <ResponseField name="music" type="array">
          Lista de productos (una generación suele producir 2 canciones)

          <Expandable title="Propiedades de music[]">
            <ResponseField name="audio_id" type="string">
              id de la pista de audio, para localizar mediante `audio_index` en operaciones posteriores
            </ResponseField>

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

            <ResponseField name="duration" type="number">
              Duración (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 del archivo de audio
            </ResponseField>

            <ResponseField name="image_url" type="string">
              URL de la imagen de portada
            </ResponseField>

            <ResponseField name="image_large_url" type="string">
              URL de la portada en tamaño grande
            </ResponseField>

            <ResponseField name="video_url" type="string">
              URL del video MV (si ya se ha generado)
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="error" type="object">
      Presente cuando `status` es `failed`

      <Expandable title="Propiedades de error">
        <ResponseField name="message" type="string">
          Motivo del fallo (el saldo retenido previamente se reembolsa automáticamente)
        </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>