跳转到主要内容
POST
  1. 提交后会返回 task_id。如果提供了 callback_url,当任务状态变为 finished 或 failed 时,系统会向 callback_url 发送 POST 请求。
  2. 无论是否提供 callback_url,都可以通过统一的查询音乐详情接口获取结果。

使用指南

  • 此接口根据你的文本提示词创作音乐
  • 每次请求会生成多个变体
  • 可以通过自定义模式和纯伴奏设置控制细节程度

参数详情

  • 自定义模式(custom_mode: true)下:
    • title 为必填
    • style、lyrics 或 negative_tags 至少提供一个
    • prompt 为可选。同时提供 lyrics 时,以 lyrics 作为演唱文本
    • 字符限制因模型而异:
      • V4:prompt 3000 个字符,style 200 个字符
      • V4_5 和 V4_5PLUS:prompt 5000 个字符,style 1000 个字符
      • V4_5ALL:prompt 5000 个字符,style 1000 个字符
      • V5:prompt 5000 个字符,style 1000 个字符
      • V5_5:prompt 5000 个字符,style 1000 个字符
      • V6、V6_MINI 和 V6_WILD:lyrics 5000 个字符,style 1000 个字符
  • 非自定义模式(custom_mode: false)下:
    • prompt 长度限制:3000 个字符
    • 提供 prompt,或至少提供 style、lyrics、image_urls、video_urls、audio_urls 中的一项
    • image_urls、video_urls 和 audio_urls 仅在此模式下可用。连同 style 和 lyrics 在内,附件数量不得超过 10

开发者说明

  • 新用户建议:先从 custom_mode: false 开始,用法更简单

可选参数

  • vocal_gender (string):人声性别偏好。m 表示男声,f 表示女声。注意:此参数仅在 custom_mode 为 true 时生效。根据实践,此参数只能提高概率,不能保证遵循男声/女声指令。
  • style_weight (number):对风格的遵循强度。范围 0-1,最多 2 位小数。示例:0.65。
  • weirdness_constraint (number):控制创意偏离程度。范围 0-1,最多 2 位小数。示例:0.65。
  • audio_weight (number):音频特征的平衡权重。范围 0-1,最多 2 位小数。示例:0.65。
  • persona_id (string):应用于生成音乐的 Persona ID。用于将特定的 Persona 风格应用到音乐生成中。仅在启用自定义模式时可用。如何生成 persona_id,请参阅 generate-persona。
  • lyrics (string):歌词内容,最多 5000 个字符。在自定义模式下优先于 prompt。
  • variety (integer):多样性,0 到 4。仅在 custom_mode 为 true 时生效。
  • image_urls、video_urls、audio_urls:非自定义模式下的参考文件。图片最多 5 个 URL,视频最多 1 个 URL。
  • persona_model (string):style_persona 或 voice_persona。需要 persona_id,且使用 V5、V5_5、V6、V6_MINI 或 V6_WILD。
  • duration (integer):自定义时长,10–360 秒。仅在 custom_mode: true 且 mv 为 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 模型标识。

此接口必须为 generate-music。

可用选项:
generate-music
示例:

"generate-music"

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
必填