Persona

  • 从已有歌曲里提取可复用的歌手人设，异步任务
  • 之后生成新歌时绑定这个人设，沿用其音色与风格
  • 结果在 result.persona_id
POST/v1/music/generations/persona

认证

string必填

所有接口均使用 Bearer Token 进行认证。

获取 API Key：访问控制台 创建。

请求时在请求头中添加：

Authorization: Bearer YOUR_OAIRoute_KEY

引用源音轨

string必填

产出源音轨那次任务的 task_id。缺失或无法解析源音轨时，提交阶段直接返回 400。

integer可选

指定 result.music[] 中第几首作为源音轨，默认 1。一次生成通常为 1 或 2。

请求参数

string可选

音频模型，默认 suno，当前仅 suno。

string必填

Persona 名称。缺失时直接返回 400。

string可选

描述这个人设的特点。

string可选

风格标签。

number可选

人声片段的起点，单位秒，不小于 0。

number可选

人声片段的终点，单位秒。须大于 vocal_start_s，且不超过已知源时长。

本端点没有版本维度，传 version 会被忽略，也不影响计费。

人声片段怎么取

vocal_start_s 与 vocal_end_s 用来指定从哪一段人声里提取特征。建议成对提供：

  • 只给起点不给终点，容易把整段都算进去，包含器乐部分
  • 区间太长，特征会被多种唱法稀释
  • 理想的区间是 10 到 30 秒的纯人声，没有伴奏干扰

响应

integer

响应状态码。

data[] 的元素字段 · 2 项
string

提交后为 submitted。

string

任务唯一标识，用于轮询。

轮询用 GET /v1/music/tasks/{task_id}，间隔 3 到 5 秒，典型耗时 30 到 120 秒。结果里的 result.persona_id 就是最终的人设标识。

失败时 data.error.message 给出原因，预扣额度自动退回。

拿到 persona_id 之后

在生成、翻唱、续写时传 persona_id 即可沿用这个人设：

{
  "model": "suno",
  "custom": true,
  "version": "v6",
  "persona_id": "persona_01KA",
  "prompt": "[Verse]\n新的歌词",
  "tags": "city pop"
}

persona_id 与 custom_model_id 互斥，两者不能同时传。它们代表两种不同的复用方式：Persona 复用音色与演唱风格，自定义模型复用整体曲风。

persona_id 与自定义模型 ID 不同，不能作为 API 的 model 值使用。它只能填在 persona_id 字段里。新流程也不需要先创建 Vox。

错误码

错误响应的格式、状态码与重试建议见错误码与限流，常见报错的排查步骤见常见问题。

使用示例

提交一个任务并拿到 task_id：

提交成功只表示任务已受理。真正的产物要拿返回的 task_id 去任务查询接口轮询，status 变成 completed 之后才有结果。