cartesia-api

Cartesia 语音与语音识别 API

Cartesia 提供文本转语音（Sonic）、语音转文本（Ink）、语音（库、克隆、本地化）以及相关的 HTTPS 和 WebSocket API。本技能涵盖应用集成和Agent 辅助编码。对于 Cartesia Line（托管语音 Agent、cartesia CLI、电话服务、Line SDK），请使用 cartesia-line。

核心指令

• **仅使用 HTTPS：**所有 HTTP 端点均使用 https://api.cartesia.ai。WebSocket 使用 wss://
  • 可能不支持 HTTP；通过 HTTP 使用的密钥可能会自动轮换
• API 版本：Cartesia 的 API 使用日期版本（Cartesia-Version: YYYY-MM-DD）。在所有服务中固定使用一个版本，并将升级版本视为主要依赖项升级——新版本可能包含破坏性变更——因此应固定选择，而非作为运行时或每次调用的变量。
  • **使用 SDK（推荐）：**SDK 已固定到其构建和测试所用的 Cartesia-Version。请让 SDK 管理版本，不要通过自定义日期（例如使用 default_headers）覆盖它，因为 SDK 可能无法兼容任意版本。要升级到较新的 API 版本，请升级 SDK。
  • **直接调用 API（不使用 SDK）：**必须自行发送 Cartesia-Version。浏览器 WebSocket 无法设置握手标头，因此请通过 ?cartesia_version=... 传递（如果两者都存在，则以查询参数为准）。
  • 可选：GET https://api.cartesia.ai/ 会返回 {"ok":true,"version":"..."}（网关当前的默认版本），可用于配置新客户端。
• **服务端身份验证：**使用 Cartesia API 密钥（sk_car_...）设置 Authorization: Bearer <api_key>。
• 客户端应用（浏览器 / 移动端）：****切勿嵌入 API 密钥。请让后端签发短期访问令牌，并使用 Authorization: Bearer <access_token>
  • 对于来自浏览器的 WebSocket，请通过 ?access_token=<token> 传递令牌（WS 握手不支持标头）
  • JS/TS SDK（v3+）可在浏览器中使用访问令牌运行——请优先使用它，而不是手动编写 WebSocket（参见下方的浏览器示例）；不要假设 SDK 只能用于服务端
  • 请参阅 Access Token API
• 错误：对于 Cartesia-Version 2026-03-01 及更新版本，错误采用结构化 JSON（error_code、title、message、request_id、可选的 doc_url）
  • 较旧版本可能会返回旧版纯文本或旧版 JSON 结构
  • 请参阅 API Errors 和 API conventions
• **权威信息来源：**优先查阅 文档，因为文档会先于 SDK / 插件 / 集成更新
  • **以 Markdown 格式获取文档：**在任意 docs.cartesia.ai 页面后附加 .md，即可获取便于 Agent 阅读的 Markdown（例如 https://docs.cartesia.ai/api-reference/stt/transcribe.md）；裸 URL 对应的是供人阅读的 HTML 页面。以编程方式获取文档时，优先使用 .md 格式
  • 机器可读索引：llms.txt 和 llms-full.txt
• **可选 MCP：**托管服务 https://mcp.cartesia.ai/mcp（通过 Playground 使用 OAuth）可在 Cursor / Claude 中列出语音、运行 TTS/STT、克隆语音以及管理发音词典
  • 对于生产环境，MCP 不能替代 API / SDK
  • 本地 stdio（uvx cartesia-mcp）用于开发；请参阅 MCP docs

使用 Sonic 进行文本转语音（生成音频）

• 选择 TTS 模型： 查看 TTS 模型，了解当前的模型 ID、支持的语言和功能。不要凭记忆使用模型 ID——训练数据会过时（例如，sonic-2 已不是当前版本）
• 语音 ID： 不要_编造_语音 ID——虚构的 UUID 无法解析。真实的语音 ID 稳定不变，因此将真实 ID 硬编码为常量很常见，也完全可行；从演练场或列出语音中复制一个。使用「列出语音」来_发现／选择_语音，而不是将其作为每次请求都必须调用的接口
• 选择端点——字节还是 WebSocket： 如果文本预先已知（固定字符串、按钮按下时），请使用 POST /tts/bytes——它会在音频生成时将其流式返回，而且更简单。只有在_输入文本_逐步到达时（例如，传输 LLM 的令牌流），才使用 WebSocket——这属于连续输入场景。不要默认使用 WebSocket；请在 TTS 端点中比较它们
• 输出音频格式： 查看 TTS 输出音频格式，了解容器格式／编码／采样率（wav + pcm_s16le @ 44.1 kHz 是安全且自包含的默认选择；mp3 不需要单独指定 encoding）

