Cartesia Sonic 2.0 的 TTS 接上 TaoToken 通道后填充功能直接可用这篇从配置层解决 Cartesia Sonic 2.0 的 TTS 接入问题你不需要先去 Cartesia 控制台单独登记而是先在 TaoToken 官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 创建 Key把客户端的 Base URL 填成 https://taotoken.net/api接口路径与参数继续按 Sonic 2.0 文档写。这样 TTS 请求会走 TaoToken 统一通道Sonic 2.0 的填充功能也能在支持自定义 Base URL 的模型工具里直接调用。TaoToken 只负责提供 Key 与 Base URL 通道不替代语音合成真正决定音色、语言、输出格式和填充效果的仍然是 Sonic 2.0 的模型能力与接口参数。接下来按实际接入时会碰到的 Base URL、Header、model_id、/tts/bytes 与填充路径逐项拆开。一、原问题与场景Sonic 2.0 的填充功能卡在接入层Cartesia 升级 Sonic 2.0 后比较受关注的点有两个一是低延迟Turbo 模式标称可以做到 40ms 级别二是新增了音频填充能力可以在已有音频里无缝插入或替换一段内容。对做实时对话、语音 Agent、播客剪辑、游戏对白原型的人来说这两个能力都很实用。但真正落地时很多开发者遇到的不是模型效果问题而是接入配置问题。典型场景是这样你的客户端、脚本或内部工具已经支持自定义 Base URL也支持发送 JSON 请求并接收二进制音频。你希望把原本发往 Cartesia 的 TTS 请求改走 TaoToken 统一通道于是需要把 Base URL 从 Cartesia 官方域名换成https://taotoken.net/apiKey 换成 TaoToken 创建的 Key其他路径和参数仍按 Sonic 2.0 文档填写。此时最容易卡住的地方包括Base URL 到底填到哪一层、Header 用X-API-Key还是Authorization、model_id是不是sonic-2、填充接口是不是普通/tts/bytes、返回二进制时文件为什么打不开。如果你只是调用普通 TTS配置通常很快但一旦要用填充功能就必须把“通道配置”和“模型参数”分开看。TaoToken 负责 Key 与 Base URL 通道Sonic 2.0 负责语音合成、音色、输出格式和填充逻辑。把这两层混在一起就会出现“Key 没问题但请求 404”“音频能返回但填充字段报 422”“本地保存成文本导致文件损坏”这类问题。所以这篇不讨论模型评测也不讨论价格只按接入配置视角把 Sonic 2.0 在 TaoToken 通道下的可复制配置、验证方法和常见错排查写清楚。二、TaoToken 前置Key、Base URL 与 Sonic 2.0 的边界开始改代码前先把三个值固定下来官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentBase URLhttps://taotoken.net/apiKeyYOUR_API_KEY操作顺序很简单打开 TaoToken 官网登录后进入控制台创建 API Key复制出来保存到环境变量里。不要把它硬编码到公开仓库。然后在支持自定义 Base URL 的模型工具、SDK 或自己的脚本里把 Base URL 填成https://taotoken.net/api。注意这里是 API 根地址不要填官网首页也不要随手加/v1、/tts、/tts/bytes。如果你的 SDK 需要的是 base_url 参数通常只填根地址如果你自己手写 HTTP 请求再在代码里拼接具体 endpoint。Sonic 2.0 侧仍然要按 Cartesia 文档准备这些内容model_id按 Sonic 2.0 文档填写常见写法是sonic-2不要凭记忆写sonic、sonic2.0、sonic_2。voice通常需要mode和id例如{mode: id, id: YOUR_VOICE_ID}。output_format决定返回音频是 raw、wav 还是 mp3以及采样率、编码格式。版本 Header如果文档要求Cartesia-Version就保留。填充接口普通 TTS 和音频填充不是同一个请求体路径和字段必须以 Sonic 2.0 文档为准。这里要反复强调边界TaoToken 只提供 Key 与 Base URL 通道不替代语音合成。你在请求里写的model_id、voice、transcript、填充区间、原音频字段仍然由 Sonic 2.0 的 API 解析。把 Base URL 换掉即可不要因为换了通道就改模型参数也不要把 Cartesia 文档里的 endpoint 和 payload 丢掉。三、可复制配置环境变量、curl 与 tts_infill.py先写环境变量。Linux、macOS、WSL 都可以用export TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_API_KEYYOUR_API_KEY export SONIC_MODEL_IDsonic-2 export SONIC_VOICE_IDYOUR_VOICE_ID export SONIC_INFILL_PATH/tts/infill如果你用.env文件也可以写成TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_API_KEYYOUR_API_KEY SONIC_MODEL_IDsonic-2 SONIC_VOICE_IDYOUR_VOICE_ID SONIC_INFILL_PATH/tts/infill下面是 curl 版普通 TTS 请求。重点看三个位置Base URL 来自 TaoTokenKey 用 TaoToken Keyendpoint 和 JSON 字段按 Sonic 2.0 文档。curl -sS -X POST $TAOTOKEN_BASE_URL/tts/bytes \ -H X-API-Key: $TAOTOKEN_API_KEY \ -H Cartesia-Version: 2024-06-10 \ -H Content-Type: application/json \ -d { model_id: sonic-2, transcript: Sonic 2.0 through TaoToken., voice: {mode: id, id: YOUR_VOICE_ID}, output_format: {container: wav, encoding: pcm_s16le, sample_rate: 44100}, language: en } \ --output sonic2-tts.wav如果 TaoToken 接入文档或你的客户端要求 Bearer 形式则把X-API-Key: $TAOTOKEN_API_KEY替换为Authorization: Bearer $TAOTOKEN_API_KEY不要两个 Header 同时乱填。以接入文档和客户端要求为准。Python 版可以写成tts_infill.py把普通 TTS 和填充请求都封装进去import os import pathlib import requests BASE_URL os.getenv(TAOTOKEN_BASE_URL, https://taotoken.net/api) API_KEY os.getenv(TAOTOKEN_API_KEY, YOUR_API_KEY) MODEL_ID os.getenv(SONIC_MODEL_ID, sonic-2) VOICE_ID os.getenv(SONIC_VOICE_ID, YOUR_VOICE_ID) INFILL_PATH os.getenv(SONIC_INFILL_PATH, /tts/infill) def build_headers(): return { X-API-Key: API_KEY, Cartesia-Version: os.getenv(CARTESIA_VERSION, 2024-06-10), Content-Type: application/json, } def tts_to_file(text, pathsonic2-tts.wav): payload { model_id: MODEL_ID, transcript: text, voice: {mode: id, id: VOICE_ID}, output_format: { container: wav, encoding: pcm_s16le, sample_rate: 44100, }, language: en, } resp requests.post( f{BASE_URL}/tts/bytes, headersbuild_headers(), jsonpayload, timeout60, ) resp.raise_for_status() pathlib.Path(path).write_bytes(resp.content) return path def infill_to_file(infill_fields_from_doc, pathsonic2-infilled.wav): payload { model_id: MODEL_ID, voice: {mode: id, id: VOICE_ID}, output_format: { container: wav, encoding: pcm_s16le, sample_rate: 44100, }, **infill_fields_from_doc, } resp requests.post( f{BASE_URL}{INFILL_PATH}, headersbuild_headers(), jsonpayload, timeout120, ) resp.raise_for_status() pathlib.Path(path).write_bytes(resp.content) return path if __name__ __main__: tts_to_file(Hello from Sonic 2.0 via TaoToken.) print(普通 TTS 已保存)填充请求的关键不在于复制上面的infill_fields_from_doc而是按 Sonic 2.0 文档把原音频、替换区间、新文本、输出选项等字段补齐。比如文档要求传 base64 音频就传 base64要求传 URL就传 URL要求传 start/end就按文档单位填写。路径如果不是/tts/infill把SONIC_INFILL_PATH改成文档里的真实路径即可。四、验证请求从 200 响应到填充音频落盘配置写完不要直接接业务用最小请求验证。第一步运行 curl 或tts_infill.py后看 HTTP 状态。成功时通常是200响应体是二进制音频。如果失败先把响应体按文本打印出来常见是 JSON 错误信息里面会提示字段缺失或 Key 无效。第二步检查文件file sonic2-tts.wav ls -lh sonic2-tts.wav ffprobe -v error -show_entries streamcodec_name,sample_rate,channels -of defaultnw1 sonic2-tts.wav如果file显示WAVE audio或RIFF大小明显大于 0ffprobe能读出采样率和声道说明普通 TTS 通道已经通了。播放可以用系统播放器也可以ffplay -autoexit sonic2-tts.wav第三步验证填充。先准备一段基础音频base.wav再调用填充接口输出sonic2-infilled.wav。成功结果不是“返回 200”就结束还要检查输出文件能正常播放。采样率、声道、容器格式与请求一致。插入区间的新语音已经生效。插入点前后没有明显爆音、截断或空白。整体时长与预期接近没有把原音频整段丢掉。可以在 Python 里这样调用infill_fields { # 以下字段名必须按 Sonic 2.0 文档补全不要凭记忆猜 # 原音频、填充区间、新 transcript、输出格式等 } infill_to_file(infill_fields)如果填充请求返回 400 或 422优先检查字段名、字段类型、时间单位、音频编码。不要先怀疑 TaoToken 通道通道只负责把请求送到模型侧参数不对仍然会被 Sonic 2.0 拒绝。Sonic 2.0 的 40ms 是模型侧 Turbo 模式标称延迟实际端到端还会受网络、音频长度、客户端缓冲和播放链路影响验证时不要只看单次耗时。五、本篇常见错排查Base URL、Header、model_id 与 /tts/infill1. Base URL 填错层级错误写法包括把官网首页https://taotoken.net/填进 SDK或者填成https://taotoken.net/api/v1。正确做法是 Base URL 用https://taotoken.net/api。如果你手写请求再拼/tts/bytes如果 SDK 自己会拼 endpoint就不要再把/tts/bytes塞进 Base URL。2. Key 没有真正生效YOUR_API_KEY没替换、环境变量没 export、子进程读不到.env、Docker 容器没传环境变量都会导致 401 或 403。先在终端echo $TAOTOKEN_API_KEY确认再在 Python 里print(API_KEY[:6])确认读取成功但不要打印完整 Key。3. Header 名不对Cartesia 原生常用X-API-Key。如果你的客户端或 TaoToken 接入文档要求 Bearer则用Authorization: Bearer YOUR_API_KEY。不要同时写两个也不要把 Key 放到 URL 参数里。4. 缺少版本 Header 或版本不匹配如果文档要求Cartesia-Version就带上。缺失、写错日期或版本过旧可能导致 400、422 或返回不兼容格式。5. model_id 写错不要写sonic、sonic2、sonic-2.0、Sonic-2这种凭记忆的写法。以 Sonic 2.0 文档为准通常是sonic-2但最终以你接入时的文档为准。6. voice 参数不完整voice通常需要mode和id。只传字符串、只传id不传mode或者 voice id 不存在都会报参数错误。先用文档示例里的 voice id 跑通再换自己的音色。7. output_format 与保存方式不匹配请求 raw PCM 却保存成.wav播放器会报错请求 mp3 却用.wav后缀也可能无法识别。要保存 wav就请求 wav 容器要保存 raw就用.pcm并记录采样率、位深、声道。8. 二进制用文本模式写坏Python 必须用write_bytes不要用open(path, w)。curl 必须用--output不要把响应直接打印到终端再复制。Node 里用Buffer.from(await res.arrayBuffer())不要按字符串处理。9. 填充接口和普通 TTS 混用普通 TTS 用/tts/bytes填充功能通常有单独路径和请求体。把普通 TTS 的 payload 直接发到填充接口或者把填充字段发到普通 TTS 接口都会失败。路径和字段以 Sonic 2.0 文档为准。10. 环境变量或 SDK 缓存旧配置有些 SDK 会缓存 base_url改了.env不重启进程仍然走旧地址。重启进程或显式传入base_url和api_key。如果用了代理或 TLS 拦截也可能出现证书错误换正常网络环境测试。11. 超时设置太短普通 TTS 可能几秒返回填充长音频可能更久。timeout60不够时改为timeout120或更长。但不要因为超时就无限重试先确认请求是否已经到达服务端避免重复提交。六、语义一致 CTA把 Key 和接入文档放在同一个路径上如果你已经按上面的方式把 Base URL 改成https://taotoken.net/api下一步就是把 Key、Header、Sonic 2.0 endpoint 和填充字段逐项对齐。不要只改域名也不要只复制一段旧示例接入配置的稳定性来自“通道配置”和“模型参数”各自正确。先创建或复制 API Keyhttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentcartesia_sonic2_ttsutm_campaignrewrite再打开接入文档确认 Base URL、鉴权 Header、Sonic 2.0 的/tts/bytes、填充路径以及请求体字段https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentcartesia_sonic2_ttsutm_campaignrewriteTaoToken 提供 Key 与 Base URL 通道不替代语音合成。把通道配置放在 TaoToken把 Sonic 2.0 的模型参数按文档填好TTS 和音频填充功能就可以在支持自定义 Base URL 的工具里直接可用。