API 概览
通过您自己的应用程序调用 Speechdash，并创建授权该应用程序的 API 密钥。
Speechdash API 允许您的应用程序创建文档并使用与应用程序相同的语音进行语音合成。您通过 API 创建的所有内容都会出现在您的图书馆中。在应用程序中完成的音频和视频转录文档也会作为图书馆文档出现（source 是 transcription，带有 transcript_id）。没有 /transcripts REST 资源：使用文档端点。API 不会启动转录任务。
基础 URL：
https://api.speechdash.com/v1健康检查（无 API 密钥）：GET https://api.speechdash.com/health
机器可读的合约已发布在 https://api.speechdash.com/v1/openapi.json，您可以为您的语言生成客户端。
端点
| 方法 | 路径 | 目的 |
|---|---|---|
GET | /health | 服务健康状态（不在 /v1 下） |
GET | /v1/openapi.json | OpenAPI 3.1 文档 |
GET | /v1/me | 账户、计划和钱包 |
GET | /v1/documents | 列出图书馆文档，包括完成的转录 |
POST | /v1/documents | 创建一个文本文档（source=api） |
GET | /v1/documents/{document_id} | 读取文档及其文本 |
PUT | /v1/documents/{document_id} | 更新标题、文本、语言、is_archived 或 visibility |
DELETE | /v1/documents/{document_id} | 删除一个文档 |
POST | /v1/documents/{document_id}/translate | 新的翻译版本（与 MP3 导出相同的信用额度） |
GET | /v1/documents/{document_id}/export | 下载 pdf、docx、txt、csv、srt 或 vtt |
POST | /v1/audio/speech | 合成最多 5,000 个字符（JSON + 音频） |
POST | /v1/audio/stream | 流式传输 WAV，最多 20,000 个字符 |
POST | /v1/audio/stream/with-timestamps | 带有每句音频和标记的 SSE |
GET | /v1/voices | 语音目录 |
GET | /v1/voices/{voice_id} | 一个语音预设 |
MCP 服务器（用于 AI 助手）
如果您使用 Cursor、Claude 桌面版或其他 MCP 客户端，可以添加官方 Speechdash MCP 服务器，而不是直接调用 HTTP。它公开相同的图书馆（包括完成的转录）、翻译、导出、语音、账户快照以及非流式语音合成，这些都是由相同的 API 密钥和计费支持的工具。流式语音合成仍然使用 REST。
查看 MCP 服务器 以获取完整的工具列表和设置（stdio 或 Streamable HTTP）。您还可以阅读营销网站上的 Agents hub，其中包含针对 AI 系统的机器可读文档。最终用户可以从本帮助中心的 API 密钥和 MCP 开始。
创建 API 密钥
打开 设置 → API。
点击 新建密钥，并为其命名，说明它将被用于哪里，例如 生产服务器。
立即复制该密钥。只有它的前缀会被存储，因此它只会显示一次，之后永远不会再次显示。
密钥会对您的账户产生作用。将其保存在服务器上，永远不要放在浏览器、移动应用或公共仓库中。如果密钥泄露，请从 设置 → API 中撤销它，并创建一个新的。
您可以保留最多 10 个活动密钥，随时重命名它们，并查看每个密钥上次使用的时间。撤销一个密钥会立即停止其请求。
验证请求
将密钥作为 bearer 令牌发送：
curl https://api.speechdash.com/v1/me \
-H "Authorization: Bearer sh_live_your_key"没有有效密钥的请求会返回 401 并带有代码 unauthorized。
GET /me 返回您的账户 ID、电子邮件、计划和钱包余额（wallet_cents 和 display_credits），以及关于使用的 API 密钥的元数据。您可以用它来验证密钥（例如在 Zapier 中）。
POST /documents 和 POST /audio/speech 接受可选的 Idempotency-Key 头。重试相同的密钥和相同的请求体会在 24 小时内重放第一次成功的响应，因此网络故障不会创建第二个文档或双重计费。如果语音响应太大无法存储，重试相同的密钥会返回 409 而不是重新生成（原始请求已经计费）。/audio/speech 的客户端断开连接会返回 204，结算已生成的任何音频，并释放密钥以便重试可以重新生成。流式音频端点会拒绝该头。
信用额度
语音合成会从与应用程序相同的钱包中消耗信用额度：0.5 信用额度（1 钱包分）每开始生成的 30 秒音频。每个请求在生成开始前都会持有一个估计值（加上一个小幅度的边际），然后会结算为实际生成的音频。未使用的持有额度会退款；每个结算的请求会出现在 设置 → 信用额度使用 中，标记为 API 语音合成。API 响应中的 billed_credits 字段是钱包分（2 分 = 1 显示信用额度）。如果流式传输在中途被中断，已经传递的句子仍然会被计费。
如果您的余额不足以覆盖持有额度，API 会在生成任何内容之前返回 402 并带有代码 payment_required。
创建文档不会消耗信用额度，但会计入您计划的每日文档限额（免费： 每天 3 个文档；Unlimited：无每日限额）和上传时长限制。文件导出不会消耗信用额度。
计费与应用内 Cloud 播放
应用内 Cloud 重播会重用每文档的句子缓存：重播已经在服务器上生成的句子可能只需要 0 显示信用额度。REST 和 MCP 语音端点总是会合成新的音频，并在生成发生时以相同的速率计费每开始的 30 秒。API 或 MCP 合成中没有重播缓存。
限制
| 限制 | 值 |
|---|---|
对 /documents 的请求 | 每分钟每账户 120 个 |
对 /audio/* 的请求 | 每分钟每账户 60 个 |
| 并行语音请求 | 每账户 3 个 |
POST /audio/speech input | 5,000 个字符 |
POST /audio/stream input | 20,000 个字符 |
| 文档文本 | 500,000 个字符 |
| 活动 API 密钥 | 10 个 |
速率限制是按账户计算的，而不是按密钥计算的，因此额外的密钥不会提高您的配额。每个响应都会携带 X-Request-ID，而 /documents 和 /audio/* 还会返回 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset。当您联系支持时，引用 X-Request-ID。
语音请求也有一个并行限制：第四个同时的请求在还有三个在运行时会返回 429，因此一个集成不能垄断合成。重试 429 和 503 后等待 Retry-After 头。
对于超过语音限制的内容，请使用 POST /v1/documents 创建一个文档，并从应用程序中导出其音频。
文档：共享、翻译、导出
序列化文档包括 visibility 和 share_url（当为私有时为 null）。PUT /v1/documents/{id} 接受 visibility 以发布一个未列出的只读页面 /share/document/{id}，以及 is_archived 以归档或恢复。共享页面仅为文本内容。它们不会播放计费音频。
POST /v1/documents/{id}/translate 创建一个新的翻译版本。它会计费与 MP3 导出相同的信用额度（每开始的 30 秒估计语音 0.5 信用额度），并在钱包余额不足时返回 402。当翻译未配置或停止时，它会返回 503。
GET /v1/documents/{id}/export?format=pdf|docx|txt|csv|srt|vtt 下载当前版本作为附件。添加 timestamps=1 以在 PDF、DOCX、TXT 和 CSV 中包含章节时间。SRT 和 VTT 需要一个转录或完整的句子时间戳。存储的 text 在 GET /v1/documents/{id} 中保留转录时间戳标头。隐藏它们仅是应用程序阅读器的一个开关。