使用 Ink 进行语音转文本（转录音频）

• 选择 STT 模型： 查看 STT 模型，了解当前模型和支持的语言
• 选择 API 端点： 查看 比较 STT 端点
• 输入音频： 查看 STT 输入编码，了解支持的格式（.wav 等自包含文件包含自己的头部信息）
• 编写任何 STT 代码之前：请阅读 常见 STT 陷阱
  • 不要在没有文档依据的情况下假设模型或 API 的行为——客户端的小错误会导致隐蔽但严重的准确率下降
  • 常见的客户端错误：
    • 在转录文本中删除或插入空白字符（请原样读取模型文本——不要使用 .strip()，也不要进行规范化处理）
    • 错误地拼接转录片段
    • 不遵循 API 规范

Cartesia Python SDK

pip install cartesia

• README.md
• 所有导出的资源
• 示例
• 异步示例

将 /heads/main/ 替换为 /tags/vX.X.X/（例如 /tags/v3.2.0/），即可获取与你的 SDK 版本对应的源代码。

Cartesia TypeScript / JavaScript SDK

npm i @cartesia/cartesia-js

• README.md
• 所有导出的资源
• Node / Bun / Deno 示例
• 浏览器示例

将 /heads/main/ 替换为 /tags/vX.X.X/（例如 /tags/v3.2.0/），即可获取与你的 SDK 版本对应的源代码。

该选择哪种路径

目标	路径
应用或后端调用 REST/WebSocket	Python SDK、JS/TS SDK，或原生 API 请求 / fetch
使用 MCP 的 IDE Agent	托管的 https://mcp.cartesia.ai/mcp + 文档备用方案
已部署的语音 Agent、Line、电话服务	cartesia-line
OpenClaw 初始化	先访问 https://cartesia.sh/openclaw.md，然后查阅文档 / llms.txt

快速开始（HTTP TTS，单次调用）

仅展示格式：请根据你的 Cartesia-Version，对照 API 参考确认字段名称和枚举值：

curl -X POST "https://api.cartesia.ai/tts/bytes" \
  -H "Authorization: Bearer $CARTESIA_API_KEY" \
  -H "Cartesia-Version: 2026-03-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model_id": "sonic-3",
    "transcript": "Hello from Cartesia.",
    "voice": { "id": "f786b574-daa5-4673-aa0c-cbe3e8534c02" },
    "output_format": {
      "container": "wav",
      "encoding": "pcm_s16le",
      "sample_rate": 44100
    },
    "language": "en"
  }' \
  --output /tmp/out.wav

心智模型（适用于 LLM）

• Sonic = 用于生成语音的 TTS 模型
• Ink = 用于转录音频的 STT 模型
• Line = 独立产品：你部署自己的 Python Agent；Cartesia 在其周围运行 STT/TTS/电话服务，这与“从我的服务器调用 TTS API”不同。
• **并发 / 配额：**根据 API 错误处理 429 类错误，以及结构化的 concurrency_limited / quota_exceeded 错误。

语言、区域设置与口音

不要混淆以下概念：

• 语言 — 粗粒度代码（en、es）
• 区域设置 — 语言与地区的组合（en-US、en-GB）
• 口音 — 区域设置中的特定语音身份

一个区域设置可以包含多种口音。en-US 包括通用美式英语和南方美式英语。仅凭国家/地区无法确定唯一的口音。如果客户端会持久化或回传某个值，请优先使用 API 中的目录 ID，而不是显示名称。

本仓库中的相关资料

• Line 语音 Agent：cartesia-line
• 链接汇总：references/resources.md

常见错误

1. 覆盖 SDK 的 Cartesia-Version：使用 SDK 时，不要设置或覆盖版本 — SDK 会固定使用经过测试的版本；升级 SDK 即可切换版本。只有原始 HTTP/WS 调用方需要自行发送日期，此时应确保各处使用同一日期（日期错误可能导致不易察觉的故障或旧版错误格式）。
2. 在前端代码中使用 API 密钥：请使用由后端签发的短期访问令牌。
3. 使用错误的身份验证标头格式：示例使用 Authorization: Bearer；请遵循当前文档，而不是旧代码片段。
4. 凭记忆使用过时的 SDK / 模型代码：训练数据会滞后于 API。模型 ID 会变化（例如 sonic-2），而 JS SDK 中具名的 import { CartesiaClient } 已弃用，且无法在浏览器中运行 — 请使用 import Cartesia from "@cartesia/cartesia-js"（或默认导入）。请根据模型文档确认模型，并根据所链接的 README / 示例确认 SDK 用法。
5. 将此技能用于 cartesia deploy / Line：请改用 cartesia-line。