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

# 恢复音频

> 为已有的音乐生成任务恢复可播放的音频链接。

用于为已经生成完成的音乐任务恢复可播放的音频链接。传入原任务的 `sunoTaskId`，服务会为该任务下的每一首音轨重新生成可访问的音频地址。

## 🚀 使用指南

* Suno 的原始链接只在一段时间内有效，失效后无法再通过该地址播放或下载音频。
* 传入原音乐生成任务的 `sunoTaskId`，该任务下的所有音轨会一起恢复。
* 本接口只负责创建任务：立即返回恢复任务的 `task_id`，实际恢复过程为异步执行。
* 任务结束后结果会推送到 `callBackUrl`，也可通过轮询[获取恢复音频详情](/cn/suno-api/get-recovery-audio-details)获取。

<Warning>
  **`source_audio_url` 已废弃。**

  生成结果与回调中的 `source_audio_url` 指向 Suno 的原始文件，该链接会在一段时间后失效且不再维护，不能作为长期存储使用。请改用本接口重新获取可播放的链接。
</Warning>

## 📌 使用场景

* 🔗 恢复很久之前生成的歌曲的播放能力
* 📦 归档或迁移自有曲库前刷新音频链接
* 🛠️ 修复用户反馈的音频地址失效问题

## ⚠️ 注意事项

* 请求体中的 `sunoTaskId` 是**音乐生成任务 ID**（例如[生成音乐](/cn/suno-api/generate-music)返回的 ID），不是本接口返回的 ID。
* 返回的 `task_id` 是**恢复任务 ID**，只能用于调用[获取恢复音频详情](/cn/suno-api/get-recovery-audio-details)。
* `callBackUrl` 为必填，恢复任务结束后结果会推送到该地址。
* 任务创建成功不代表每一首音轨都能恢复成功，最终结果以每条记录的 `status` 为准。

## 📩 回调说明

恢复任务结束后，会向 `callBackUrl` 发起 `POST` 请求：

```json theme={null}
{
  "code": 200,
  "msg": "success",
  "task_id": "bbbb****0f7b",
  "data": [
    {
      "id": "3bc3****48fc",
      "audio_url": "https://example.com/****.m4a",
      "title": "Sunrise Love",
      "status": "success",
      "error": ""
    }
  ]
}
```

任务级 `code` 为 `200` 表示至少有一首音轨恢复成功，为 `500` 表示全部失败。`data` 的顺序与原任务的音轨顺序一致。


## OpenAPI

````yaml cn/suno-api/suno-api-cn.json POST /api/v1/suno/recovery
openapi: 3.0.0
info:
  title: intro
  description: 这是生成音频的API接口文档
  version: 1.0.0
  contact:
    name: 技术支持
    email: support@api.box
servers:
  - url: https://apibox.erweima.ai
    description: API 服务器
security:
  - BearerAuth: []
tags:
  - name: Music Generation
    description: 用于创建和管理音乐生成任务的接口
  - name: Lyrics Generation
    description: 用于歌词生成和管理的接口
  - name: WAV Conversion
    description: 用于将音乐转换为WAV格式的接口
  - name: Vocal Removal
    description: 用于从音乐轨道中移除人声的接口
  - name: Music Video Generation
    description: 用于生成MP4视频的接口
  - name: Account Management
    description: 用于账户和积分管理的接口
  - name: Audio Enhancement
    description: 用于增强和修改现有音频的伴奏和人声元素的接口
paths:
  /api/v1/suno/recovery:
    post:
      summary: 恢复音频
      description: |-
        为已完成的音乐生成任务恢复可播放的音频链接。

        ## 使用指南
        - Suno 原始链接（`source_audio_url`）仅在一段时间内有效，现已废弃。
        - 传入原音乐生成任务的 `sunoTaskId`，该任务下的所有音轨会一起恢复。
        - 本接口仅负责创建任务并立即返回，结果会推送到必填的 `callBackUrl`，也可通过轮询「获取恢复音频详情」获取。
      operationId: recovery-audio
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - sunoTaskId
                - callBackUrl
              properties:
                sunoTaskId:
                  type: string
                  description: 需要恢复音频链接的原音乐生成任务 ID。
                  example: 5c79****be8e
                callBackUrl:
                  type: string
                  format: uri
                  description: 恢复任务完成后的回调通知地址，恢复结果会推送到该地址。
                  example: https://api.example.com/callback
      responses:
        '200':
          description: 请求成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          task_id:
                            type: string
                            description: 恢复任务 ID，用于调用「获取恢复音频详情」接口。
                            example: dc19****18b3
        '500':
          $ref: '#/components/responses/Error'
components:
  schemas:
    ApiResponse:
      type: object
      properties:
        code:
          type: integer
          description: |-
            # 状态码说明

            - ✅ 200 - 请求成功
            - ⚠️ 400 - 参数错误
            - ⚠️ 401 - 没有访问权限
            - ⚠️ 404 - 请求方式或者路径错误
            - ⚠️ 405 - 调用超过限制
            - ⚠️ 413 - 主题或者prompt过长
            - ⚠️ 429 - 积分不足
            - ⚠️ 430 - 您的调用频率过高。请稍后再试。
            - ⚠️ 455 - 网站维护
            - ❌ 500 - 服务器异常
          example: 200
          enum:
            - 200
            - 400
            - 401
            - 404
            - 405
            - 413
            - 429
            - 430
            - 455
            - 500
        msg:
          type: string
          description: 当 code != 200 时，展示错误信息
          example: success
  responses:
    Error:
      description: 服务器异常
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: |-
        # 🔑 API 认证说明

        所有接口都需要通过 Bearer Token 方式进行认证。

        ## 获取 API Key

        1. 访问 [API Key 管理页面](https://api.box/api-key) 获取您的 API Key

        ## 使用方式

        在请求头中添加：

        ```
        Authorization: Bearer YOUR_API_KEY
        ```

        > **⚠️ 注意：**
        > - 请妥善保管您的 API Key，不要泄露给他人
        > - 如果怀疑 API Key 泄露，请立即在管理页面重置

````