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

# 替换片段

> 指定歌曲中的一段时间，用新歌词或风格重写这一段。

> 能力按服务端配置逐项启用。未启用操作返回 503 且不创建任务；音乐积分扣除当前未启用。

## 调用步骤

指定歌曲中的一段时间，用新歌词或风格重写这一段。

* 1. 按下方示例准备输入，将占位地址和 ID 换成你有权使用的资源。
* 2. 将 model 设为 suno\_replace\_section，参数放在 input 内。提交一次并保存返回的 task\_id。
* 3. 查询已保存的任务，或接收回调。任务仍在处理中时继续等待，不重新提交同一操作。
* 从 result.data.data 读取作品。每首歌曲都有独立的本站 id，后续任务可将其作为 audio\_id。

## 创建任务

将model和input发送到统一任务入口；可在顶层传公开HTTPS callback\_url。资源ID均为本账户的本站ID。当前音乐积分扣除未启用。

```json theme={null}
{
  "model": "suno_replace_section",
  "input": {
    "audio_id": "YOUR_AUDIO_ID",
    "prompt": "[Verse] A new beginning",
    "tags": "Pop",
    "title": "New verse",
    "infill_start_s": 20,
    "infill_end_s": 40,
    "full_lyrics": "Original full lyrics"
  }
}
```

## 受理响应

HTTP 200仅表示受理。查询GET /api/v1/tasks/\{task\_id}，直到data.status为succeeded或failed。成功后读取data.result；失败原因位于data.message。

```json theme={null}
{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "YOUR_TASK_ID"
  }
}
```

## 参数速查

| 字段 | 类型 | 必填 | 说明与限制 |
| - | - | - | - |
| vocal\_gender | string | 否 / 依条件 | m 或 f，表示人声倾向，不保证特定声音身份；生成时仅限自定义模式。 values: m, f |
| style\_weight | number | 否 / 依条件 | 风格影响程度，0–1，最多两位小数；生成时仅限自定义模式。 min: 0; max: 1 |
| weirdness\_constraint | number | 否 / 依条件 | 创意约束，0–1，最多两位小数；生成时仅限自定义模式。 min: 0; max: 1 |
| audio\_weight | number | 否 / 依条件 | 音频影响程度，0–1，最多两位小数；生成时仅限自定义且非纯音乐模式。 min: 0; max: 1 |
| variety | integer | 否 / 依条件 | 多样性，0–4 整数，自定义生成默认 1。 min: 0; max: 4 |
| persona\_id | string | 否 / 依条件 | 本站 Voice 或 Persona ID；供应商 root 和原曲映射由后台处理。 maxLength: 200 |
| persona\_model | string | 否 / 依条件 | style\_persona 或 voice\_persona，须与资源真实来源匹配。 values: style\_persona, voice\_persona |
| audio\_id | string | 是 | 本账户的本站歌曲ID。翻唱/续写只传此ID，不传源task\_id或外部URL。 maxLength: 200 |
| prompt | string | 是 | 必填替换提示文本，最多5000字符；lyrics不能替代此字段。 maxLength: 5000 |
| tags | string | 是 | 此操作的音乐风格，最多 1000 字符。 maxLength: 1000 |
| title | string | 是 | 标题。生成/翻唱最多 80 字符，续写及其他操作最多 100 字符；自定义生成必填。 maxLength: 100 |
| infill\_start\_s | number | 是 | 替换开始位置（秒），最多两位小数。 min: 0 |
| infill\_end\_s | number | 是 | 替换结束位置（秒），最多两位小数，不能超出原曲。替换区间须为10–120秒且不超过原曲时长的一半。 min: 0 |
| full\_lyrics | string | 是 | 包含替换段落并放在正确位置的完整歌词。 maxLength: 5000 |
| lyrics | string | 否 / 依条件 | 可选替换段歌词，最多5000字符，省略时使用prompt；不替代full\_lyrics或主提示文本。 maxLength: 5000 |
| negative\_tags | string | 否 / 依条件 | 排除的风格；增加伴奏或人声时必填。 maxLength: 1000 |
| result\_mode | string | 否 / 依条件 | 续写/替换：full\_song（默认）或 segment；加轨：mixed（默认）或 stem；完整/混合结果等待合并完成。 values: full\_song, segment; default: full\_song |

