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

# Conventions générales Suno et interrogation des tâches

>  - Notes communes à l'API musicale Suno : authentification, cycle de vie des tâches asynchrones, model / version, référence de la piste source
- Interrogation des tâches : GET /v1/music/tasks/:task_id, interroger jusqu'à completed / failed 

<Info>
  Cette page décrit les conventions communes à toutes les API musicales Suno, à utiliser conjointement avec la documentation propre à chaque endpoint. Toutes les API de génération / édition sont des **tâches asynchrones** : soumettez pour obtenir un `task_id`, puis interrogez l'API décrite ici pour récupérer le résultat.
</Info>

## Authentification

Toutes les requêtes doivent inclure dans leurs en-têtes :

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

Rendez-vous sur la [page de gestion des clés API](https://apimart.ai/keys) pour obtenir votre clé API.

## Cycle de vie des tâches (toutes les API sont asynchrones)

<Steps>
  <Step title="Soumettre">
    `POST /v1/music/generations/<opération>` → renvoie immédiatement notre `task_id` :

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

  <Step title="Interroger">
    `GET /v1/music/tasks/:task_id` jusqu'à ce que `status` soit `completed` ou `failed`. Pendant la génération, `status` vaut `pending` et `progress` passe de en file d'attente `10` → prêt `50` → terminé `100`. Intervalle de sondage recommandé : 3–5 s ; la génération musicale prend généralement 30–120 s.
  </Step>

  <Step title="Récupérer le résultat">
    Une fois terminée, récupérez `audio_url` / `image_url` / `video_url`, etc. depuis `data.result.music[]`.
  </Step>
</Steps>

Enchaînement des statuts de tâche : `submitted` → `pending` → `completed` / `failed`. **En cas d'échec, `data.error.message` donne la raison et le quota préautorisé est automatiquement remboursé.**

## Version version

`v3.5` / `v4` / `v4.5` / `v4.5+` / `v4.5-all` / `v5` / `v5.5`, ce qui influe sur la qualité audio et la facturation ; la valeur par défaut est utilisée si non fournie. La disponibilité et les valeurs par défaut varient selon l'endpoint — certains ne prennent en charge qu'un sous-ensemble, et d'autres n'ont aucune dimension de version ; reportez-vous à la documentation propre à chaque endpoint.

## Référencer la piste source : task\_id + audio\_index

Les opérations basées sur un morceau existant (extension / reprise / séparation de pistes / ajout de voix / découpage…) **ne nécessitent** de mémoriser aucun id en amont, il suffit de passer :

* `task_id` : notre `task_id` de la tâche ayant produit la piste source
* `audio_index` : quel morceau dans le `music[]` du résultat de cette tâche (indexé à partir de 1, par défaut `1` ; une génération produit généralement 2 morceaux : 1 et 2)

<Warning>
  Si la source ne peut pas être résolue (tâche non terminée / indice hors limites / `task_id` inexistant), un `400` est renvoyé au moment de la soumission.
</Warning>

## Interroger une tâche : GET /v1/music/tasks/:task\_id

<ParamField path="task_id" type="string" required>
  Notre `task_id` renvoyé par l'API de soumission.
</ParamField>

Interrogez cette API jusqu'à ce que `status` soit `completed` ou `failed`. Une fois terminée, récupérez les produits depuis `data.result.music[]`.

## Response

<ResponseField name="task_id" type="string">
  Identifiant unique de la tâche
</ResponseField>

<ResponseField name="status" type="string">
  Statut de la tâche : `submitted` / `pending` / `completed` / `failed`
</ResponseField>

<ResponseField name="progress" type="integer">
  Progression : en file d'attente `10` → prêt `50` → terminé `100`
</ResponseField>

<ResponseField name="data" type="object">
  Données du résultat

  <Expandable title="Propriétés">
    <ResponseField name="result" type="object">
      Présent lorsque `status` vaut `completed`

      <Expandable title="Propriétés de result">
        <ResponseField name="music" type="array">
          Liste des produits (une génération produit généralement 2 morceaux)

          <Expandable title="Propriétés de music[]">
            <ResponseField name="audio_id" type="string">
              id de la piste, utilisé pour localiser via `audio_index` lors des opérations ultérieures
            </ResponseField>

            <ResponseField name="title" type="string">
              Titre
            </ResponseField>

            <ResponseField name="duration" type="number">
              Durée (en secondes)
            </ResponseField>

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

            <ResponseField name="tags" type="string">
              Étiquettes de style
            </ResponseField>

            <ResponseField name="audio_url" type="string">
              URL du fichier audio
            </ResponseField>

            <ResponseField name="image_url" type="string">
              URL de l'image de couverture
            </ResponseField>

            <ResponseField name="image_large_url" type="string">
              URL de la couverture grand format
            </ResponseField>

            <ResponseField name="video_url" type="string">
              URL de la vidéo MV (si déjà générée)
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="error" type="object">
      Présent lorsque `status` vaut `failed`

      <Expandable title="Propriétés de error">
        <ResponseField name="message" type="string">
          Raison de l'échec (le quota préautorisé est automatiquement remboursé)
        </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>