Cartesia 免费档每月 2 万 credits：语音合成约 27 分钟加转写近两小时

接口地址与鉴权

Cartesia 的 base_url 形态为 https://api.cartesia.ai，语音合成走 /tts/bytes（或流式接口），语音转写走 STT 相关路径，完整路径以官方文档为准。鉴权用请求头 X-API-Key，另外每个请求都必须带 Cartesia-Version 版本头，取值写官方文档当前标注的 API 版本号，填错会直接返回版本不匹配的错误。

常用模型名：语音合成用 sonic-3.6（即 Sonic-3.6），语音转写用 ink-2（即 Ink-2）。模型标识会随版本更新，真实可用列表以控制台或文档中的模型页为准。

一次语音合成请求

先导出环境变量，密钥与版本号都从控制台获取：

export CARTESIA_API_KEY="你在控制台创建的密钥"
export CARTESIA_VERSION="官方文档标注的 API 版本号"
export CARTESIA_VOICE_ID="在音色页面复制的音色 ID"

然后用 curl 发起一次合成调用，把关键参数放在 JSON 请求体里：

curl -X POST "https://api.cartesia.ai/tts/bytes" \
  -H "X-API-Key: $CARTESIA_API_KEY" \
  -H "Cartesia-Version: $CARTESIA_VERSION" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "sonic-3.6",
    "transcript": "你好，这是一段语音合成测试。",
    "voice": {"mode": "id", "id": "VOICE_ID"},
    "language": "zh",
    "output_format": {"container": "wav", "sample_rate": 44100, "encoding": "pcm_s16le"}
  }' --output test.wav

关键参数说明：model_id 指定合成模型；transcript 是要朗读的文本，按字符计费，1 credit 约等于 1 个字符；voice 指定音色，可传 ID 或内联声音数据；language 建议显式指定，中文场景填 zh 可显著提升发音准确度；output_format 控制容器、采样率与编码，采样率越高消耗不变但带宽更大。若把 voice.id 换成变量，请替换成真实音色 ID，不要保留占位字符串。语音转写则把音频文件与 model_id 设为 ink-2 提交到 STT 接口，参数以文档为准。

额度耗尽与限流的典型表现

• 429 状态码：多为并发或速率超限。免费档 TTS 只允许 2 并发、STT 允许 8 并发，批量任务需要自行加队列控制。
• 402 或 403 类错误：通常是 credits 用尽或当前密钥无权限。先看控制台用量页是否归零，再看密钥是否被删除。
• 版本头报错：请求返回关于 API 版本的提示，说明 Cartesia-Version 取值与当前服务不匹配，按文档更新即可。
• 音频为空或截断：检查请求是否超长、输出格式字段是否拼错，以及是否误用了免费层不支持的音色克隆功能。

排查顺序建议为：先确认控制台剩余 credits 与当月重置时间，再核对密钥与版本头，然后用最小请求体（一句短文本）单独测试，最后才排查并发与网络层。上线前还应确认免费层不含商用授权，如需商用请升级到 Pro 档。