> ## Documentation Index > Fetch the complete documentation index at: https://docs.poyo.ai/llms.txt > Use this file to discover all available pages before exploring further. # 延长音乐 > 基于源音轨创建续写，延长或修改现有音乐 > [!TIP] > > 1. 提交后会返回 `task_id`。如果提供了 `callback_url`，当任务状态变为 `finished` 或 `failed` 时，系统会向 `callback_url` 发送 POST 请求。 > 2. 无论是否提供 `callback_url`，都可以通过统一的[查询音乐详情](https://docs.poyo.ai/zh/api-manual/music-series/query-music-detail.md)接口获取结果。 `instrumental` 显式控制是否输出人声。仅当 `default_param_flag: true` 且使用 V5、V5\_5、V6、V6\_MINI 或 V6\_WILD 时，`persona_model` 才接受 `style_persona` 或 `voice_persona`，并需配合 `persona_id`。 ## 使用指南 * 此接口从指定位置延长现有音轨 * 你可以使用新的风格、提示词和标题自定义延长内容，也可以继承原音轨的设置 * `mv` 为必填。使用 `default_param_flag` 控制是否必须提供自定义的 `style`、`title` 和 `continue_at` ## 参数详情 * 自定义模式（`default_param_flag: true`）下： * `style`、`title` 和 `continue_at` 为**必填** * 延长人声时 `prompt` 为必填。当 `instrumental: true` 时不发送 `prompt`。 * `continue_at` 指定开始延长的时间点（秒） * 字符限制因模型而异： * **V4**：`prompt` 3000 个字符，`style` 200 个字符，`title` 80 个字符 * **V4\_5 和 V4\_5PLUS**：`prompt` 5000 个字符，`style` 1000 个字符，`title` 100 个字符 * **V4\_5ALL**：`prompt` 5000 个字符，`style` 1000 个字符，`title` 80 个字符 * **V5**：`prompt` 5000 个字符，`style` 1000 个字符，`title` 100 个字符 * **V5\_5**：`prompt` 5000 个字符，`style` 1000 个字符，`title` 100 个字符 * **V6、V6\_MINI 和 V6\_WILD**：`prompt` 5000 个字符，`style` 1000 个字符，`title` 100 个字符 * 简单模式（`default_param_flag: false`）下： * `audio_id` 和 `mv` 为必填；沿用源音轨的设置 ## 开发者说明 * 使用此接口前，请确保你有一个来自先前生成音轨的有效 `audio_id` * 延长内容会从指定的 `continue_at` 时间点无缝衔接 ## 可选参数 * `negative_tags` (string)：延长时要排除的音乐风格或特征。 * `vocal_gender` (string)：人声性别偏好。`m` 表示男声，`f` 表示女声。注意：此参数会提高概率，但不能保证一定遵循。 * `style_weight` (number)：对风格的遵循强度。范围 0-1，最多 2 位小数。 * `weirdness_constraint` (number)：控制创意偏离程度。范围 0-1，最多 2 位小数。 * `audio_weight` (number)：音频特征的平衡权重。范围 0-1，最多 2 位小数。 * `persona_id` (string)：应用于延长音乐的 Persona ID。仅在 `default_param_flag: true` 且使用 V5、V5\_5、V6、V6\_MINI 或 V6\_WILD 时可用。如何生成 persona\_id，请参阅 [generate-persona](https://docs.poyo.ai/zh/api-manual/music-series/generate-persona.md)。 * `persona_model` (string)：`style_persona` 或 `voice_persona`。需要 `persona_id`、`default_param_flag: true`，且使用 V5、V5\_5、V6、V6\_MINI 或 V6\_WILD。 ## OpenAPI ````yaml zh/api-manual/music-series/extend-music.json POST /api/generate/submit openapi: 3.1.0 info: title: PoYo AI - 扩展音乐 API description: 基于源音轨创建续写，从而扩展或修改已有音乐 version: 1.0.0 servers: - url: https://api.poyo.ai description: 生产环境 security: - BearerAuth: [] paths: /api/generate/submit: post: tags: - Music Extension summary: 提交音乐扩展任务 description: 基于源音轨创建续写，从而扩展或修改已有音乐 operationId: submitExtendMusicTask requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubmitRequest' examples: custom-mode: summary: 自定义模式 - 完全控制 value: model: extend-music callback_url: https://your-domain.com/callback input: default_param_flag: true audio_id: audio_abc123 instrumental: false prompt: Continue with an energetic chorus section style: Pop, Upbeat title: Summer Vibes Extended continue_at: 120 mv: V5_5 negative_tags: Heavy Metal, Sad style_weight: 0.7 simple-mode: summary: 简单模式 - 使用原始参数 value: model: extend-music callback_url: https://your-domain.com/callback input: default_param_flag: false audio_id: audio_abc123 mv: V4_5PLUS responses: '200': description: 任务提交成功 content: application/json: schema: $ref: '#/components/schemas/SubmitResponse' components: schemas: SubmitRequest: type: object required: - model - input properties: model: type: string description: |- API 模型标识符。 此接口必须为 `extend-music`。 enum: - extend-music example: extend-music callback_url: type: string format: uri description: |- 用于接收结果通知的 Webhook 回调 URL。 接收任务完成更新的接口。 example: https://your-domain.com/callback input: type: object required: - audio_id - mv description: 音乐扩展的输入参数 properties: default_param_flag: type: boolean default: true description: >- 控制使用自定义参数还是继承源音频的参数。 - 为 `true` 时：启用自定义参数模式。`mv`、`style`、`title` 和 `continue_at` 变为必填。人声扩展还需额外提供 `prompt`。 - 为 `false` 时：`audio_id` 和 `mv` 为必填。 example: true audio_id: type: string description: |- 要扩展的源音轨标识符。 这是你要续写或修改的已有曲目的唯一 ID。 example: audio_abc123 prompt: type: string description: >- 描述你希望如何扩展音乐。 当 `default_param_flag` 为 `true` 时，人声扩展必填。当 `instrumental` 为 `true` 时不会发送。 各模型字符限制： - **V4**：最多 3000 个字符 - **V4_5 & V4_5PLUS**：最多 5000 个字符 - **V4_5ALL**：最多 5000 个字符 - **V5**：最多 5000 个字符 - **V5_5**：最多 5000 个字符 - **V6, V6_MINI, and V6_WILD**：最多 5000 个字符 example: Continue with an energetic chorus section style: type: string description: |- 扩展部分的音乐风格说明。 当 `default_param_flag` 为 `true` 时必填。 各模型字符限制： - **V4**：最多 200 个字符 - **V4_5 & V4_5PLUS**：最多 1000 个字符 - **V4_5ALL**：最多 1000 个字符 - **V5**：最多 1000 个字符 - **V5_5**：最多 1000 个字符 - **V6, V6_MINI, and V6_WILD**：最多 1000 个字符 example: Pop, Upbeat title: type: string description: |- 扩展后曲目的标题。 当 `default_param_flag` 为 `true` 时必填。 各模型字符限制： - **V4**：最多 80 个字符 - **V4_5 & V4_5PLUS**：最多 100 个字符 - **V4_5ALL**：最多 80 个字符 - **V5**：最多 100 个字符 - **V5_5**：最多 100 个字符 - **V6, V6_MINI, and V6_WILD**：最多 100 个字符 example: Summer Vibes Extended continue_at: type: number exclusiveMinimum: 0 description: |- 开始扩展的时间点（秒）。 指定在原曲目中从哪个位置开始扩展。 当 `default_param_flag` 为 `true` 时必填。 example: 120 mv: type: string description: |- 用于音乐扩展的 AI 模型版本。 - **V5**：音乐表现力更出色，生成更快 - **V5_5**：根据你的独特品味调校的个性化模型。 - **V4_5PLUS**：音色更丰富，带来新的创作方式，最长 8 分钟 - **V4_5**：提示词理解更智能，生成更快，最长 8 分钟 - **V4_5ALL**：V4_5ALL 提示词更智能，生成更快，最长 8 分钟 - **V4**：人声质量提升，最长 4 分钟 - **V6**：音乐表现力更强，人声更自然。 - **V6_MINI**：轻量且快速。 - **V6_WILD**：更大胆、更有辨识度的音乐表达。 enum: - V4 - V4_5 - V4_5ALL - V4_5PLUS - V5 - V5_5 - V6 - V6_MINI - V6_WILD example: V5_5 negative_tags: type: string description: |- 扩展中要排除的音乐风格或特征。 指定输出中要避免的流派、情绪或乐器。 example: Heavy Metal, Sad vocal_gender: type: string description: |- 扩展部分的偏好人声性别。 - `m`：男声 - `f`：女声 **注意**：此参数只会提高指定性别出现的概率，无法保证。 enum: - m - f example: m style_weight: type: number multipleOf: 0.01 description: |- 控制指定风格对扩展的影响强度。 范围：0-1，最多 2 位小数。 值越高，越贴近指定风格。 minimum: 0 maximum: 1 example: 0.7 weirdness_constraint: type: number multipleOf: 0.01 description: |- 控制实验性创意和非常规元素的程度。 取值范围：0-1，最多 2 位小数。 - 值较低：音乐更常规 - 值较高：输出更具实验性和独特性 minimum: 0 maximum: 1 example: 0.5 audio_weight: type: number multipleOf: 0.01 description: |- 在音频特性与其他生成因素之间取得平衡。 取值范围：0-1，最多 2 位小数。 调整最终输出中对音质和声音特征的侧重。 minimum: 0 maximum: 1 example: 0.6 persona_id: type: string description: >- 应用于扩展音乐的 Persona ID。 仅在启用自定义模式（`default_param_flag: true`）时可用。 用于为音乐扩展应用特定的 Persona 风格。 如何生成 persona_id，请参阅 [generate-persona](/zh/api-manual/music-series/generate-persona)。 example: persona_123 persona_model: type: string enum: - style_persona - voice_persona description: >- Persona 类型；需要提供 persona_id、default_param_flag=true，且模型为 V5、V5_5、V6、V6_MINI 或 V6_WILD。 instrumental: type: boolean description: 扩展是否为纯音乐。为 true 时不会发送 prompt。 allOf: - if: properties: default_param_flag: const: true then: required: - mv - style - title - continue_at - if: properties: default_param_flag: const: true instrumental: not: const: true then: required: - prompt - if: required: - persona_model then: required: - persona_id properties: default_param_flag: const: true - if: required: - persona_id then: properties: mv: enum: - V5 - V5_5 - V6 - V6_MINI - V6_WILD default_param_flag: const: true - if: properties: default_param_flag: const: true mv: const: V4 then: properties: prompt: maxLength: 3000 style: maxLength: 200 title: maxLength: 80 - if: properties: default_param_flag: const: true mv: const: V4_5ALL then: properties: prompt: maxLength: 5000 style: maxLength: 1000 title: maxLength: 80 - if: properties: default_param_flag: const: true mv: enum: - V4_5 - V4_5PLUS - V5 - V5_5 - V6 - V6_MINI - V6_WILD then: properties: prompt: maxLength: 5000 style: maxLength: 1000 title: maxLength: 100 SubmitResponse: type: object required: - code - data properties: code: type: integer example: 200 description: >- 业务状态码。`200` 表示成功，其他值都表示请求失败。请务必检查这个字段：部分参数校验错误会以 HTTP 200 返回，响应体里的 `code` 为 `400`。 - `200`：成功 - `400`：请求参数无效 - `401`：API Key 缺失或无效 - `402`：积分不足 - `403`：没有权限 - `404`：资源不存在 - `408`：请求超时 - `429`：请求频率超限 - `500`：服务器内部错误 - `502`：上游服务错误 - `503`：服务暂不可用 详见[错误码](/zh/api-manual/error-codes)。 enum: - 200 - 400 - 401 - 402 - 403 - 404 - 408 - 429 - 500 - 502 - 503 data: type: object required: - task_id - status - created_time properties: task_id: type: string example: task-unified-1757165031-uyujaw3d description: 任务唯一标识，用于查询任务状态 status: type: string enum: - not_started - running - finished - failed example: not_started description: >- 任务状态。提交后立即返回时始终为 `not_started`。后续状态请通过[查询任务状态](/zh/api-manual/task-management/status)接口或 `callback_url` 获取。 - `not_started`：排队中，等待处理 - `running`：生成中 - `finished`：已完成，结果在 `files` 或 `output` 中 - `failed`：失败，详情见 `error_message` created_time: type: string format: date-time example: '2025-11-12T10:30:00' description: 任务创建时间，ISO 8601 格式 securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: API Key description: >- 所有 API 接口都需要 Bearer Token 认证。 创建 API Key：登录 PoYo，进入 **仪表盘 → API 密钥**（[poyo.ai/zh/dashboard/api-key](https://poyo.ai/zh/dashboard/api-key)），点击创建 Key。 在请求头中添加： ``` Authorization: Bearer YOUR_API_KEY ``` ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.