参考
API v1 — 端点
GET/api/v1/voices声音目录：id、语言、性别、风格、许可、样本
GET/api/v1/voices/{voice}/avatar声音头像（上传图片或生成渐变）
GET/api/v1/languages支持的语言：代码、名称、等级、声音数量
POST/api/v1/tts语音合成 → WAV 或 MP3（format 参数）
POST/api/v1/tts_stream流式合成（分块 PCM），低延迟 — 干净流，无后期效果，也没有 mp3
POST/api/v1/voices/create创建语音：name、audio_b64（≤10 MB base64）、ref_text（=audio 逐字）、consent="voice-data-consent,privacy"、language? → voice id
GET/api/v1/voices/mine你的语音（已创建克隆 + 已购买）：voice（slug）、name、language、kind、sample_url — 需要 API 密钥
POST/api/v1/transcribe转写短片段：audio_b64、language?（全名）→ text。时长计入套餐的每月转写分钟数上限
GET/api/v1/status引擎就绪情况（实时代理）：ready、model_ready、engine_up、latency_ms
POST/api/v1/warmup在通话会话前预热引擎（不扣字符）
GET /api/v1/voices — 过滤器：q（按名称/风格搜索）、language（ru、en、de…）、gender（male/female）、limit（默认 200，最大 500）、offset。将响应中的 voice 字段传给 POST /tts。
# GET /api/v1/voices?language=ru&gender=male&limit=200
{
"object": "list",
"total": 152,
"count": 152,
"voices": [
{
"voice": "de_at_f1",
"name": "Greta",
"language": "de-AT",
"gender": "female",
"style": "Young",
"description": "Female voice — Austrian German, young, joyful, for presentations.", // in the response language (?locale=)
"labels": { // filter on the *_key fields: they are stable and never translated
"gender": "female", "language": "de-AT", "language_name": "Austrian German",
"accent": "Austrian German", "age": "young", // age is "" unless the catalogue marks it
"style": "Young", "style_key": "young",
"use_case": "presentations", "use_case_key": "presentations",
"emotion": "joyful", "emotion_key": "joyful"
},
"license": "commercial",
"badge": null, // null | "beta" | "soon" (soon = synthesis disabled)
"sample_url": "https://hancvoice.com/api/v1/voices/de_at_f1/sample", // permanent link, redirects to the current file
"avatar_url": "https://hancvoice.com/api/v1/voices/de_at_f1/avatar"
}
]
}
头像和语言。Avatar：302 到图片或 SVG 渐变 — 直接放入 <img>。Languages：tier = main（ready） | beta | soon。
# GET /api/v1/languages — supported languages (code, name, tier, voice count)
{
"object":
"list",
"total": 24,
"languages": [
{
"code":
"de",
"name":
"German",
"native_name":
"Deutsch",
"tier":
"main",
"voice_count": 32
}
]
}
# GET /api/v1/voices/{voice}/avatar → 302 to image, or a generated SVG. Use directly in <img src>.
<img src=
"https://hancvoice.com/api/v1/voices/de_at_f1/avatar" width=
"64" />
访问
身份验证
所有端点都需要 API 密钥：X-API-Key: <key> 标头或 Authorization: Bearer <key>（除 GET /api/v1/voices、GET /api/v1/status、GET /api/v1/languages 和 GET /api/v1/voices/{voice}/avatar — 公开）。密钥在你的账户 → “API” 部分创建；API 从 Starter 套餐及以上可用（否则 403）。合成会按密钥套餐扣除字符——余额为零时返回 402。限流按套餐：Starter — 30 requests/min，Pro — 120，Business — 300，Scale — 600（fallback 60）；超出则返回 429，并带 Retry-After 标头。
POST /api/v1/tts
参数
voiceGET /api/v1/voices 中的 Voice ID。⚠️ 如果该字段缺失，合成会回退到默认语音（de_at_n1），并且仍会扣除字符——请始终显式传入 ID。
text转语音文本；最大长度取决于密钥套餐（必填）
language通常无需填写：语言根据文本自动识别，语音会用该语言朗读文本。语音只在其 verified_languages（GET /api/v1/voices）中没有口音；用其他语言时会保留口音，响应会注明：X-Synthesis-Language、X-Voice-Language、X-Language-Verified: false。仅当语音没有自身语言、且文本太短无法识别语言时，才使用该参数：de、en、ru、fr、es、it、pt、zh、ja、ko（也包括 de-DE、en-US …）以及全名（German、English …）。另有 Auto：引擎从文本中检测语言——这是用自己的语音合成 beta 语言的唯一方式。
instruct英文情绪/风格，例如 "calm, friendly"（可选）
emotionstudio-voice 情绪（适用于带录制情绪参考的声音）：愉快、兴奋、温柔、平静、悲伤、严肃、紧张、愤怒、害怕、惊讶（可选；不带该参数时为中性）
saturation音色的饱和度/谐波“染色”（后处理）：{"preset":"tube"|"tape"|"air","intensity":0–1}（可选）
speed语速 0.5–2.0（可选）范围外的值会被限制到最近边界；响应随后会带有 X-Effects-Failed: speed_clamped_to_…。
gain_db音量 −24…+24 dB（可选）
eq音色均衡器：{"bands":[{"hz":80,"db":4}, …]}（可选）
effect声音预设：radio、audiobook、podcast、phone、cinematic、megaphone、vintage、deep、bright、warm、narrator_warm、intimate、spacious、whisper、concert；character：robot、cartoon、chipmunk、monster、villain、echo_hall；studio：studio_announcer、studio_natural、studio_rich。高级效果（characters、studio、cinematic、concert、megaphone、vintage）——仅限付费方案，否则会被忽略（可选）
seed用于确定性重复生成相同配音的数字（可选）
cleantrue — 神经降噪（与 effect 分开，可选）
background背景/环境音：rain、thunder、sea、forest、birds、wind、stream、night、street、cafe、crowd、fire（可选）
bg_level背景音量 0.05–0.8（可选，默认 0.25）
lead_silence_ms音频开头的静音，ms（可选，适用于 agents；默认 0）
format“wav”（默认）或“mp3”（可选）
response_format电话输出（B2B/IVR）：g711_alaw_8k、g711_ulaw_8k、g722_16k、opus、pcm_s16le_24k。响应为编解码流 + X-Audio-Format 标头（可选）
container仅与 response_format 一起使用：wav（容器，默认）或 raw（用于 SIP/RTP 的原始帧）（可选）
响应是二进制音频文件：audio/wav 或 audio/mpeg（如果 format=mp3）；对于电话 response_format，则为相应的编解码容器（见 X-Audio-Format）。
POST /api/v1/tts_stream
流式合成
接受 voice、text、language、instruct、speed、gain_db、eq、effect、background、bg_level、saturation、seed 和 segments（最多 40 项：text、instruct 最多 200 字符，silence 0–3000 ms）。响应：原始 PCM — 24 kHz、16 位、单声道、小端序（application/octet-stream，分块）；没有 WAV 头，请自行设置采样率。
# POST /api/v1/tts_stream → PCM stream (application/octet-stream, chunked)
{
"voice": "de_at_f1",
"text": "Hallo! Das ist Streaming-Synthese.",
"language": "de"
}
POST /api/v1/voices/create
创建语音
name语音名称（必填）
audio_b64base64 格式的样本录音，≤10 MB（必填）
ref_text录音转写 — 逐字，最多 2000 个字符（更长 → 400 ref_text_too_long）。如果文本与音频不匹配，声音会失真。
consent同意字符串 — 需准确传入 "voice-data-consent,privacy"（语音数据，GDPR）；否则 — 400（必填）
language样本语言，完整名称（俄语、英语…）或 ISO 代码；默认德语（可选）
将响应中的 voice 字段传给 POST /tts。下面的 voice 值只是示例；真实标识来自响应。创建您自己的声音可通过付费方案获得；您自己的声音数量不限 — 创建一个会从您的余额中扣除 25.000 个字符（存储和使用免费）。
# Response — 200 OK (voice value is an example)
{
"ok": true,
"voice": "usr_a1b2c3",
"name": "My voice",
"language": "German"
}
GET /api/v1/voices/mine
您的专属声音
GET /api/v1/voices 只返回公开目录。要获取您的专属声音——包括通过 API 创建的以及在您的账户/工作室中生成的——请使用您的 API 密钥进行认证并调用此端点。它会返回您的克隆（kind="own"）以及在 Marketplace 购买的声音（kind="marketplace"）。将 voice 字段（slug）传给 POST /api/v1/tts。
# GET /api/v1/voices/mine — your own voices (API key required)
curl https://hancvoice.com/api/v1/voices/mine \
-H "X-API-Key: $HANCVOICE_KEY"
# Response — 200 OK
{
"object": "list",
"count": 1,
"voices": [
{
"voice": "usr_a1b2c3",
"name": "My voice",
"language": "German",
"gender": null,
"kind": "own",
"sample_url": "https://hancvoice.com/voice-samples/usr_a1b2c3.wav",
"avatar_url": "https://hancvoice.com/generated-audio/voice-avatars/usr_a1b2c3.webp"
}
]
}
gender 对于专属声音为 null（不存储）；如果没有样本，sample_url 可能为 null。使用您的专属声音合成时，语言取自该声音，并会覆盖 POST /tts 中的 language 参数。
完整复制粘贴流程 — 创建、列表、合成（将示例密钥替换为您在 账户 → API 中的密钥）：
# Full own-voice flow — create → list (mine) → synthesize.
# Example key below — replace it with your own key from Account → API.
KEY="sk-live-9f3c1a7b4e2d8c6f0a5b3e1d7c9f2a4b6d8e0c1a3f5b7d9e"
# 1) Create your voice (skip if you already have one in your account)
curl -X POST https://hancvoice.com/api/v1/voices/create \
-H "X-API-Key: $KEY" -H "Content-Type: application/json" \
-d '{"name":"My voice","ref_text":"exact transcript of the recording","audio_b64":"<24kHz sample, base64>","consent":"voice-data-consent,privacy"}'
# → {"ok":true,"voice":"usr_a1b2c3","name":"My voice","language":"German"}
# 2) List your own voices → take the "voice" (slug)
curl https://hancvoice.com/api/v1/voices/mine -H "X-API-Key: $KEY"
# 3) Synthesize with your voice
curl -X POST https://hancvoice.com/api/v1/tts \
-H "X-API-Key: $KEY" -H "Content-Type: application/json" \
-d '{"voice":"usr_a1b2c3","text":"Hallo, das ist meine eigene Stimme.","language":"de"}' --output out.wav
POST /api/v1/transcribe
转录
audio_b64base64 音频；用于短片段（必填）
language仅限完整语言名称：俄语、英语、德语、法语、意大利语、西班牙语、葡萄牙语、中文、日语、韩语——以及 14 种 beta 语言（保加利亚语、捷克语、希腊语、乌克兰语、波兰语等）作为识别提示，和字面量 "auto"（这里不接受 ISO 代码，不同于 /tts；未提供该参数 — 自动检测）（可选）
按套餐计费字符（约 1 分钟音频 = 1000 个字符）；适用套餐的每月转写分钟数上限。
# Response — language = vom Engine erkannter ISO-Code (z. B. de, en, ru)
{
"text": "Transkribierter Text des Fragments.",
"language": "de"
}
GET /api/v1/status · POST /api/v1/warmup
状态与预热
GET /api/v1/status（无需密钥）— 实时引擎就绪状态。POST /api/v1/warmup（需密钥；不扣字符）在一系列调用前预热引擎。
# GET /api/v1/status
{
"ready": true,
"model_ready": true,
"engine_up": true,
"latency_ms": 42
}
# POST /api/v1/warmup
{
"ok": true,
"warmed": true,
"warm_ms": 318
}
响应
响应头和 code 字段
Content-Typeaudio/wav 或 audio/mpeg（取决于 format 参数）；对于 /tts_stream — application/octet-stream
X-Effects-Failed未应用的效果（在引擎端未应用或被套餐裁剪），以逗号分隔 — 音频会不带这些效果返回
X-CacheHIT / MISS — 表示响应是否来自缓存。注意：使用 API key 时，HIT 的计费与 MISS 相同（缓存节省的是生成时间，不是字符）。
Retry-After在 429 时 — 多少秒后重试请求
错误正文中的 code 字段（机器可读）：plan_required — 需要更高的套餐；voice_limit — 套餐的声音数量上限；plan_quota — 每月转录分钟数限额已用完；email_unverified — 请验证您的邮箱；voice_conflict — 声音名称已被占用（创建声音时）。
响应代码
错误
200成功 — 响应正文包含音频文件
400JSON 损坏或文本为空。未知语言会返回引擎的 4xx（例如 400），代码为 engine_bad_request — 在 /v1/tts 和 /v1/tts_stream 上相同
401缺少或无效的 API key（X-API-Key / Authorization 标头）
402key 余额中的字符数不足 — 请充值套餐
403当前套餐不提供该功能（例如 API — 从 Starter 起可用，自定义声音 — 需付费套餐）或无权访问该声音
409冲突（voice_conflict）：已存在同名声音 — 创建声音时请选择其他名称
413文件过大：自定义声音的音频大于 10 MB（base64）
429超过速率限制（按套餐：Starter 30，Pro 120，Business 300，Scale 600 每分钟；/voices/create 5/分钟，/warmup 20/分钟）。请遵守 Retry-After 标头。代码：rate_limited。 另有一种：concurrency_limit（同为 429）表示同一账号同时进行的请求过多（按套餐：Starter 2, Pro 3, Business 4, Scale 6 个并发合成）——等其中一个完成后重试。此处没有 Retry-After，因为等待时间取决于您自己正在进行的请求。
500内部错误（例如 GET /v1/voices 时数据库不可用）— 请稍后重试。
502合成/转录引擎无响应（Bad Gateway）— 请稍等后重试
503引擎正在休眠/不可用，或服务过载 — 请几秒后重试
错误正文为 JSON { "error": "description", "code": "machine-readable" }。可能的 code 值：auth_required、plan_required、rate_limited, concurrency_limit、no_credits、voice_create_credits、bad_request、empty_text、text_too_long、ref_text_too_long、name_too_long、voice_limit、voice_conflict、voice_access、plan_quota、no_audio、engine_busy、engine_unavailable、engine_error、billing_unavailable、temporarily_unavailable。失败时不扣除字符数 — 但如果客户端中止了流，则已传输的音频按比例计费。
所有错误代码
code 字段中的机器代码完整列表：auth_required（401）·plan_required（403，Starter 版 API）·text_too_long、bad_request、name_required、ref_text_required、ref_text_too_long、name_too_long、audio_b64_required、consent_required、voice_required（400）·voice_access·voice_not_found（404）·no_credits（402）·body_too_large、audio_too_large（413）·concurrency_limit（429，并发）·rate_limited（429，含 Retry-After）·engine_bad_request（引擎 4xx）·engine_error、engine_unavailable、engine_not_configured、temporarily_unavailable、mp3_failed、telephony_failed、transcribe_failed（5xx）·client_abort（499，客户端断开连接）。
说明
容易忽略的实用细节：/v1/tts 和 /v1/tts_stream 的请求体上限为 2 MB（否则返回 413），/v1/transcribe 的 base64 上限为 30 MB · speaker 是 voice 的同义词 · 文本中的暂停标记 ‖（U+2016）会生成正好 400 毫秒 的静音 · instruct 会被静默截断到 500 个字符，lead_silence_ms 上限为 5000 · 如果没有 seed，则使用 4242，因此默认输出可复现（如需变化，请自行修改 seed）· 如果没有 language，则默认德语 · GET /v1/languages 接受 ?locale · 速率限制按 每个端点分别 计算；各自限制：/voices/create 5/分钟，/warmup 20/分钟，/voices/mine 60/分钟，公开 GET 端点每 IP 120/分钟 · POST /v1/voices/clone 是 /voices/create 的别名。
目录
效果和背景
effect 参数 — 每次请求一个预设。免费项所有人可用；高级项 — 仅限付费方案。
播报（免费）radio — 纯净播报 · audiobook — 有声书 · narrator_warm — 温暖旁白 · podcast — 播客 · phone — 电话 · intimate — 贴近 · spacious — 宽阔 · whisper — 耳语 · deep — 更低沉 · bright — 更明亮 · warm — 更温暖
工作室（高级）studio_announcer — 宣告播报 · studio_natural — 自然录音棚 · studio_rich — 丰富“昂贵” · cinematic — 影院 · concert — 礼堂 · megaphone — 扩音器 · vintage — 复古
角色（高级）robot — 机器人 · cartoon — 卡通 · chipmunk — 花栗鼠 · monster — 怪兽 · villain — 反派 · echo_hall — 回音厅
背景（背景）自然：rain（雨）· thunder（雷暴）· sea（海）· forest（森林）· birds（鸟）· wind（风）· stream（溪流）· night（夜晚）。城市：street（街道）· cafe（咖啡馆）· crowd（人群）。温馨：fire（壁炉）。音量 — bg_level 0.05–0.8
eq（音色）8 个频段：80、160、300、600、1500、3500、6500、10500 Hz，每个 −12…+12 dB。示例：{"bands":[{"hz":80,"db":-4},{"hz":3500,"db":3}]} — 去除低频杂音，增加清晰度
配额
限制
请求速率按密钥方案：Starter — 30/分，Pro — 120/分，Business — 300/分，Scale — 600/分。以下端点无论方案都有硬上限：POST /v1/voices/create — 5/分，POST /v1/warmup — 20/分，GET /v1/status — 每 IP 60/分，GET /v1/voices — 每 IP 120/分。
文本长度POST /api/v1/tts 的最大字符数取决于密钥方案
字符余额合成会按密钥方案扣除字符；余额为零时 — 402
转录≈1 分钟音频 = 1000 字符；适用方案的每月分钟数：Pro 100，Business 300，Scale 800 分钟。Free 和 Starter 不包含转录 — API 返回 403（plan_required）。配额用尽 → 403（plan_quota）。
文件大小语音创建：样本 ≤10 MB（base64），否则 413
示例
完整请求
POST /api/v1/tts
{
"voice": "cml_de",
"text": "Heute ist das Wetter wunderbar.",
"language": "de",
"instruct": "calm, friendly",
"speed": 1.0,
"effect": "podcast",
"eq": { "bands": [ { "hz": 3500, "db": 3 } ] },
"background": "rain",
"bg_level": 0.2,
"format": "mp3"
}
→ 200 OK, Content-Type: audio/mpeg (binary file)