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

# Konvensi Umum Suno & Kueri Tugas

>  - Penjelasan umum antarmuka musik Suno: autentikasi, siklus hidup tugas asinkron, model / version, referensi audio sumber
- Kueri tugas: GET /v1/music/tasks/:task_id, polling hingga completed / failed 

<Info>
  Halaman ini adalah konvensi umum untuk semua antarmuka musik Suno, digunakan bersama dokumentasi terpisah setiap endpoint. Semua antarmuka pembuatan / pengeditan bersifat **tugas asinkron**: kirim untuk mendapatkan `task_id`, lalu polling antarmuka kueri di halaman ini untuk mengambil hasilnya.
</Info>

## Autentikasi

Semua permintaan perlu menyertakan pada header permintaan:

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

Kunjungi [halaman pengelolaan API Key](https://apimart.ai/keys) untuk mendapatkan API Key.

## Siklus hidup tugas (semua antarmuka bersifat asinkron)

<Steps>
  <Step title="Kirim">
    `POST /v1/music/generations/<operation>` → segera mengembalikan `task_id` dari pihak kami:

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

  <Step title="Polling">
    `GET /v1/music/tasks/:task_id` hingga `status` menjadi `completed` atau `failed`. Selama proses pembuatan, `status` bernilai `pending`, dan `progress` berjalan: antre `10` → siap `50` → selesai `100`. Disarankan interval polling 3–5s; pembuatan musik biasanya 30–120s.
  </Step>

  <Step title="Ambil hasil">
    Setelah selesai, ambil `audio_url` / `image_url` / `video_url` dan lainnya dari `data.result.music[]`.
  </Step>
</Steps>

Alur status tugas: `submitted` → `pending` → `completed` / `failed`. **Saat gagal, `data.error.message` memberikan alasannya, dan kuota yang dipotong di muka dikembalikan otomatis.**

## Versi version

`v3.5` / `v4` / `v4.5` / `v4.5+` / `v4.5-all` / `v5` / `v5.5`, memengaruhi kualitas audio dan penagihan; jika tidak dikirim menggunakan default. Versi yang tersedia dan nilai default berbeda-beda per endpoint — sebagian endpoint hanya mendukung subset, dan sebagian tidak memiliki dimensi versi sama sekali; lihat dokumentasi masing-masing endpoint.

## Referensi audio sumber: task\_id + audio\_index

Operasi berbasis lagu yang sudah ada (perpanjangan / cover / pemisahan trek / penambahan vokal / pemotongan…) **tidak perlu** mencatat id pihak hulu apa pun, cukup kirim:

* `task_id`: `task_id` pihak kami dari tugas yang menghasilkan audio sumber
* `audio_index`: lagu ke berapa di dalam `music[]` hasil tugas tersebut (berbasis 1, default `1`; satu kali pembuatan biasanya 2 lagu: 1 dan 2)

<Warning>
  Jika sumber tidak dapat diresolusi (tugas belum selesai / indeks di luar batas / `task_id` tidak ditemukan), `400` dikembalikan pada saat pengiriman.
</Warning>

## Kueri tugas: GET /v1/music/tasks/:task\_id

<ParamField path="task_id" type="string" required>
  `task_id` pihak kami yang dikembalikan antarmuka pengiriman.
</ParamField>

Polling antarmuka ini hingga `status` menjadi `completed` atau `failed`. Setelah selesai, ambil produk dari `data.result.music[]`.

## Response

<ResponseField name="task_id" type="string">
  Pengenal unik tugas
</ResponseField>

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

<ResponseField name="progress" type="integer">
  Progres: antre `10` → siap `50` → selesai `100`
</ResponseField>

<ResponseField name="data" type="object">
  Data hasil

  <Expandable title="Properti">
    <ResponseField name="result" type="object">
      Ada saat `status` bernilai `completed`

      <Expandable title="Properti result">
        <ResponseField name="music" type="array">
          Daftar produk (satu kali pembuatan biasanya 2 lagu)

          <Expandable title="Properti music[]">
            <ResponseField name="audio_id" type="string">
              id audio, digunakan untuk operasi berikutnya guna melokasikan dengan `audio_index`
            </ResponseField>

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

            <ResponseField name="duration" type="number">
              Durasi (detik)
            </ResponseField>

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

            <ResponseField name="tags" type="string">
              Tag gaya
            </ResponseField>

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

            <ResponseField name="image_url" type="string">
              URL gambar sampul
            </ResponseField>

            <ResponseField name="image_large_url" type="string">
              URL sampul gambar besar
            </ResponseField>

            <ResponseField name="video_url" type="string">
              URL video MV (jika sudah dibuat)
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="error" type="object">
      Ada saat `status` bernilai `failed`

      <Expandable title="Properti error">
        <ResponseField name="message" type="string">
          Alasan kegagalan (kuota yang dipotong di muka dikembalikan otomatis)
        </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>