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

# Suno 人声分离任务信息

> 查询 Suno 人声分离任务的状态和结果。

## API 接口

```
GET https://api.crun.ai/api/v1/client/job/TaskInfo
```

<Info>
  此接口用于查询通过 `/api/v1/client/job/CreateTask` API 创建的 Suno 人声分离任务的执行状态，并获取任务结果。\
  它与[通用任务查询](https://docs.crun.ai/zh/models/common/get-task-info)使用相同的接口、参数和任务状态枚举，但任务结果中**不**包含 `media_urls` 或 `suno_data`。
  相反，它会返回一个 `media_info` 对象，其中包含根据不同分离模式而变化的音频分轨 URL。
</Info>

## 查询参数

<ParamField query="task_id" type="string" required>
  创建任务时返回的唯一任务标识符。

  **示例**：`task_12345678`
</ParamField>

## 请求示例

<CodeGroup>
  ```bash cURL theme={null} theme={null}
  curl -X GET "https://api.crun.ai/api/v1/client/job/TaskInfo?task_id=task_12345678" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json"

  ```

  ```python Python theme={null} theme={null}
  import requests

  API_KEY = "YOUR_API_KEY"

  headers = {
    "X-API-KEY": API_KEY,
    "Content-Type": "application/json"
  }
  params = {
    "task_id": "task_12345678",
  }

  GET_TASK_STATUS_URL = "https://api.crun.ai/api/v1/client/job/TaskInfo"

  response = requests.get(GET_TASK_STATUS_URL, params=params, headers=headers)
  print(response.json())
  ```

  ```javascript Node.js theme={null} theme={null}
  const API_KEY = "YOUR_API_KEY";
  const taskId = "task_12345678";

  const url = new URL("https://api.crun.ai/api/v1/client/job/TaskInfo");
  url.searchParams.append("task_id", taskId);

  fetch(url.toString(), {
    method: "GET",
    headers: {
        "X-API-KEY": API_KEY,
        "Content-Type": "application/json",
    },
  })
    .then(res => res.json())
    .then(data => {
        console.log(data);
    })
    .catch(err => {
        console.error("请求失败:", err);
    });
  ```
</CodeGroup>

<ResponseExample title="响应示例">
  ```json 任务运行中 theme={null}
  {
    "code": 200,
    "message": "success",
    "data": {
      "task_id": "d6956973-2f17-43d4-8514-af6cc3a2f55d",
      "provider": "Suno",
      "model_version": "suno-vocal-separation",
      "status": "running",
      "param": {
        "model": "suno/vocal-separatio",
        "callback_url": null,
        "input": {
          "task_id": "task_12345678",
          "suno_id": "suno_abc123",
          "mode": "vocal"
        }
      },
      "credits": 10,
      "create_at": 1768900378,
      "result": null,
      "duration_s": null,
      "complete_at": null,
      "source": "api"
    }
  }
  ```

  ```json 任务成功（人声模式） theme={null}
  {
    "code": 200,
    "message": "success",
    "data": {
      "task_id": "d6956973-2f17-43d4-8514-af6cc3a2f55d",
      "provider": "Suno",
      "model_version": "suno-vocal-separation",
      "status": "success",
      "param": {
        "model": "suno/vocal-separatio",
        "callback_url": null,
        "input": {
          "task_id": "task_12345678",
          "suno_id": "suno_abc123",
          "mode": "vocal"
        }
      },
      "create_at": 1768900378,
      "result": {
        "code": 200,
        "message": "generation success",
        "media_info": {
          "origin_url": "https://example.com/origin.mp3",
          "vocal_url": "https://example.com/vocal.mp3",
          "instrumental_url": "https://example.com/instrumental.mp3"
        }
      },
      "credits": 10,
      "duration_s": 137,
      "complete_at": 1768900515,
      "source": "api"
    }
  }
  ```

  ```json 任务成功（乐器分轨模式） theme={null}
  {
    "code": 200,
    "message": "success",
    "data": {
      "task_id": "d6956973-2f17-43d4-8514-af6cc3a2f55d",
      "provider": "Suno",
      "model_version": "suno-vocal-separation",
      "status": "success",
      "param": {
        "model": "suno/vocal-separatio",
        "callback_url": null,
        "input": {
          "task_id": "task_12345678",
          "suno_id": "suno_abc123",
          "mode": "instrumental"
        }
      },
      "create_at": 1768900378,
      "result": {
        "code": 200,
        "message": "generation success",
        "media_info": {
          "origin_url": "https://example.com/origin.mp3",
          "vocal_url": "https://example.com/vocal.mp3",
          "backing_vocals_url": "https://example.com/backing_vocals.mp3",
          "drums_url": "https://example.com/drums.mp3",
          "bass_url": "https://example.com/bass.mp3",
          "guitar_url": "https://example.com/guitar.mp3",
          "keyboard_url": "https://example.com/keyboard.mp3",
          "percussion_url": "https://example.com/percussion.mp3",
          "strings_url": "https://example.com/strings.mp3",
          "synth_url": "https://example.com/synth.mp3",
          "fx_url": "https://example.com/fx.mp3",
          "brass_url": "https://example.com/brass.mp3",
          "woodwinds_url": "https://example.com/woodwinds.mp3"
        }
      },
      "credits": 50,
      "duration_s": 137,
      "complete_at": 1768900515,
      "source": "api"
    }
  }
  ```

  ```json 任务失败 theme={null}
  {
    "code": 200,
    "message": "success",
    "data": {
      "task_id": "d6956973-2f17-43d4-8514-af6cc3a2f55d",
      "provider": "Suno",
      "model_version": "suno-vocal-separation",
      "status": "failed",
      "param": {
        "model": "suno/vocal-separatio",
        "callback_url": null,
        "input": {
          "task_id": "task_12345678",
          "suno_id": "suno_abc123",
          "mode": "vocal"
        }
      },
      "create_at": 1768900378,
      "result": {
        "code": 501,
        "message": "generation failed"
      },
      "credits": 0,
      "duration_s": 137,
      "complete_at": 1768900515,
      "source": "api"
    }
  }
  ```
</ResponseExample>

## 响应格式

<ResponseField name="code" type="integer">
  响应状态码。200 表示请求已成功处理（无论任务执行结果如何，只要任务被找到并返回）。
</ResponseField>

<ResponseField name="message" type="string">
  响应消息。通常为 `"success"`。
</ResponseField>

<ResponseField name="data" type="object">
  包含所有任务信息的任务数据对象。

  <Expandable title="data 属性">
    <ResponseField name="task_id" type="string">
      任务的唯一标识符。
    </ResponseField>

    <ResponseField name="provider" type="string">
      模型提供方名称。

      **示例**：`Suno`
    </ResponseField>

    <ResponseField name="model_version" type="string">
      创建任务时使用的具体模型版本。
    </ResponseField>

    <ResponseField name="status" type="string">
      任务当前状态。详情请参见下方的[任务状态枚举](#任务状态枚举)。

      **可能的值**：`pending`、`running`、`success`、`failed`
    </ResponseField>

    <ResponseField name="param" type="object">
      创建任务时使用的原始参数。

      <Expandable title="param 属性">
        <ResponseField name="model" type="string">
          创建任务时使用的模型标识符。
        </ResponseField>

        <ResponseField name="callback_url" type="string | null">
          为此任务配置的 Webhook 回调 URL。
        </ResponseField>

        <ResponseField name="input" type="object">
          模型专属的输入参数。其结构会因所选模型而异。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="result" type="object | null">
      任务生成结果。
      仅当任务状态为 `success` 或 `failed` 时才会返回有效值；否则返回 `null`。

      <Expandable title="result 属性">
        <ResponseField name="code" type="integer">
          任务生成结果状态码。`200` 表示生成成功。非 200 值表示生成失败。
        </ResponseField>

        <ResponseField name="message" type="string">
          任务成功或失败的说明。
        </ResponseField>

        <ResponseField name="media_info" type="object">
          分离后的音频媒体 URL。仅在状态为 `success` 时返回。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="credits" type="number">
      任务消耗的积分，任务状态是`pending` 或 `running` 时表示预扣积分，任务状态是 `success` 或 `failed` 时表示实际消耗积分。
    </ResponseField>

    <ResponseField name="create_at" type="integer">
      任务创建时的 Unix 时间戳（秒）。
    </ResponseField>

    <ResponseField name="complete_at" type="integer | null">
      任务完成时的 Unix 时间戳（秒）。
      如果任务尚未完成，则为 `null`。
    </ResponseField>

    <ResponseField name="duration_s" type="integer | null">
      任务执行耗时，单位为秒。如果任务尚未完成，则为 null。
    </ResponseField>

    <ResponseField name="source" type="string">
      任务创建来源。
    </ResponseField>
  </Expandable>
</ResponseField>

## Media Info 对象

<ResponseField name="origin_url" type="string">
  原始音频 URL。
</ResponseField>

<ResponseField name="vocal_url" type="string">
  主人声音频 URL。
</ResponseField>

<ResponseField name="instrumental_url" type="string">
  伴奏部分音频 URL（仅人声模式）。
</ResponseField>

<ResponseField name="backing_vocals_url" type="string">
  和声音频 URL（仅乐器分轨模式）。
</ResponseField>

<ResponseField name="drums_url" type="string">
  鼓组部分音频 URL（仅乐器分轨模式）。
</ResponseField>

<ResponseField name="bass_url" type="string">
  贝斯部分音频 URL（仅乐器分轨模式）。
</ResponseField>

<ResponseField name="guitar_url" type="string">
  吉他部分音频 URL（仅乐器分轨模式）。
</ResponseField>

<ResponseField name="keyboard_url" type="string">
  键盘部分音频 URL（仅乐器分轨模式）。
</ResponseField>

<ResponseField name="percussion_url" type="string">
  打击乐部分音频 URL（仅乐器分轨模式）。
</ResponseField>

<ResponseField name="strings_url" type="string">
  弦乐部分音频 URL（仅乐器分轨模式）。
</ResponseField>

<ResponseField name="synth_url" type="string">
  合成器部分音频 URL（仅乐器分轨模式）。
</ResponseField>

<ResponseField name="fx_url" type="string">
  音效部分音频 URL（仅乐器分轨模式）。
</ResponseField>

<ResponseField name="brass_url" type="string">
  铜管部分音频 URL（仅乐器分轨模式）。
</ResponseField>

<ResponseField name="woodwinds_url" type="string">
  木管部分音频 URL（仅乐器分轨模式）。
</ResponseField>

## 任务状态枚举

| 状态        | 描述          | 操作                              |
| --------- | ----------- | ------------------------------- |
| `pending` | 任务正在队列中等待处理 | 继续轮询                            |
| `running` | 任务正在处理中     | 继续轮询                            |
| `success` | 任务已成功完成     | 访问 `result.media_info` 获取分轨 URL |
| `failed`  | 任务失败        | 访问 result 对象查看错误码和错误消息。         |

## 获取任务结果最佳实践

<AccordionGroup>
  <Accordion title="推荐轮询间隔">
    * **轮询间隔**：使用 15 到 30 秒的轮询间隔
    * **动态调整间隔**：对于长时间运行的音频处理任务，可以考虑动态增加轮询间隔
    * **延迟首次轮询**：在首次检查状态前至少等待一个轮询间隔，以减少不必要的请求
    * **最大轮询时长**：15-20 分钟后停止轮询并进行排查

    <Warning>
      过于频繁的轮询可能会触发请求频率限制。生产环境建议使用回调。
    </Warning>
  </Accordion>

  <Accordion title="使用回调替代轮询">
    对于生产应用，我们强烈建议在创建任务时使用 `callback_url` 参数：

    * **无需轮询**：你的服务器会自动接收通知
    * **降低 API 成本**：避免持续轮询请求
    * **更好的性能**：任务完成后立即通知
    * **降低延迟**：完成与通知之间没有轮询等待延迟

    <Tip>
      推荐方式
    </Tip>
  </Accordion>

  <Accordion title="处理已完成任务">
    当 `status` 为 `success` 时：

    1. 从响应中的 `result` 字段获取任务结果
    2. 从 `result.media_info` 中提取分轨 URL
    3. 将音频文件下载到你自己的存储中
    4. 将结果元数据持久化到你的存储或数据库中

    <Warning>
      **重要**：生成的媒体 URL 通常会在 14 天后被永久删除
    </Warning>
  </Accordion>
</AccordionGroup>

## 常见错误码

| Code  | 描述                  | 解决方案                       |
| ----- | ------------------- | -------------------------- |
| `401` | 未授权 - API Key 无效或缺失 | 检查你的 API Key               |
| `404` | 任务未找到               | 确认 task\_id 是否正确           |
| `429` | 超出请求频率限制            | 降低请求频率                     |
| `500` | 内部服务器错误             | 几分钟后重试                     |
| `501` | 生成失败                | 查看 `result` 对象以获取错误码和错误消息。 |

## 速率限制

* **最大查询频率**：每个账户每秒最多 15 次请求
* **推荐间隔**：每次轮询间隔 15-30 秒

## 相关资源

<CardGroup cols={2}>
  <Card title="人声分离" icon="music" href="/zh/suno-api/vocal-separation">
    创建人声分离任务
  </Card>

  <Card title="Suno 快速开始" icon="sparkles" href="/zh/suno-api/quickstart">
    了解如何调用 Suno 模型
  </Card>
</CardGroup>


## OpenAPI

````yaml zh/suno-api/vocal-separation-task-info.json get /api/v1/client/job/TaskInfo
openapi: 3.0.0
info:
  title: Suno 人声分离任务信息
  description: 查询 Suno 人声分离任务的状态和结果。
  version: 1.0.0
  contact:
    name: 技术支持
    email: support@crun.ai
servers:
  - url: https://api.crun.ai
    description: API 服务器
security:
  - ApiKeyAuth: []
paths:
  /api/v1/client/job/TaskInfo:
    get:
      summary: 查询 Suno 人声分离任务的状态和结果。
      operationId: suno-vocal-separation-task-info
      parameters:
        - name: task_id
          in: query
          required: true
          description: 用于获取任务结果的任务 ID。
          schema:
            type: string
            minLength: 36
            maxLength: 36
            example: task_1234567
      responses:
        '200':
          description: 任务信息获取成功，或任务未找到。
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        $ref: '#/components/schemas/TaskResponseModel'
        '401':
          description: 缺少 API Key
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
              example:
                code: 401
                message: API key missing
                data: null
        '403':
          description: API Key 已被禁用
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
              example:
                code: 403
                message: API key disabled
                data: null
        '404':
          description: 任务未找到
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
              example:
                code: 404
                message: Task not found
                data: null
        '500':
          $ref: '#/components/responses/Error'
components:
  schemas:
    ApiResponse:
      type: object
      properties:
        code:
          type: integer
          description: |-
            响应状态码

            - **200**：成功 - 请求已成功处理
            - **401**：未授权 - 身份验证凭证缺失或无效
            - **402**：积分不足 - 账户没有足够的积分执行该操作
            - **404**：未找到 - 请求的资源或接口不存在
            - **422**：验证错误 - 请求参数未通过验证检查
            - **429**：请求频率受限 - 已超过该资源的请求限制
            - **455**：服务不可用 - 系统当前正在维护
            - **500**：服务器错误 - 处理请求时发生意外错误
            - **501**：生成失败 - 内容生成任务失败
            - **505**：功能已禁用 - 请求的功能当前已被禁用
        message:
          type: string
          description: 响应消息
        data:
          nullable: true
      required:
        - code
        - message
    TaskResponseModel:
      type: object
      description: 任务记录和结果信息。
      properties:
        task_id:
          type: string
          description: 任务 ID
          example: task_1234567
        provider:
          type: string
          description: 模型提供方
          example: Suno
        model_version:
          type: string
          description: 模型版本
          example: suno-vocal-separation
        status:
          type: string
          description: 任务状态
          enum:
            - pending
            - running
            - success
            - failed
          example: success
        param:
          type: object
          description: 创建任务时使用的原始参数。
        create_at:
          type: integer
          description: 任务创建时间戳（秒）
          example: 1768900378
        result:
          type: object
          nullable: true
          description: 任务生成结果。仅当状态为 `success` 或 `failed` 时返回。
          properties:
            code:
              type: integer
              description: 任务生成结果状态码。200 表示生成成功。
              example: 200
            message:
              type: string
              description: 任务成功或失败的说明。
              example: generation success
            media_info:
              $ref: '#/components/schemas/VocalSeparationMediaInfo'
          required:
            - code
            - message
        credits:
          type: number
          description: >-
            任务消耗的积分，任务状态是`pending` 或 `running` 时表示预扣积分，任务状态是 `success` 或
            `failed` 时表示实际消耗积分。
          example: 10
        duration_s:
          type: integer
          nullable: true
          description: 任务执行耗时，单位为秒
          example: 137
        complete_at:
          type: integer
          nullable: true
          description: 任务完成时间戳（秒）
          example: 1768900515
        source:
          type: string
          description: 任务来源
          enum:
            - api
            - playground
          example: api
      required:
        - task_id
        - provider
        - model_version
        - status
        - param
        - create_at
        - source
    VocalSeparationMediaInfo:
      type: object
      description: 分离后的音频媒体 URL。仅在状态为 `success` 时返回。字段取决于分离模式。
      properties:
        origin_url:
          type: string
          format: uri
          description: 原始音频 URL。
          example: https://example.com/origin.mp3
        vocal_url:
          type: string
          format: uri
          description: 主人声音频 URL。
          example: https://example.com/vocal.mp3
        instrumental_url:
          type: string
          format: uri
          description: 伴奏部分音频 URL（仅人声模式）。
          example: https://example.com/instrumental.mp3
        backing_vocals_url:
          type: string
          format: uri
          description: 和声音频 URL（仅乐器分轨模式）。
          example: https://example.com/backing_vocals.mp3
        drums_url:
          type: string
          format: uri
          description: 鼓组部分音频 URL（仅乐器分轨模式）。
          example: https://example.com/drums.mp3
        bass_url:
          type: string
          format: uri
          description: 贝斯部分音频 URL（仅乐器分轨模式）。
          example: https://example.com/bass.mp3
        guitar_url:
          type: string
          format: uri
          description: 吉他部分音频 URL（仅乐器分轨模式）。
          example: https://example.com/guitar.mp3
        keyboard_url:
          type: string
          format: uri
          description: 键盘部分音频 URL（仅乐器分轨模式）。
          example: https://example.com/keyboard.mp3
        percussion_url:
          type: string
          format: uri
          description: 打击乐部分音频 URL（仅乐器分轨模式）。
          example: https://example.com/percussion.mp3
        strings_url:
          type: string
          format: uri
          description: 弦乐部分音频 URL（仅乐器分轨模式）。
          example: https://example.com/strings.mp3
        synth_url:
          type: string
          format: uri
          description: 合成器部分音频 URL（仅乐器分轨模式）。
          example: https://example.com/synth.mp3
        fx_url:
          type: string
          format: uri
          description: 音效部分音频 URL（仅乐器分轨模式）。
          example: https://example.com/fx.mp3
        brass_url:
          type: string
          format: uri
          description: 铜管部分音频 URL（仅乐器分轨模式）。
          example: https://example.com/brass.mp3
        woodwinds_url:
          type: string
          format: uri
          description: 木管部分音频 URL（仅乐器分轨模式）。
          example: https://example.com/woodwinds.mp3
  responses:
    Error:
      description: 服务器错误
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: |-
        所有 API 都需要通过 API Key 进行身份验证。

        获取 API Key：
        1. 访问 [API Key 管理页面](https://crun.ai/zh/user-api-key) 获取你的 API Key

        使用方式：
        添加到请求头：

        x-api-key: YOUR_API_KEY

        注意：
        - 请妥善保管你的 API Key，不要与他人共享
        - 如果你怀疑 API Key 已泄露，请立即在管理页面中重置

````