## 输入与限制

下方Schema列出支持字段、类型和基础限制；还须遵守“重要条件”，跨字段与来源资源校验不完全体现在JSON Schema中。未知参数会被拒绝。URL 参数仅接受公开 HTTPS 地址，不接受文件对象。

```json theme={null}
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "vocal_gender": {
      "type": "string",
      "enum": [
        "m",
        "f"
      ],
      "description": "m 或 f，表示人声倾向，不保证特定声音身份；生成时仅限自定义模式。"
    },
    "style_weight": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "description": "风格影响程度，0–1，最多两位小数；生成时仅限自定义模式。"
    },
    "weirdness_constraint": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "description": "创意约束，0–1，最多两位小数；生成时仅限自定义模式。"
    },
    "audio_weight": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "description": "音频影响程度，0–1，最多两位小数；生成时仅限自定义且非纯音乐模式。"
    },
    "variety": {
      "type": "integer",
      "minimum": 0,
      "maximum": 4,
      "description": "多样性，0–4 整数，自定义生成默认 1。"
    },
    "persona_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "本站 Voice 或 Persona ID；供应商 root 和原曲映射由后台处理。"
    },
    "persona_model": {
      "type": "string",
      "enum": [
        "style_persona",
        "voice_persona"
      ],
      "description": "style_persona 或 voice_persona，须与资源真实来源匹配。"
    },
    "audio_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "本账户的本站歌曲ID。翻唱/续写只传此ID，不传源task_id或外部URL。"
    },
    "prompt": {
      "type": "string",
      "maxLength": 5000,
      "description": "必填替换提示文本，最多5000字符；lyrics不能替代此字段。"
    },
    "tags": {
      "type": "string",
      "maxLength": 1000,
      "description": "此操作的音乐风格，最多 1000 字符。"
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100,
      "description": "标题。生成/翻唱最多 80 字符，续写及其他操作最多 100 字符；自定义生成必填。"
    },
    "infill_start_s": {
      "type": "number",
      "minimum": 0,
      "description": "替换开始位置（秒），最多两位小数。"
    },
    "infill_end_s": {
      "type": "number",
      "minimum": 0,
      "description": "替换结束位置（秒），最多两位小数，不能超出原曲。替换区间须为10–120秒且不超过原曲时长的一半。"
    },
    "full_lyrics": {
      "type": "string",
      "maxLength": 5000,
      "description": "包含替换段落并放在正确位置的完整歌词。"
    },
    "lyrics": {
      "type": "string",
      "maxLength": 5000,
      "description": "可选替换段歌词，最多5000字符，省略时使用prompt；不替代full_lyrics或主提示文本。"
    },
    "negative_tags": {
      "type": "string",
      "maxLength": 1000,
      "description": "排除的风格；增加伴奏或人声时必填。"
    },
    "result_mode": {
      "default": "full_song",
      "type": "string",
      "enum": [
        "full_song",
        "segment"
      ],
      "description": "续写/替换：full_song（默认）或 segment；加轨：mixed（默认）或 stem；完整/混合结果等待合并完成。"
    }
  },
  "required": [
    "audio_id",
    "prompt",
    "tags",
    "title",
    "infill_start_s",
    "infill_end_s",
    "full_lyrics"
  ],
  "additionalProperties": false
}
```

## 重要条件

* 替换区间必须位于原曲内，至少10秒、最多120秒，且不超过原曲时长的一半；起止位置最多两位小数。prompt仍然必填；lyrics仅覆盖替换段歌词，full\_lyrics为替换后的完整歌曲歌词。
* Persona替换尚未开放；传persona\_id返回HTTP 422/code 42201。
* full\_song/mixed等待合并，segment/stem返回对应片段或器乐轨。合并失败不会把片段作为完整歌曲返回；部分成功会在结果消息中说明。
* 歌曲音频可能为MP3或M4A；需要真正MP3时使用suno\_export\_mp3。可选封面无法获取时可能为null，不影响音频使用。
* 上传文件保留24小时，生成文件保留14天，任务详情保留30天；复用文件沿用原到期时间。有效Voice/Persona身份映射与任务日志清理分开处理，请及时下载需长期保存的文件。

