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

# Suno Allgemeine Konventionen und Aufgabenabfrage

>  - Allgemeine Hinweise zur Suno-Musik-API: Authentifizierung, Lebenszyklus asynchroner Aufgaben, model / version, Referenz auf Quell-Audiospuren
- Aufgabenabfrage: GET /v1/music/tasks/:task_id, abfragen bis completed / failed 

<Info>
  Diese Seite enthält die allgemeinen Konventionen für alle Suno-Musik-APIs und wird zusammen mit der jeweiligen Einzeldokumentation der Endpunkte verwendet. Alle Generierungs- / Bearbeitungs-APIs sind **asynchrone Aufgaben**: Beim Absenden erhalten Sie eine `task_id`, anschließend fragen Sie die Abfrage-API auf dieser Seite ab, um das Ergebnis zu erhalten.
</Info>

## Authentifizierung

Alle Anfragen müssen im Anfrage-Header Folgendes mitführen:

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

Besuchen Sie die [Seite zur API-Key-Verwaltung](https://apimart.ai/keys), um einen API Key zu erhalten.

## Aufgabenlebenszyklus (alle APIs sind asynchron)

<Steps>
  <Step title="Absenden">
    `POST /v1/music/generations/<operation>` → gibt sofort unsere `task_id` zurück:

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

  <Step title="Abfragen">
    `GET /v1/music/tasks/:task_id` bis `status` `completed` oder `failed` ist. Während der Generierung ist `status` `pending` und `progress` läuft von Warteschlange `10` → bereit `50` → fertig `100`. Empfohlenes Abfrageintervall 3–5s; die Musikgenerierung dauert in der Regel 30–120s.
  </Step>

  <Step title="Ergebnis abrufen">
    Nach Abschluss `audio_url` / `image_url` / `video_url` usw. aus `data.result.music[]` abrufen.
  </Step>
</Steps>

Statusverlauf der Aufgabe: `submitted` → `pending` → `completed` / `failed`. **Bei einem Fehlschlag gibt `data.error.message` den Grund an, und das vorab reservierte Guthaben wird automatisch zurückerstattet.**

## Version

`v3.5` / `v4` / `v4.5` / `v4.5+` / `v4.5-all` / `v5` / `v5.5`, beeinflusst Klangqualität und Abrechnung; ohne Angabe wird die Standardversion verwendet. Verfügbare Versionen und Standardwerte unterscheiden sich je Endpunkt — manche unterstützen nur eine Teilmenge, und manche haben gar keine Versionsdimension; maßgeblich ist die jeweilige Endpunkt-Dokumentation.

## Quell-Audiospur referenzieren: task\_id + audio\_index

Für Operationen auf Basis vorhandener Songs (Fortsetzen / Cover / Stem-Trennung / Gesang hinzufügen / Zuschneiden …) müssen Sie sich **keine** vorgelagerte id merken, übergeben Sie nur:

* `task_id`: unsere `task_id` der Aufgabe, die die Quell-Audiospur erzeugt hat
* `audio_index`: welcher Song aus dem Ergebnis `music[]` dieser Aufgabe (1-basiert, Standard `1`; eine Generierung erzeugt in der Regel 2 Songs: 1 und 2)

<Warning>
  Wenn die Quelle nicht aufgelöst werden kann (Aufgabe nicht abgeschlossen / Index außerhalb des Bereichs / `task_id` nicht gefunden), wird bereits beim Absenden ein `400` zurückgegeben.
</Warning>

## Aufgabe abfragen: GET /v1/music/tasks/:task\_id

<ParamField path="task_id" type="string" required>
  Die von der Absende-API zurückgegebene, unsere `task_id`.
</ParamField>

Fragen Sie diese API ab, bis `status` `completed` oder `failed` ist. Nach Abschluss die Produkte aus `data.result.music[]` abrufen.

## Response

<ResponseField name="task_id" type="string">
  Eindeutige Kennung der Aufgabe
</ResponseField>

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

<ResponseField name="progress" type="integer">
  Fortschritt: Warteschlange `10` → bereit `50` → fertig `100`
</ResponseField>

<ResponseField name="data" type="object">
  Ergebnisdaten

  <Expandable title="Eigenschaften">
    <ResponseField name="result" type="object">
      Vorhanden, wenn `status` `completed` ist

      <Expandable title="result Eigenschaften">
        <ResponseField name="music" type="array">
          Ergebnisliste (eine Generierung erzeugt in der Regel 2 Songs)

          <Expandable title="music[] Eigenschaften">
            <ResponseField name="audio_id" type="string">
              Audiospur-id, für spätere Operationen zur Lokalisierung per `audio_index`
            </ResponseField>

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

            <ResponseField name="duration" type="number">
              Dauer (Sekunden)
            </ResponseField>

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

            <ResponseField name="tags" type="string">
              Stil-Tags
            </ResponseField>

            <ResponseField name="audio_url" type="string">
              URL der Audiodatei
            </ResponseField>

            <ResponseField name="image_url" type="string">
              URL des Covers
            </ResponseField>

            <ResponseField name="image_large_url" type="string">
              URL des großen Covers
            </ResponseField>

            <ResponseField name="video_url" type="string">
              URL des MV-Videos (falls bereits generiert)
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="error" type="object">
      Vorhanden, wenn `status` `failed` ist

      <Expandable title="error Eigenschaften">
        <ResponseField name="message" type="string">
          Grund für den Fehlschlag (das vorab reservierte Guthaben wird automatisch zurückerstattet)
        </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>