> ## 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 共通仕様とタスク照会

>  - Suno 音楽インターフェースの共通説明：認証、非同期タスクのライフサイクル、model / version、ソース音源の参照
- タスク照会：GET /v1/music/tasks/:task_id、completed / failed になるまでポーリング 

<Info>
  本ページはすべての Suno 音楽インターフェースに共通する仕様であり、各エンドポイント個別のドキュメントと併せて使用します。すべての生成 / 編集インターフェースは**非同期タスク**です：送信して `task_id` を取得し、本ページの照会インターフェースをポーリングして結果を取得します。
</Info>

## 認証

すべてのリクエストで、リクエストヘッダーに以下を含める必要があります：

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

[API Key 管理ページ](https://apimart.ai/keys) にアクセスして API Key を取得してください。

## タスクのライフサイクル（すべてのインターフェースが非同期）

<Steps>
  <Step title="送信">
    `POST /v1/music/generations/<operation>` → 即座に当方の `task_id` を返します：

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

  <Step title="ポーリング">
    `GET /v1/music/tasks/:task_id` を `status` が `completed` または `failed` になるまで実行します。生成中は `status` が `pending` で、`progress` は 待機 `10` → 準備完了 `50` → 完了 `100` と進みます。ポーリング間隔は 3〜5s を推奨します。音楽生成は通常 30〜120s かかります。
  </Step>

  <Step title="結果の取得">
    完了時、`data.result.music[]` から `audio_url` / `image_url` / `video_url` などを取得します。
  </Step>
</Steps>

タスクステータスの遷移：`submitted` → `pending` → `completed` / `failed`。**失敗した場合は、`data.error.message` に理由が示され、事前に差し引かれた額度が自動的に返還されます。**

## バージョン

`v3.5` / `v4` / `v4.5` / `v4.5+` / `v4.5-all` / `v5` / `v5.5`。音質と課金に影響します。指定しない場合はデフォルトを使用します。対応状況とデフォルト値はエンドポイントごとに異なり、一部は一部のバージョンのみ対応し、一部はバージョンの区分がまったくありません。各エンドポイント個別のドキュメントを参照してください。

## ソース音源の参照：task\_id + audio\_index

既存の楽曲に基づく操作（続き生成 / カバー / トラック分離 / ボーカル追加 / トリミング…）では、上流の id を一切記録する**必要はありません**。以下のみを渡します：

* `task_id`：ソース音源を生成したそのタスクの当方の `task_id`
* `audio_index`：そのタスク結果 `music[]` の何番目の曲か（1 始まり、デフォルト `1`。1 回の生成で通常 2 曲：1 と 2）

<Warning>
  ソースを解決できない場合（タスクが未完了 / 番号が範囲外 / `task_id` が存在しない）、送信時に `400` を返します。
</Warning>

## タスク照会：GET /v1/music/tasks/:task\_id

<ParamField path="task_id" type="string" required>
  送信インターフェースが返した当方の `task_id`。
</ParamField>

このインターフェースを `status` が `completed` または `failed` になるまでポーリングします。完了後、`data.result.music[]` から成果物を取得します。

## Response

<ResponseField name="task_id" type="string">
  タスクの一意の識別子
</ResponseField>

<ResponseField name="status" type="string">
  タスクステータス：`submitted` / `pending` / `completed` / `failed`
</ResponseField>

<ResponseField name="progress" type="integer">
  進捗：待機 `10` → 準備完了 `50` → 完了 `100`
</ResponseField>

<ResponseField name="data" type="object">
  結果データ

  <Expandable title="属性">
    <ResponseField name="result" type="object">
      `status` が `completed` のときに存在します

      <Expandable title="result の属性">
        <ResponseField name="music" type="array">
          成果物のリスト（1 回の生成で通常 2 曲）

          <Expandable title="music[] 属性">
            <ResponseField name="audio_id" type="string">
              音源 id。後続操作で `audio_index` により特定するために使用します
            </ResponseField>

            <ResponseField name="title" type="string">
              タイトル
            </ResponseField>

            <ResponseField name="duration" type="number">
              長さ（秒）
            </ResponseField>

            <ResponseField name="lyrics" type="string">
              歌詞
            </ResponseField>

            <ResponseField name="tags" type="string">
              スタイルタグ
            </ResponseField>

            <ResponseField name="audio_url" type="string">
              音声ファイルの URL
            </ResponseField>

            <ResponseField name="image_url" type="string">
              カバー画像の URL
            </ResponseField>

            <ResponseField name="image_large_url" type="string">
              大きいカバー画像の URL
            </ResponseField>

            <ResponseField name="video_url" type="string">
              MV 動画の URL（生成済みの場合）
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="error" type="object">
      `status` が `failed` のときに存在します

      <Expandable title="error の属性">
        <ResponseField name="message" type="string">
          失敗理由（事前に差し引かれた額度は自動的に返還されます）
        </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>