## 结果 Schema

创建响应为 \{code:200,msg:"success",data:\{task\_id}}，轮询 GET /api/v1/tasks/\{task\_id}。成功时 data.result 为符合下方 Schema 的对象，其他状态为 null；input 仍为 JSON 字符串。

```json theme={null}
{
  "type": "object",
  "required": [
    "code",
    "msg",
    "data"
  ],
  "properties": {
    "code": {
      "const": 200
    },
    "msg": {
      "type": "string"
    },
    "data": {
      "type": "object",
      "required": [
        "callbackType",
        "task_id",
        "data"
      ],
      "properties": {
        "callbackType": {
          "const": "complete"
        },
        "task_id": {
          "type": "string"
        },
        "data": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "id",
              "audio_url",
              "stream_audio_url",
              "image_url",
              "prompt",
              "lyrics",
              "model_name",
              "title",
              "createTime",
              "duration",
              "tags",
              "source_audio_url",
              "source_image_url",
              "source_stream_audio_url"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "audio_url": {
                "type": "string"
              },
              "stream_audio_url": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "image_url": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "prompt": {
                "type": "string"
              },
              "lyrics": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "model_name": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "title": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "createTime": {
                "type": [
                  "integer",
                  "null"
                ]
              },
              "duration": {
                "type": [
                  "number",
                  "null"
                ]
              },
              "tags": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "source_audio_url": {
                "type": "string"
              },
              "source_image_url": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "source_stream_audio_url": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          }
        }
      }
    }
  }
}
```

> 歌曲duration单位为秒，任务duration单位为毫秒；createTime是毫秒Unix时间戳或null。目前stream\_audio\_url和source\_stream\_audio\_url均为null；source\_audio\_url/source\_image\_url与audio\_url/image\_url指向同一本站托管副本，并非供应商直链。请遍历实际歌曲数组，注册上传音频不代表新生成两首歌曲。

## 相关流程

