Suno Voice自建音色生成接口

本页由 ModelFold 文档站根据上游官方 OpenAPI 文档同步生成。接口路径、参数、示例与官方保持一致；品牌与 API 域名已替换为 ModelFold。

接口

POST /jobs/createTask

完整 URL: https://ai.modelfold.online/v1/jobs/createTask

鉴权：所有请求都需要 Authorization: Bearer <API_KEY> 请求头。

文档已更新

若你此前已完成对接，仍可前往旧版文档查看：旧版地址 (https://ai.modelfold.online/docs/)

在用户录制验证短句后，生成 Suno Voice 自建音色。

提交原验证任务 ID、用户朗读验证短句后的音频 URL，以及可选的音色元信息，例如 voice_name、description 和 style。系统会验证录音并创建可复用的自建音色。

为了获得更佳效果，请上传或录制一段歌声样本。纯净的清唱人声通常能生成最准确的人声分析结果。

TIP

本接口免费。

查询任务状态

TIP

生产环境中，建议使用 callBackUrl 参数在自建音色生成完成后接收自动通知。

使用生成的音色

获取 Voice ID：Voice ID 就是验证短句任务的 taskId，create-voice 也会在 resultJson.resultUrls[0] 中返回它。create-voice 会立即返回 success，这只表示请求已受理。验证短句任务的状态变为 "success"（通常一分钟内）即表示音色已可用；变为 "fail" 表示录音未通过校验。可在验证短句任务的 callBackUrl 接收结果（data.status 为 "success" 或 "fail"），或用该 taskId 轮询查询任务详情。使用时，在生成音乐接口中把 Voice ID 填入 persona_id，并设置 persona_model: "voice_persona"。

请求参数

请求体 (application/json)

参数	类型	必填	说明
`model`	`string`	是	模型名称示例：`ai-music-api/create-voice`。
`callBackUrl`	`string`	否	接收生成任务完成更新的 URL。可选但建议在生产环境中使用。 - 当生成完成时，系统将向此 URL POST 任务状态和结果 - 回调包含生成的 URL 和任务信息 - 您的回调端点应接受包含结果的 JSON 负载的 POST 请求 - 或者，使用获取任务详情端点轮询任务状态 - 为确保回调安全性，请参阅 Webhook 校验指南了解签名验证实现方法
`input`	`object`	是	生成任务的输入参数
`input.task_id`	`string`	是	任务task_id
`input.verify_url`	`string`	是	用户录制服务端返回的 `validateInfo` 验证短句后的音频 URL。为了获得更好的效果，请上传或录制一段清唱人声样本。纯净的清唱人声通常能生成最准确的人声分析结果。
`input.voice_name`	`string`	否	音色名称
`input.description`	`string`	否	音色描述
`input.style`	`string`	否	音色风格
`input.singer_skill_level`	`string`	否	歌手技能等级支持：beginner、intermediate、advanced、professional 默认值：`"beginner"`。可选值：`beginner` / `intermediate` / `advanced` / `professional`。示例：`beginner`。

请求示例

bash

curl -X POST "https://ai.modelfold.online/v1/jobs/createTask" \
  -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "ai-music-api/create-voice",
  "callBackUrl": "https://example.com/callback/suno/voice_create",
  "input": {
    "task_id": "voice_create_001",
    "verify_url": "https://example.com/audio/verify_read.mp3",
    "voice_name": "My Voice",
    "description": "created from uploaded voice",
    "style": "Pop, Female Vocal",
    "singer_skill_level": "beginner"
  }
}'

json

{
  "model": "ai-music-api/create-voice",
  "callBackUrl": "https://example.com/callback/suno/voice_create",
  "input": {
    "task_id": "voice_create_001",
    "verify_url": "https://example.com/audio/verify_read.mp3",
    "voice_name": "My Voice",
    "description": "created from uploaded voice",
    "style": "Pop, Female Vocal",
    "singer_skill_level": "beginner"
  }
}

响应

200 —

参数	类型	必填	说明
`code`	`integer`	是	请求状态码。请求失败时 HTTP 状态仍为 200，请始终以本字段判断：200 表示成功，其他值均表示失败，原因见 msg。常见值：401 API key 无效或缺失；402 积分不足；429 超出频率限制；422 或 500 请求未能处理（请先查看 msg、检查参数，再决定是否重试）。
`msg`	`string`	是	—
`data`	`object`	是	—
`data.taskId`	`string`	是	任务id

json

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "xxx_task_id_xxx"
  }
}

Suno Voice自建音色生成接口 ​

接口 ​

查询任务状态 ​

使用生成的音色 ​

请求参数 ​

请求体 (application/json) ​

请求示例 ​

响应 ​

200 — ​