cartesia-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cartesia Voice & Speech APIs

Cartesia语音与语音API

Cartesia provides text-to-speech (Sonic), speech-to-text (Ink), voices (library, clone, localize), and related HTTPS and WebSocket APIs. This skill covers application integration and agent-assisted coding. For Cartesia Line (managed voice agents,

cartesia

CLI, telephony, Line SDK), use cartesia-line.

Cartesia提供文本转语音（Sonic）、语音转文本（Ink）、语音资源（库、克隆、本地化）以及相关的HTTPS和WebSocket API。本技能涵盖应用集成和代理辅助编码相关内容。如需了解Cartesia Line（托管语音代理、

cartesia

CLI、电话服务、Line SDK），请使用**cartesia-line**。

Core directives

核心指令

HTTPS only: All HTTP endpoints use
```
https://api.cartesia.ai
```
. WebSockets use
```
wss://
```
- HTTP may be unsupported; keys used over HTTP can be auto-rotated
API version: Cartesia's API is dated (
```
Cartesia-Version: YYYY-MM-DD
```
). Pin one version across your services and treat bumping it like a major dependency upgrade — a new version can carry breaking changes — so it's a fixed choice, not a runtime/per-call variable.
- With an SDK (recommended): the SDK already pins a
```
Cartesia-Version
```
  it was built and tested against. Let it manage that — do not override it (e.g. via
```
default_headers
```
  ) with your own date, since the SDK may not work against an arbitrary version. To move to a newer API version, upgrade the SDK.
- Calling the API directly (no SDK): you must send
```
Cartesia-Version
```
  yourself. Browser WebSockets can't set handshake headers, so pass it as ?cartesia_version=...
  (query wins if both are present).
- Optional:
```
GET https://api.cartesia.ai/
```
  returns