[Voice 完整四步](https://docs.apistable.com/zh/suno-voice-workflow.md)
[文件上传](https://docs.apistable.com/zh/file-upload.md)
[回调](https://docs.apistable.com/zh/webhooks.md)


## OpenAPI

````yaml openapi-suno-replace-section-zh.json POST /api/v1/tasks/create_task
openapi: 3.1.0
info:
  title: APIstable API
  version: 1.0.0-preview
  description: >-
    Public /api/v1 protocol. Valid API keys have the same account-scoped access.
    No client submission idempotency or max_credits. Enabled Suno operations use
    PayAPI and durable task processing. Media uses R2: uploads 24 hours,
    generated files 14 days, task logs 30 days. Music credit deduction is
    disabled. Unconfigured operations and LLM return 503.
servers:
  - url: https://apistable.com
    description: APIstable API
security: []
paths:
  /api/v1/tasks/create_task:
    post:
      summary: 替换片段
      description: 指定歌曲中的一段时间，用新歌词或风格重写这一段。
      operationId: suno_replace_section
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - model
                - input
              additionalProperties: false
              properties:
                model:
                  type: string
                  enum:
                    - suno_replace_section
                  example: suno_replace_section
                input:
                  $schema: https://json-schema.org/draft/2020-12/schema
                  type: object
                  properties:
                    vocal_gender:
                      type: string
                      enum:
                        - m
                        - f
                      description: m 或 f，表示人声倾向，不保证特定声音身份；生成时仅限自定义模式。
                    style_weight:
                      type: number
                      minimum: 0
                      maximum: 1
                      description: 风格影响程度，0–1，最多两位小数；生成时仅限自定义模式。
                    weirdness_constraint:
                      type: number
                      minimum: 0
                      maximum: 1
                      description: 创意约束，0–1，最多两位小数；生成时仅限自定义模式。
                    audio_weight:
                      type: number
                      minimum: 0
                      maximum: 1
                      description: 音频影响程度，0–1，最多两位小数；生成时仅限自定义且非纯音乐模式。
                    variety:
                      type: integer
                      minimum: 0
                      maximum: 4
                      description: 多样性，0–4 整数，自定义生成默认 1。
                    persona_id:
                      type: string
                      minLength: 1
                      maxLength: 200
                      description: 本站 Voice 或 Persona ID；供应商 root 和原曲映射由后台处理。
                    persona_model:
                      type: string
                      enum:
                        - style_persona
                        - voice_persona
                      description: style_persona 或 voice_persona，须与资源真实来源匹配。
                    audio_id:
                      type: string
                      minLength: 1
                      maxLength: 200
                      description: 本账户的本站歌曲ID。翻唱/续写只传此ID，不传源task_id或外部URL。
                    prompt:
                      type: string
                      maxLength: 5000
                      description: 必填替换提示文本，最多5000字符；lyrics不能替代此字段。
                    tags:
                      type: string
                      maxLength: 1000
                      description: 此操作的音乐风格，最多 1000 字符。
                    title:
                      type: string
                      minLength: 1
                      maxLength: 100
                      description: 标题。生成/翻唱最多 80 字符，续写及其他操作最多 100 字符；自定义生成必填。
                    infill_start_s:
                      type: number
                      minimum: 0
                      description: 替换开始位置（秒），最多两位小数。
                    infill_end_s:
                      type: number
                      minimum: 0
                      description: 替换结束位置（秒），最多两位小数，不能超出原曲。替换区间须为10–120秒且不超过原曲时长的一半。
                    full_lyrics:
                      type: string
                      maxLength: 5000
                      description: 包含替换段落并放在正确位置的完整歌词。
                    lyrics:
                      type: string
                      maxLength: 5000
                      description: 可选替换段歌词，最多5000字符，省略时使用prompt；不替代full_lyrics或主提示文本。
                    negative_tags:
                      type: string
                      maxLength: 1000
                      description: 排除的风格；增加伴奏或人声时必填。
                    result_mode:
                      default: full_song
                      type: string
                      enum:
                        - full_song
                        - segment
                      description: >-
                        续写/替换：full_song（默认）或 segment；加轨：mixed（默认）或
                        stem；完整/混合结果等待合并完成。
                  required:
                    - audio_id
                    - prompt
                    - tags
                    - title
                    - infill_start_s
                    - infill_end_s
                    - full_lyrics
                  additionalProperties: false
                callback_url:
                  type: string
                  format: uri
                  description: >-
                    Optional public HTTPS endpoint for signed completion
                    callbacks; no redirects or private IPs.
            example:
              model: suno_replace_section
              input:
                audio_id: YOUR_AUDIO_ID
                prompt: '[Verse] A new beginning'
                tags: Pop
                title: New verse
                infill_start_s: 20
                infill_end_s: 40
                full_lyrics: Original full lyrics
      responses:
        '200':
          description: Accepted task. Poll the common task endpoint or use callback_url.
          content:
            application/json:
              schema:
                type: object
                required:
                  - code
                  - msg
                  - data
                additionalProperties: false
                properties:
                  code:
                    const: 200
                  msg:
                    const: success
                  data:
                    type: object
                    required:
                      - task_id
                    additionalProperties: false
                    properties:
                      task_id:
                        type: string
        '400':
          description: >-
            40001 invalid JSON, 40002 invalid input/callback, 40003 unsupported
            parameter.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Invalid or revoked API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: '40201: Insufficient credits (live acceptance).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: '40401: Unknown model or resource not found in this account.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: '40901: Resource belongs to a different provider account.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '410':
          description: '41001: Source audio or temporary resource has expired.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: '41301: Request too large.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: '42201: Requested music combination is not enabled.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: '42901: Rate/concurrency limit (live acceptance).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: '50301: Service/provider unavailable. No live submission or charge.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    Error:
      type: object
      required:
        - code
        - msg
        - data
      properties:
        code:
          type: integer
        msg:
          type: string
        data:
          type: 'null'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Every valid key can submit and query its own account. Revoked keys are
        rejected.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.