> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiid.edu.kg/llms.txt
> Use this file to discover all available pages before exploring further.

# 依 ID 查詢音樂任務

> 透過 path `task_id` 查詢音樂生成任務。

音樂生成任務查詢介面。建立介面返回的 `data` 即任務 ID，透過 `GET /suno/fetch/{task_id}` 查詢單個任務。

## 查詢方式

```http
GET /suno/fetch/task_xxx
```

## 查詢輸出

外層保持 new-api 任務結構：

- `code`：成功時為 `success`。
- `message`：錯誤或提示資訊。
- `data.task_id`：任務 ID。
- `data.status`：任務狀態，常見值 `NOT_START`、`SUBMITTED`、`QUEUED`、`IN_PROGRESS`、`SUCCESS`、`FAILURE`。
- `data.progress`：任務進度。
- `data.result_url`：成功後可用的結果位址，若上游返回多首歌曲，以 `data.data` 內片段為準。
- `data.data`：上游音樂結果原始資料，通常包含歌曲片段陣列或物件。

成功態範例：

```json
{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_xxx",
    "platform": "suno",
    "action": "MUSIC",
    "status": "SUCCESS",
    "progress": "100%",
    "result_url": "https://example.com/audio.mp3",
    "properties": {
      "upstream_model_name": "suno_music",
      "origin_model_name": "suno-v5.5"
    },
    "data": [
      {
        "id": "clip_xxx",
        "title": "夏日海风",
        "audio_url": "https://example.com/audio.mp3",
        "image_url": "https://example.com/cover.jpg",
        "model_name": "suno-v5.5",
        "metadata": {
          "duration": 180,
          "prompt": "轻快电子流行，夏日海边，女声 旋律"
        }
      }
    ]
  }
}
```



## OpenAPI

````yaml api-reference/zh-tw/openapi.json GET /suno/fetch/{task_id}
openapi: 3.0.0
info:
  title: 出海營 API 參考文件
  version: 1.0.0
  description: Public AI Gateway API Reference
servers:
  - url: https://api.aiid.edu.kg
security:
  - BearerAuth: []
tags:
  - name: OpenAI格式（Chat）
  - name: OpenAI格式（Responses）
  - name: 圖片生成 Gemini 格式
  - name: 圖片生成OpenAI DALL-E 格式
  - name: 獲取模型列表
  - name: 影片生成HappyHorse與 Wan
  - name: 影片生成Kling格式
  - name: 影片生成 Omni 與 Veo 格式
  - name: 影片生成 Seedance 格式
  - name: 影片生成Sora相容格式
  - name: 影片生成 Vidu 格式
  - name: 音樂生成任務格式
paths:
  /suno/fetch/{task_id}:
    get:
      tags:
        - 音樂生成任務格式
      summary: 依 ID 查詢音樂任務
      description: >-
        透過 path `task_id` 查詢音樂生成任務。


        音樂生成任務查詢介面。建立介面返回的 `data` 即任務 ID，透過 `GET /suno/fetch/{task_id}` 查詢單個任務。


        ## 查詢方式


        ```http

        GET /suno/fetch/task_xxx

        ```


        ## 查詢輸出


        外層保持 new-api 任務結構：


        - `code`：成功時為 `success`。

        - `message`：錯誤或提示資訊。

        - `data.task_id`：任務 ID。

        - `data.status`：任務狀態，常見值
        `NOT_START`、`SUBMITTED`、`QUEUED`、`IN_PROGRESS`、`SUCCESS`、`FAILURE`。

        - `data.progress`：任務進度。

        - `data.result_url`：成功後可用的結果位址，若上游返回多首歌曲，以 `data.data` 內片段為準。

        - `data.data`：上游音樂結果原始資料，通常包含歌曲片段陣列或物件。


        成功態範例：


        ```json

        {
          "code": "success",
          "message": "",
          "data": {
            "task_id": "task_xxx",
            "platform": "suno",
            "action": "MUSIC",
            "status": "SUCCESS",
            "progress": "100%",
            "result_url": "https://example.com/audio.mp3",
            "properties": {
              "upstream_model_name": "suno_music",
              "origin_model_name": "suno-v5.5"
            },
            "data": [
              {
                "id": "clip_xxx",
                "title": "夏日海风",
                "audio_url": "https://example.com/audio.mp3",
                "image_url": "https://example.com/cover.jpg",
                "model_name": "suno-v5.5",
                "metadata": {
                  "duration": 180,
                  "prompt": "轻快电子流行，夏日海边，女声 旋律"
                }
              }
            ]
          }
        }

        ```
      parameters:
        - name: task_id
          in: path
          required: true
          schema:
            type: string
            example: task_xxx
          description: 提交音樂任務後返回的任務 ID。
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    example: success
                    description: 成功時為 `success`。
                  message:
                    type: string
                    description: 錯誤或提示資訊。
                  data:
                    type: object
                    properties:
                      task_id:
                        type: string
                        description: 任務 ID。
                      status:
                        type: string
                        description: >-
                          任務狀態，常見值
                          `NOT_START`、`SUBMITTED`、`QUEUED`、`IN_PROGRESS`、`SUCCESS`、`FAILURE`。
                      progress:
                        type: string
                        description: 任務進度。
                      result_url:
                        type: string
                        description: 成功後可用的結果地址。
                      data:
                        type: string
                        items:
                          type: object
                          properties:
                            audio_url:
                              type: string
                              description: 歌曲音訊 URL。
                            image_url:
                              type: string
                              description: 歌曲封面 URL。
                            title:
                              type: string
                              description: 歌曲標題。
                            metadata:
                              type: object
                              properties:
                                duration:
                                  type: string
                                  description: 音訊長度。
              examples:
                music_fetch_success:
                  summary: 音樂任務查詢成功
                  value:
                    code: success
                    message: ''
                    data:
                      task_id: task_xxx
                      platform: suno
                      action: MUSIC
                      status: SUCCESS
                      progress: 100%
                      result_url: https://example.com/audio.mp3
                      properties:
                        upstream_model_name: suno_music
                        origin_model_name: suno-v5.5
                      data:
                        - id: clip_xxx
                          title: 夏日海风
                          audio_url: https://example.com/audio.mp3
                          image_url: https://example.com/cover.jpg
                          model_name: suno-v5.5
                          metadata:
                            duration: 180
                            prompt: 轻快电子流行，夏日海边，女声 旋律
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: |-
        使用 Bearer Token 認證。
        格式: `Authorization: Bearer sk-xxxxxx`

````