跳转到主要内容
POST
  1. 提交后会返回 task_id。如果提供了 callback_url,当任务状态变为 finished 或 failed 时,系统会向 callback_url 发送 POST 请求。
  2. 无论是否提供 callback_url,都可以通过统一的查询音乐详情接口获取结果。
上传翻唱仅在自定义模式下、使用 V5、V5_5、V6、V6_MINI 或 V6_WILD 时,支持 persona_model(style_persona 或 voice_persona)配合 persona_id。仅当 custom_mode: true 且 mv 设为 V5_5、V6、V6_MINI 或 V6_WILD 时,还支持 10–360 的整数 duration。

使用指南

  • 此接口在保留原旋律的同时,将上传的音轨转换为新风格
  • 提供 upload_url,或同时提供 task_id 和 audio_id。不要同时传入两种来源
  • 在应用新的音乐特征时,保留原有的旋律和结构

参数详情

  • 音频上传要求:
    • 上传的音频时长不得超过 8 分钟
    • 注意:使用 V4_5ALL 模型时,上传的音频时长不得超过 1 分钟
    • 通过 upload_url 提供指向音频文件的有效 URL
  • 自定义模式(custom_mode: true)下:
    • style 和 title 为必填
    • 如果 instrumental 为 false,prompt 为必填
    • 字符限制因模型而异:
      • 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 个字符
  • 非自定义模式(custom_mode: false)下:
    • prompt 为必填,用于描述期望的转换效果(最多 500 个字符)
    • style 和 title 应留空

开发者说明

  • 确保音频 URL 可公开访问,且文件时长不超过 8 分钟(V4_5ALL 为 1 分钟)
  • 为获得最佳效果,请使用旋律线清晰的高质量源音频
  • audio_weight 参数有助于在保留原曲与应用新风格之间取得平衡

可选参数

  • 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。仅在 custom_mode: true 且使用 V5、V5_5、V6、V6_MINI 或 V6_WILD 时可用。如何生成 persona_id,请参阅 generate-persona。
  • persona_model (string):style_persona 或 voice_persona。需要 persona_id、custom_mode: true,且使用 V5、V5_5、V6、V6_MINI 或 V6_WILD。

授权

Authorization
string
header
必填

所有 API 接口都需要 Bearer Token 认证。

创建 API Key:登录 PoYo,进入 仪表盘 → API 密钥(poyo.ai/zh/dashboard/api-key),点击创建 Key。

在请求头中添加:

请求体

application/json
model
enum<string>
必填

API 模型标识符。

此接口必须为 upload-and-cover-audio。

可用选项:
upload-and-cover-audio
示例:

"upload-and-cover-audio"

input
object
必填

音频翻唱生成的输入参数

callback_url
string<uri>

用于接收结果通知的 Webhook 回调 URL。

接收任务完成更新的接口。

示例:

"https://your-domain.com/callback"

响应

200 - application/json

任务提交成功

code
enum<integer>
必填

业务状态码。200 表示成功,其他值都表示请求失败。请务必检查这个字段:部分参数校验错误会以 HTTP 200 返回,响应体里的 code 为 400。

  • 200:成功
  • 400:请求参数无效
  • 401:API Key 缺失或无效
  • 402:积分不足
  • 403:没有权限
  • 404:资源不存在
  • 408:请求超时
  • 429:请求频率超限
  • 500:服务器内部错误
  • 502:上游服务错误
  • 503:服务暂不可用

详见错误码。

可用选项:
200,
400,
401,
402,
403,
404,
408,
429,
500,
502,
503
示例:

200

data
object
必填