> ## Documentation Index > Fetch the complete documentation index at: https://evolink.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Voice Enrollment 创建自定义音色 > - 给 [Qwen Audio 3.1 TTS Flash](/cn/api-manual/audio-series/qwen-audio-tts/qwen-audio-3.1-tts-flash) 创建自定义音色，模型名 `voice-enrollment`。同一个模型两种用法：传 `audio_url` 是**声音复刻**，传 `voice_prompt` + `preview_text` 是**声音设计**；两个都传或都不传返回 `400` - 两种用法创建的音色都只能用于 `qwen-audio-3.1-tts-flash`，并且只有创建它的账号能用。旧版 `qwen-voice-design` 创建的音色不能用于该 TTS；迁移时请用本接口重新创建音色 - 声音设计会额外返回一段试听音频（固定 24 kHz WAV）；声音复刻只返回音色名称 - 异步处理模式，使用返回的任务ID [进行查询](/cn/api-manual/task-management/get-task-detail)。复刻约 15–30 秒完成，设计要等试听文本整段合成完，30 字约 12 秒、200 字约 49 秒 - 按次计费，复刻与设计同价；任务失败全额退还。试听音频链接有效期 24 小时，请尽快保存 - 只能复刻你本人的声音，或已获得明确授权的声音 **使用流程：** 1. 调用本接口，传 `audio_url`（复刻）或 `voice_prompt` + `preview_text`（设计），以及 `preferred_name` 2. 轮询任务结果，获取 `result_data.voice`（音色名称） 3. 调用 [Qwen Audio 3.1 TTS Flash](/cn/api-manual/audio-series/qwen-audio-tts/qwen-audio-3.1-tts-flash)，把音色名称传给 `voice` 参数 **任务结果（`status` 为 `completed` 时）：** | 字段 | 声音复刻 | 声音设计 | |---|---|---| | `result_data.voice` | `qwen-audio-3.1-tts-flash-{preferred_name}-{32 位标识}` | `qwen-audio-3.1-tts-flash-vd-{preferred_name}-{32 位标识}`（多一段 `vd-`） | | `result_data.voice_type` | `voice_clone` | `voice_design` | | `result_data.target_model` | `qwen-audio-3.1-tts-flash` | `qwen-audio-3.1-tts-flash` | | `results` / `result_data.preview_audio_url` | 不返回 | 试听音频链接（有效期 24 小时），另有 `sample_rate: 24000`、`response_format: "wav"` | 设计的试听音频偶尔拿不到时，任务照常完成（音色已建好并计费），结果里改为 `preview_audio_unavailable: true` 和 `preview_audio_warning`。 **音色有效期：** - 复刻和设计创建的自定义音色默认有效期为 `6 小时`，从创建任务完成时起算；使用音色合成不会延长有效期 - 到期后调用 TTS 返回 `404`（`voice_expired`），请重新调用本接口创建音色，再使用新音色合成 **音色名额：** 上游账号下 Qwen-Audio-TTS 系列的自定义音色总数有上限（官方为 1000 个，复刻与设计共用）。名额用尽时创建会失败并全额退还。 **文本长度按字符数计算：** 中文、英文、标点都按 1 个字符计。 ## OpenAPI ````yaml cn/api-manual/audio-series/qwen-audio-tts/voice-enrollment.json POST /v1/audios/generations openapi: 3.1.0 info: title: Voice Enrollment 创建自定义音色接口 description: 给 Qwen Audio 3.1 TTS Flash 创建自定义音色：用一段真人录音复刻，或用一段文字描述设计。同一个模型，按传入的字段区分用法。 license: name: MIT version: 1.0.0 servers: - url: https://api.evolink.ai description: 生产环境 security: - bearerAuth: [] tags: - name: 创建自定义音色 description: 声音复刻与声音设计，音色绑定 Qwen Audio 3.1 TTS Flash paths: /v1/audios/generations: post: tags: - 创建自定义音色 summary: Voice Enrollment 创建自定义音色 description: >- - 给 [Qwen Audio 3.1 TTS Flash](/cn/api-manual/audio-series/qwen-audio-tts/qwen-audio-3.1-tts-flash) 创建自定义音色，模型名 `voice-enrollment`。同一个模型两种用法：传 `audio_url` 是**声音复刻**，传 `voice_prompt` + `preview_text` 是**声音设计**；两个都传或都不传返回 `400` - 两种用法创建的音色都只能用于 `qwen-audio-3.1-tts-flash`，并且只有创建它的账号能用。旧版 `qwen-voice-design` 创建的音色不能用于该 TTS；迁移时请用本接口重新创建音色 - 声音设计会额外返回一段试听音频（固定 24 kHz WAV）；声音复刻只返回音色名称 - 异步处理模式，使用返回的任务ID [进行查询](/cn/api-manual/task-management/get-task-detail)。复刻约 15–30 秒完成，设计要等试听文本整段合成完，30 字约 12 秒、200 字约 49 秒 - 按次计费，复刻与设计同价；任务失败全额退还。试听音频链接有效期 24 小时，请尽快保存 - 只能复刻你本人的声音，或已获得明确授权的声音 **使用流程：** 1. 调用本接口，传 `audio_url`（复刻）或 `voice_prompt` + `preview_text`（设计），以及 `preferred_name` 2. 轮询任务结果，获取 `result_data.voice`（音色名称） 3. 调用 [Qwen Audio 3.1 TTS Flash](/cn/api-manual/audio-series/qwen-audio-tts/qwen-audio-3.1-tts-flash)，把音色名称传给 `voice` 参数 **任务结果（`status` 为 `completed` 时）：** | 字段 | 声音复刻 | 声音设计 | |---|---|---| | `result_data.voice` | `qwen-audio-3.1-tts-flash-{preferred_name}-{32 位标识}` | `qwen-audio-3.1-tts-flash-vd-{preferred_name}-{32 位标识}`（多一段 `vd-`） | | `result_data.voice_type` | `voice_clone` | `voice_design` | | `result_data.target_model` | `qwen-audio-3.1-tts-flash` | `qwen-audio-3.1-tts-flash` | | `results` / `result_data.preview_audio_url` | 不返回 | 试听音频链接（有效期 24 小时），另有 `sample_rate: 24000`、`response_format: "wav"` | 设计的试听音频偶尔拿不到时，任务照常完成（音色已建好并计费），结果里改为 `preview_audio_unavailable: true` 和 `preview_audio_warning`。 **音色有效期：** - 复刻和设计创建的自定义音色默认有效期为 `6 小时`，从创建任务完成时起算；使用音色合成不会延长有效期 - 到期后调用 TTS 返回 `404`（`voice_expired`），请重新调用本接口创建音色，再使用新音色合成 **音色名额：** 上游账号下 Qwen-Audio-TTS 系列的自定义音色总数有上限（官方为 1000 个，复刻与设计共用）。名额用尽时创建会失败并全额退还。 **文本长度按字符数计算：** 中文、英文、标点都按 1 个字符计。 operationId: createVoiceEnrollment requestBody: required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/VoiceCloneRequest' - $ref: '#/components/schemas/VoiceDesignRequest' examples: clone_minimal: summary: 声音复刻：最简调用 value: model: voice-enrollment audio_url: https://your-cdn.com/samples/my-voice.wav preferred_name: myvoice clone_full: summary: 声音复刻：完整参数 value: model: voice-enrollment audio_url: https://your-cdn.com/samples/my-voice.wav preferred_name: myvoice language: zh target_model: qwen-audio-3.1-tts-flash callback_url: https://your-domain.com/webhooks/voice-completed design_minimal: summary: 声音设计：最简调用 value: model: voice-enrollment voice_prompt: 沉稳的中年男性播音员，音色低沉浑厚，富有磁性，语速平稳，吐字清晰 preview_text: 各位听众朋友，大家好，欢迎收听晚间新闻。 preferred_name: announcer design_full: summary: 声音设计：完整参数 value: model: voice-enrollment voice_prompt: >- A calm British female narrator in her thirties, warm and articulate preview_text: Good evening, and welcome to tonight's programme. preferred_name: narrator language: en sample_rate: 24000 response_format: wav target_model: qwen-audio-3.1-tts-flash callback_url: https://your-domain.com/webhooks/voice-completed responses: '200': description: 创建音色的任务已受理 content: application/json: schema: $ref: '#/components/schemas/VoiceEnrollmentResponse' '400': description: 请求参数错误 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: mutually_exclusive: summary: 同时传了 audio_url 和 voice_prompt value: error: code: invalid_parameter message: >- audio_url and voice_prompt are mutually exclusive: pass audio_url to clone a voice, or voice_prompt to design one type: invalid_request_error missing_mode: summary: audio_url 和 voice_prompt 都没传 value: error: code: invalid_parameter message: >- audio_url (voice cloning) or voice_prompt (voice design) is required for voice-enrollment type: invalid_request_error missing_preferred_name: summary: 缺少 preferred_name value: error: code: invalid_parameter message: >- preferred_name is required for voice-enrollment (e.g. 'announcer', 'narrator') type: invalid_request_error invalid_preferred_name: summary: preferred_name 不符合规则 value: error: code: invalid_parameter message: preferred_name must be 1-10 English letters or digits type: invalid_request_error bad_target_model: summary: target_model 不是 qwen-audio-3.1-tts-flash value: error: code: invalid_parameter message: >- target_model 'qwen3-tts-vd' is not supported, valid value: qwen-audio-3.1-tts-flash type: invalid_request_error bad_language: summary: language 不在支持范围 value: error: code: invalid_parameter message: >- language must be one of zh, en, ja, ko, de, fr, it, ru, pt, es type: invalid_request_error audio_url_too_long: summary: 复刻：audio_url 超过 2048 字符 value: error: code: invalid_parameter message: audio_url must not exceed 2048 characters, got 2191 type: invalid_request_error audio_url_not_public: summary: 复刻：audio_url 是内网地址 value: error: code: invalid_media_url message: >- invalid parameter "audio_url": points to localhost; provide a publicly accessible URL type: invalid_request_error audio_url_not_http: summary: 复刻：audio_url 使用 FTP 等非法协议 value: error: code: invalid_media_url message: >- invalid parameter "audio_url": must be an absolute HTTP(S) URL type: invalid_request_error param: audio_url audio_url_base64: summary: 复刻：audio_url 使用 Base64 data URI value: error: code: invalid_parameter message: >- audio_url must be a publicly accessible HTTP(S) URL: must be an absolute HTTP(S) URL type: invalid_request_error clone_with_design_field: summary: 复刻时传了设计的字段 value: error: code: invalid_parameter message: >- preview_text is only supported for voice design (voice_prompt) type: invalid_request_error voice_prompt_too_long: summary: 设计：voice_prompt 超过 500 字符 value: error: code: invalid_parameter message: voice_prompt must not exceed 500 characters, got 501 type: invalid_request_error missing_preview_text: summary: 设计：缺少 preview_text value: error: code: invalid_parameter message: preview_text is required for voice design type: invalid_request_error preview_text_length: summary: 设计：preview_text 长度不在 15 ~ 200 value: error: code: invalid_parameter message: preview_text must be 15-200 characters, got 3 type: invalid_request_error design_sample_rate: summary: 设计：采样率不是 24000 value: error: code: invalid_parameter message: sample_rate must be 24000 for voice-enrollment type: invalid_request_error '401': description: 未认证、Token无效或过期 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: unauthorized message: Invalid or expired token type: authentication_error '402': description: 配额不足、需要充值 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: insufficient_quota message: Insufficient quota. Please top up your account. type: insufficient_quota '403': description: 无权限访问 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: model_access_denied message: 'Token does not have access to model: voice-enrollment' type: invalid_request_error '429': description: 请求频率超限 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: rate_limit_exceeded message: Too many requests, please try again later type: rate_limit_error '500': description: 服务器内部错误 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: internal_error message: Internal server error type: api_error components: schemas: VoiceCloneRequest: title: 声音复刻（audio_url） type: object description: >- 用一段真人录音创建音色。传了 `audio_url` 即为声音复刻，此时请省略设计用的 `voice_prompt`、`preview_text`、`sample_rate`、`response_format`。非空设计文本、非零采样率或非空格式返回 `400`；`sample_rate: 0/null`、`response_format: ""/null` 按未传处理。 required: - model - audio_url - preferred_name properties: model: type: string enum: - voice-enrollment default: voice-enrollment example: voice-enrollment description: 模型名称 audio_url: type: string format: uri maxLength: 2048 example: https://your-cdn.com/samples/my-voice.wav description: |- 待复刻的录音文件地址。传了本字段即为**声音复刻**，不能与 `voice_prompt` 同时传 **地址要求：** - HTTP 或 HTTPS，无需鉴权即可公开访问 - 不能是本地或内网地址，否则返回 `400`（`invalid_media_url`） - 长度不超过 `2048` 字符 - FTP 等非 HTTP(S) 协议返回 `400`（`invalid_media_url`） - 只支持链接，不支持 Base64；传 Base64 data URI 返回 `400`（`invalid_parameter`） **音频要求**（不满足时任务可能失败）： - 格式：WAV、MP3 或 M4A - 时长：不超过 60 秒；有效人声过短也会失败（实测 2 秒的录音失败） - 文件大小：不超过 `10 MB` - 采样率：`16 kHz` 及以上 - 必须包含清晰的人声；无声、音乐等非人声音频会被拒绝 **录音建议：** - 时长 10 ~ 20 秒，其中至少有 5 秒连续、清晰的朗读，停顿不超过 2 秒 - 单声道；双声道录音只取第一个声道 - 无背景音乐、噪音和其他人声；正常说话，不要唱歌 音频无法下载或不符合要求时任务失败，积分全额退还 **只能复刻你本人的声音，或已获得明确授权的声音** pattern: >- [^\u0009-\u000D\u0020\u0085\u00A0\u1680\u2000-\u200A\u2028\u2029\u202F\u205F\u3000] preferred_name: type: string maxLength: 10 pattern: ^[a-zA-Z0-9]+$ example: myvoice description: >- 音色名称前缀 **约束：** - 仅英文字母和数字，1 ~ 10 位（不支持下划线及其他符号） - 大写字母会被转成小写 - 不要求唯一 生成的完整音色名：复刻为 `qwen-audio-3.1-tts-flash-{preferred_name}-{32 位标识}`，设计为 `qwen-audio-3.1-tts-flash-vd-{preferred_name}-{32 位标识}` 如传入 `myvoice`，复刻出的音色名类似：`qwen-audio-3.1-tts-flash-myvoice-5996beec833d41f4982158347ba97fae` language: type: string enum: - zh - en - ja - ko - de - fr - it - ru - pt - es example: zh description: |- 复刻时是录音中所说的语言，帮助模型更准确地提取音色；设计时是音色的语言倾向，建议与 `preview_text` 语种一致 不传时默认 `zh` target_model: type: string enum: - qwen-audio-3.1-tts-flash default: qwen-audio-3.1-tts-flash example: qwen-audio-3.1-tts-flash description: >- 音色将由哪个 TTS 模型驱动。目前只有一个取值，不传即为该值；传别的值返回 `400` | 值 | 说明 | |-----|------| | `qwen-audio-3.1-tts-flash` | Qwen Audio 3.1 TTS Flash 非流式（默认，唯一取值） | callback_url: $ref: '#/components/schemas/CallbackUrl' not: anyOf: - required: - voice_prompt properties: voice_prompt: not: type: - string - 'null' pattern: >- ^[\u0009-\u000D\u0020\u0085\u00A0\u1680\u2000-\u200A\u2028\u2029\u202F\u205F\u3000]*$ - required: - preview_text properties: preview_text: not: type: - string - 'null' pattern: >- ^[\u0009-\u000D\u0020\u0085\u00A0\u1680\u2000-\u200A\u2028\u2029\u202F\u205F\u3000]*$ - required: - sample_rate properties: sample_rate: not: enum: - 0 - null - required: - response_format properties: response_format: not: enum: - '' - null VoiceDesignRequest: title: 声音设计（voice_prompt） type: object description: >- 用一段文字描述创建音色，并把 `preview_text` 合成成一段试听音频。传了 `voice_prompt` 即为声音设计，此时不能传 `audio_url`。 required: - model - voice_prompt - preview_text - preferred_name properties: model: type: string enum: - voice-enrollment default: voice-enrollment example: voice-enrollment description: 模型名称 voice_prompt: type: string maxLength: 500 example: 沉稳的中年男性播音员，音色低沉浑厚，富有磁性，语速平稳，吐字清晰 description: >- 声音特征描述，用于定义音色。传了本字段即为**声音设计**，不能与 `audio_url` 同时传 **约束：** - 不超过 `500` 个字符（中文、英文都按 1 计） - 建议用中文或英文描述 **描述维度建议：** 性别、年龄、音调、语速、情感、特点（有磁性、清脆、沙哑、圆润、甜美、浑厚）、用途（新闻播报、广告配音、有声书、动画角色、语音助手） **推荐写法示例：** - `沉稳的中年男性，语速缓慢，音色低沉有磁性，适合朗读新闻或纪录片解说` - `温柔知性的女性，30岁左右，语调平和，适合有声书朗读` pattern: >- [^\u0009-\u000D\u0020\u0085\u00A0\u1680\u2000-\u200A\u2028\u2029\u202F\u205F\u3000] preview_text: type: string minLength: 15 maxLength: 200 example: 各位听众朋友，大家好，欢迎收听晚间新闻。 description: |- 试听文本，会被**整段**合成成试听音频 **约束：** - `15` ~ `200` 个字符（中文、英文都按 1 计） - 文本越长创建越慢：30 字约 12 秒，200 字约 49 秒 - 建议与 `language` 语种一致 pattern: >- [^\u0009-\u000D\u0020\u0085\u00A0\u1680\u2000-\u200A\u2028\u2029\u202F\u205F\u3000] sample_rate: type: - integer - 'null' enum: - 24000 - 0 - null default: 24000 example: 24000 description: |- 试听音频采样率（Hz），固定使用 `24000` - 不传、传 `0` 或 `null` 时按未传处理，使用默认值 `24000` - 其他采样率返回 `400`（`invalid_parameter`） response_format: type: - string - 'null' enum: - wav - '' - null default: wav example: wav description: |- 试听音频格式，固定使用 `wav` - 不传、传空字符串 `""` 或 `null` 时按未传处理，使用默认值 `wav` - 其他格式返回 `400`（`invalid_parameter`） preferred_name: type: string maxLength: 10 pattern: ^[a-zA-Z0-9]+$ example: myvoice description: >- 音色名称前缀 **约束：** - 仅英文字母和数字，1 ~ 10 位（不支持下划线及其他符号） - 大写字母会被转成小写 - 不要求唯一 生成的完整音色名：复刻为 `qwen-audio-3.1-tts-flash-{preferred_name}-{32 位标识}`，设计为 `qwen-audio-3.1-tts-flash-vd-{preferred_name}-{32 位标识}` 如传入 `myvoice`，复刻出的音色名类似：`qwen-audio-3.1-tts-flash-myvoice-5996beec833d41f4982158347ba97fae` language: type: string enum: - zh - en - ja - ko - de - fr - it - ru - pt - es example: zh description: |- 复刻时是录音中所说的语言，帮助模型更准确地提取音色；设计时是音色的语言倾向，建议与 `preview_text` 语种一致 不传时默认 `zh` target_model: type: string enum: - qwen-audio-3.1-tts-flash default: qwen-audio-3.1-tts-flash example: qwen-audio-3.1-tts-flash description: >- 音色将由哪个 TTS 模型驱动。目前只有一个取值，不传即为该值；传别的值返回 `400` | 值 | 说明 | |-----|------| | `qwen-audio-3.1-tts-flash` | Qwen Audio 3.1 TTS Flash 非流式（默认，唯一取值） | callback_url: $ref: '#/components/schemas/CallbackUrl' not: required: - audio_url properties: audio_url: not: type: - string - 'null' pattern: >- ^[\u0009-\u000D\u0020\u0085\u00A0\u1680\u2000-\u200A\u2028\u2029\u202F\u205F\u3000]*$ VoiceEnrollmentResponse: type: object properties: created: type: integer description: 任务创建时间戳 example: 1775123456 id: type: string description: 任务ID example: task-unified-1775123456-abcd1234 model: type: string description: 实际使用的模型名称 example: voice-enrollment object: type: string enum: - audio.generation.task description: 任务的具体类型 progress: type: integer description: 任务进度百分比 (0-100) minimum: 0 maximum: 100 example: 0 status: type: string description: 任务状态 enum: - pending - processing - completed - failed example: pending task_info: $ref: '#/components/schemas/AudioTaskInfo' description: 音频任务详细信息 type: type: string enum: - audio description: 任务的输出类型 example: audio usage: $ref: '#/components/schemas/AudioUsage' description: 使用量和计费信息 ErrorResponse: type: object properties: error: type: object properties: code: type: string description: 错误代码标识符 message: type: string description: 错误描述信息 type: type: string description: 错误类型 CallbackUrl: type: string description: |- 任务完成后的HTTPS回调地址 **回调时机：** - 任务完成（completed）或失败（failed）时触发 - 在计费确认完成后发送 **安全限制：** - 仅支持HTTPS协议 - 禁止回调到内网IP地址（127.0.0.1、10.x.x.x、172.16-31.x.x、192.168.x.x等） - URL长度不超过`2048`字符 **回调机制：** - 超时时间：`10`秒 - 失败后最多重试`3`次（会分别在失败的`1`秒/`2`秒/`4`秒后进行重试） - 回调响应体格式与任务查询接口返回的格式一致 - 回调地址若返回2xx状态码视为成功，其他状态码会触发重试 format: uri example: https://your-domain.com/webhooks/voice-completed AudioTaskInfo: type: object properties: can_cancel: type: boolean description: 任务是否可以取消；创建音色的任务不可取消 example: false estimated_time: type: integer description: 预估完成时间(秒)。保守估计：复刻通常 15–30 秒，设计随试听文本变长，30 字约 12 秒、200 字约 49 秒 minimum: 0 example: 60 audio_type: type: string description: >- 本次请求的用法：传了 `audio_url` 为 `voice_clone`，传了 `voice_prompt` 为 `voice_design`，与任务结果里的 `voice_type` 一致 example: voice_clone enum: - voice_clone - voice_design AudioUsage: type: object description: 使用量信息 properties: credits_reserved: type: number description: 预估消耗积分数。按次计费，复刻与设计同价；任务失败时积分全额退还 minimum: 0 example: 0.001 securitySchemes: bearerAuth: type: http scheme: bearer description: |- ##所有接口均需要使用Bearer Token进行认证## **获取 API Key：** 访问 [API Key 管理页面](https://evolink.ai/dashboard/keys) 获取您的 API Key **使用时在请求头中添加：** ``` Authorization: Bearer YOUR_API_KEY ``` ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.