> ## Documentation Index
> Fetch the complete documentation index at: https://docs.api.box/llms.txt
> Use this file to discover all available pages before exploring further.
# Suno Voice 自建音色生成
> 根据用户录制的验证短句音频生成可复用的 Suno 自建音色。
### 使用指南
* 请在验证短句生成完成，并且用户已完成验证音频录制后调用此接口。
* 验证短句是服务端返回的 `validateInfo` 文本。为获得更佳的音色生成效果，建议用户以演唱方式录制服务端返回的验证短句。
* 提交原验证任务的 `taskId`，并在 `verifyUrl` 中传入验证音频 URL。
* 可选的 `voiceName`、`description`、`style` 和 `singerSkillLevel` 可帮助管理并调整生成的音色。
* 接口会返回新的 `taskId`，后续通过它查询最终 `voiceId`。
* 如果传入 `callBackUrl`，系统会在音色创建完成或任务失败时发送 POST 回调。回调地址必须可公网访问，并在 15 秒内返回 HTTP 200。
### 流程
1. 生成并获取验证短句。
2. 录制用户完成该短句的验证音频；为获得更佳的音色生成效果，建议采用演唱方式录制。
3. 上传或托管验证音频，并将 URL 作为 `verifyUrl` 传入。
4. 提交音色生成任务，并保存返回的 `taskId`。
5. 任务成功后，通过查询接口或回调获取 `voiceId`。
### 回调
查看音色创建完成或失败时发送的回调格式
### 开发者注意事项
* `taskId` 必须来自同一音色流程中的验证短句任务。
* `verifyUrl` 应指向用户录制服务端返回的同一条验证短句的音频；为获得更佳效果，建议采用演唱方式录制。
* 获取 `voiceId` 后，建议先调用音色可用性检查接口，再用于依赖自建音色的生成流程。
## OpenAPI
````yaml /cn/suno-api/suno-voice-api-cn.json POST /api/v1/voice/generate
openapi: 3.0.1
info:
title: Suno Voice API
description: Suno Voice 自建音色 API 文档
version: 1.0.0
contact:
name: Technical Support
email: support@api.box
servers: []
security:
- BearerAuth: []
tags:
- name: docs
- name: docs/zh-CN
- name: docs/zh-CN/Market
- name: docs/zh-CN/Market/Suno API
- name: docs/zh-CN/Market/Suno API/voice
- name: suno接口/voice
paths:
/api/v1/voice/generate:
post:
tags:
- docs/zh-CN/Market/Suno API/voice
- suno接口/voice
summary: Suno Voice自建音色生成接口
description: >
根据用户录制的服务端验证短句音频，生成 Suno Voice 自建音色。
提交原验证任务 ID、用户录制验证短句后的音频 URL，以及可选的音色元信息，例如 `voiceName`、`description` 和
`style`。为获得更佳的音色生成效果，建议用户以演唱方式录制服务端返回的同一条 `validateInfo`
短句。系统会验证录音并创建可复用的自建音色。
## 查询任务状态
提交任务后，你可以通过自建音色记录查询接口检查音色生成进度，并获取最终的 `voiceId`：
了解如何查询自建音色生成状态，并获取生成的 voiceId
:::tip[]
生产环境中，建议使用 `callBackUrl` 参数在自建音色生成完成后接收自动通知，而不是轮询状态接口。
:::
## 使用生成的音色
当任务成功后，查询接口或回调结果中会包含 `voiceId`。你可以在支持自建音色的 Suno 生成接口中使用该 ID。
相关资源
验证生成的音色是否可以使用
查看账户积分和使用情况
operationId: suno-voice-generate
parameters: []
requestBody:
content:
application/json:
schema:
type: object
properties:
taskId:
description: 任务task_id
type: string
verifyUrl:
description: 用户录制服务端返回的验证短句后的音频URL；为获得更佳效果，建议采用演唱方式录制[必填]
type: string
voiceName:
description: 音色名称
type: string
description:
description: 音色描述
type: string
style:
description: 音色风格
type: string
singerSkillLevel:
type: string
description: 歌手技能等级。支持：beginner、intermediate、advanced、professional
default: beginner
enum:
- beginner
- intermediate
- advanced
- professional
x-apidog-enum:
- value: beginner
name: ''
description: ''
- value: intermediate
name: ''
description: ''
- value: advanced
name: ''
description: ''
- value: professional
name: ''
description: ''
callBackUrl:
description: >-
用于接收自建音色生成结果的回调地址。任务成功时，回调中会包含生成的 `voiceId`；任务失败时会包含
`errorCode` 和 `errorMessage`。该地址必须可公网访问，并在 15 秒内返回 HTTP
200。回调数据格式请参考
[自建音色生成回调](https://docs.api.box/cn/suno-api/suno-voice-generate-callbacks)。
type: string
required:
- taskId
- verifyUrl
example:
taskId: voice_create_001
verifyUrl: https://example.com/audio/verify_read.mp3
voiceName: My Voice
description: created from uploaded voice
style: Pop, Female Vocal
singerSkillLevel: beginner
callBackUrl: https://example.com/callback/suno/voice_create
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
type: object
properties:
code:
type: integer
msg:
type: string
data:
type: object
properties:
taskId:
description: 任务id
type: string
required:
- taskId
required:
- code
- msg
- data
example:
code: 200
msg: success
data:
taskId: xxx_task_id_xxx
headers: {}
deprecated: false
security:
- BearerAuth: []
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: API Key
description: |-
# API 认证说明
所有接口都需要通过 Bearer Token 方式进行认证。
## 获取 API Key
1. 访问 [API Key 管理页面](https://api.box/api-key) 获取您的 API Key
## 使用方式
在请求头中添加：
```
Authorization: Bearer YOUR_API_KEY
```
> **注意：**
> - 请妥善保管您的 API Key，不要泄露给他人
> - 如果怀疑 API Key 泄露，请立即在管理页面重置
````