```
{"ok":true,"version":"..."}
```
  (the gateway's current default), useful when wiring a new client.
Server-side auth: Use Authorization: Bearer <api_key>
with your Cartesia API key (
```
sk_car_...
```
).
Client apps (browser / mobile): Never embed API keys. Have your backend mint a short-lived access token and use
```
Authorization: Bearer <access_token>
```
- For WebSockets from browsers, pass the token as ?access_token=<token>
  (headers are not available on WS handshake)
- The JS/TS SDK (v3+) runs in the browser with an access token — prefer it over hand-rolling the WebSocket (see its Browser Examples below); don't assume the SDK is server-only
- See Access Token API
Errors: For
```
Cartesia-Version
```
2026-03-01 and newer, errors are structured JSON (
```
error_code
```
,
```
title
```
,
```
message
```
,
```
request_id
```
, optional
```
doc_url
```
)
- Older versions may return legacy plain-text or legacy JSON structures
- See API Errors and API conventions
Source of truth: Prefer docs since they are updated first before SDKs / plugins / integrations
- Fetch docs as Markdown: append
```
.md
```
  to any
```
docs.cartesia.ai
```
  page to get the agent-readable Markdown (e.g.
```
https://docs.cartesia.ai/api-reference/stt/transcribe.md
```
  ); the bare URL is the human HTML page. Prefer the
```
.md
```
  form when fetching docs programmatically
- For machine index:
```
llms.txt
```
  and
```
llms-full.txt
```
Optional MCP: hosted server
```
https://mcp.cartesia.ai/mcp
```
(OAuth via the Playground) lists voices, runs TTS/STT, clones, and manages pronunciation dictionaries in Cursor / Claude
- MCP does not replace API / SDKs for production
- Local stdio (
```
uvx cartesia-mcp
```
  ) is for development; see MCP docs

仅使用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":"..."}
```
  （网关当前的默认版本），在搭建新客户端时很有用。
服务端认证：使用**
```
Authorization: Bearer <api_key>
```
**搭配您的Cartesia API密钥（
```
sk_car_...
```
）。
客户端应用（浏览器/移动端）：切勿嵌入API密钥。请让您的后端生成短期访问令牌，并使用
```
Authorization: Bearer <access_token>
```
- 对于浏览器发起的WebSocket连接，请通过**
```
?access_token=<token>
```
  **传递令牌（WS握手时无法设置标头）
- JS/TS SDK（v3+）可在浏览器中通过访问令牌运行——优先使用SDK而非手动实现WebSocket（请参阅下方的浏览器示例）；不要假设SDK仅适用于服务端
- 请查看访问令牌API
错误处理：对于
```
Cartesia-Version
```
2026-03-01及更新版本，错误信息为结构化JSON（包含
```
error_code
```
、
```
title
```
、
```
message
```
、
```
request_id
```
，可选
```
doc_url
```
）
- 旧版本可能返回纯文本或旧版JSON结构的错误信息
- 请查看API错误和API约定
权威来源：优先参考官方文档，因为文档会先于SDK/插件/集成更新
- 获取Markdown格式文档：在任意
```
docs.cartesia.ai
```
  页面后追加
```
.md
```
  即可获取代理可读的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用于生产环境
- 本地标准输入输出（
```
uvx cartesia-mcp
```
  ）仅用于开发；请查看MCP文档

Text-to-speech with Sonic (generating audio)

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

Choosing a TTS model: See TTS models for current model IDs, supported languages, and features. Don't trust a model ID from memory — training data goes stale (e.g.
```
sonic-2
```
is no longer current)
Voice IDs: Don't invent a voice ID — a made-up UUID won't resolve. Real voice IDs are stable, so hardcoding a real one as a constant is fine and common; copy one from the playground or List Voices. Use List Voices to discover/choose a voice, not as a required call on every request
Choosing an endpoint — bytes vs WebSocket: if the text is known up front (a fixed string, a button press), use POST /tts/bytes
— it streams audio back as it's generated and is simpler. Reach for the WebSocket only when the input text arrives incrementally (e.g. piping an LLM's token stream) — the continuations case. Don't default to WebSockets; compare them in TTS endpoints
Output audio format: See TTS output audio format for containers/encodings/sample rates (
```
wav
```
+
```
pcm_s16le
```
@ 44.1 kHz is a safe, self-contained default;
```
mp3
```
carries no separate
```
encoding
```
)

选择TTS模型：请查看TTS模型获取当前模型ID、支持的语言及功能。不要凭记忆使用模型ID——训练数据会过时（例如
```
sonic-2
```
已不再是当前版本）
语音ID：不要自行编造语音ID——虚构的UUID无法解析。真实的语音ID是稳定的，因此将真实语音ID硬编码为常量是可行且常见的做法；请从Playground或列出语音资源中复制。使用列出语音资源接口来发现/选择语音，而非在每次请求时都必须调用该接口
选择端点——字节流vs WebSocket：如果文本是预先确定的（固定字符串、按钮触发），请使用**
```
POST /tts/bytes
```
——它会在生成音频时流式返回，实现更简单。仅当输入文本是增量到达时（例如传递LLM的令牌流）才使用WebSocket**——即续传场景。不要默认使用WebSocket；请在TTS端点对比中查看两者差异
输出音频格式：请查看TTS输出音频格式获取容器/编码/采样率信息（
```
wav
```
+
```
pcm_s16le
```
@ 44.1 kHz是安全且自包含的默认选项；
```
mp3
```
无需单独指定
```
encoding
```
）

Speech-to-text with Ink (transcribing audio)

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

Choosing an STT model: see STT models for current models and supported languages
Choosing an API endpoint: see Compare STT Endpoints
Input audio: see STT input encodings for supported formats (self-contained files like
```
.wav
```
carry their own header)
Before you write any STT code: read Common STT Pitfalls
- Don't assume model or API behavior without grounding it in the docs — small client-side mistakes cause obscure but severe accuracy degradation
- Common client-side errors:
  - Stripping or inserting whitespace in transcripts (read the model's text verbatim — no
```
.strip()
```
    , no normalization)
  - Improperly concatenating transcript pieces
  - Not following the API spec

选择STT模型：请查看STT模型获取当前模型及支持的语言
选择API端点：请查看STT端点对比
输入音频：请查看STT输入编码获取支持的格式（
```
.wav
```
等自包含文件自带标头）
编写STT代码前：请阅读STT常见陷阱
- 不要在未参考文档的情况下假设模型或API的行为——客户端的小错误会导致模糊但严重的准确性下降
- 常见客户端错误：
  - 去除或插入转录文本中的空格（请原样读取模型返回的文本——不要使用
```
.strip()
```
    ，不要进行标准化）
  - 错误拼接转录片段
  - 未遵循API规范

Cartesia Python SDK

pip install cartesia

Replace

/heads/main/

with

/tags/vX.X.X/

(e.g.

/tags/v3.2.0/

) to source code specific to your SDK version.

pip install cartesia

将

/heads/main/

替换为

/tags/vX.X.X/

（例如

/tags/v3.2.0/

）即可获取对应SDK版本的源代码。

Cartesia TypeScript / JavaScript SDK

npm i @cartesia/cartesia-js

Replace

/heads/main/

with

/tags/vX.X.X/

(e.g.

/tags/v3.2.0/

) to source code specific to your SDK version.

npm i @cartesia/cartesia-js

将

/heads/main/

替换为

/tags/vX.X.X/

（例如

/tags/v3.2.0/

）即可获取对应SDK版本的源代码。

When to use which path

场景选择指南

Goal	Path
App or backend calling REST/WebSocket	Python SDK, JS/TS SDK, or native API requests / fetch
IDE agent with MCP	Hosted `https://mcp.cartesia.ai/mcp` + docs fallback
Deployed voice agent, Line, telephony	cartesia-line
OpenClaw bootstrap	`https://cartesia.sh/openclaw.md` then docs / `llms.txt`

目标	路径
应用或后端调用REST/WebSocket	Python SDK、JS/TS SDK，或原生API请求/fetch
IDE代理搭配MCP	托管服务 `https://mcp.cartesia.ai/mcp` + 文档回退
已部署语音代理、Line、电话服务	cartesia-line
OpenClaw初始化	`https://cartesia.sh/openclaw.md` 之后参考文档/ `llms.txt`

Quick start (HTTP TTS, one-shot)

快速入门（HTTP TTS，单次调用）

Shape only: confirm field names and enums against the API reference for your

Cartesia-Version

bash

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

仅作格式参考：请根据您使用的

Cartesia-Version

，在API参考中确认字段名和枚举值：

bash

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

Mental model (for LLMs)

心智模型（面向LLM）

Sonic = TTS model used to generate speech
Ink = STT model used to transcribe audio
Line = separate product: you deploy your Python agent; Cartesia runs STT/TTS/telephony around it, different from "call TTS API from my server."
Concurrency / quota: Handle
```
429
```
-class and structured
```
concurrency_limited
```
/
```
quota_exceeded
```
per API errors.

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

Language vs locale vs accent

语言vs区域设置vs口音

Do not collapse these:

language — coarse code (
```
en
```
,
```
es
```
)
locale — language-region bucket (
```
en-US
```
,
```
en-GB
```
)
accent — a specific voice identity inside a locale

One locale can have many accents.

en-US

includes General American and Southern American. Country cannot pick a unique accent. Prefer catalog IDs from the API over display names when the client will persist or send a value back.

不要混淆这三者：

language —— 粗略代码（
```
en
```
、
```
es
```
）
locale —— 语言-区域分组（
```
en-US
```
、
```
en-GB
```
）
accent —— 区域设置内的特定语音标识

一个区域设置可以包含多种口音。

en-US

包括通用美式英语和美式南方英语。国家无法唯一确定口音。当客户端需要持久化或回传值时，优先使用API提供的目录ID而非显示名称。

Related material in this repo

本仓库中的相关资源

Line voice agents: cartesia-line
Link hub: references/resources.md

Line语音代理：cartesia-line
链接中心：references/resources.md

Common mistakes

常见错误

Overriding the SDK's
Cartesia-Version
: with an SDK, don't set or override the version — it pins one it's tested against; upgrade the SDK to move versions. Only raw HTTP/WS callers send the date themselves, and then keep one date everywhere (wrong date → subtle breakage or legacy error shapes).
API keys in frontend code: use short-lived access tokens minted by your backend.
Wrong auth header style: examples use Authorization: Bearer
; match current docs, not old snippets.
Stale SDK / model code from memory: training data lags the API. Model IDs drift (e.g.
```
sonic-2
```
), and the JS SDK's named
```
import { CartesiaClient }
```
is deprecated and won't run in browsers — use
```
import Cartesia from "@cartesia/cartesia-js"
```
(or the default import). Confirm models against the models docs and SDK usage against the linked README / examples.
Using this skill for
cartesia deploy
/ Line: switch to cartesia-line.

覆盖SDK的
Cartesia-Version
：使用SDK时，不要设置或覆盖版本号——SDK已固定其测试过的版本；如需升级版本，请直接升级SDK。只有直接调用HTTP/WS的用户才需要自行传递日期，并且要在所有地方保持同一个日期（错误的日期会导致细微的功能故障或旧版错误格式）。
前端代码中嵌入API密钥：请使用后端生成的短期访问令牌。
错误的认证标头格式：示例使用**
```
Authorization: Bearer
```
**；请匹配当前文档，不要使用旧代码片段。
凭记忆使用过时的SDK/模型代码：训练数据滞后于API。模型ID会变化（例如
```
sonic-2
```
），并且JS SDK的命名导入
```
import { CartesiaClient }
```
已被弃用，无法在浏览器中运行——请使用
```
import Cartesia from "@cartesia/cartesia-js"
```
（或默认导入）。请根据模型文档确认模型信息，根据链接的README/示例确认SDK用法。
将本技能用于
cartesia deploy
/Line：请切换至cartesia-line技能。