API 文档
Fish Audio API 中文接口参考，覆盖鉴权、端点、错误与计费口径。
API 文档
本文面向准备接入 Fish Audio /v1 API 的开发者。所有示例默认使用下面的 Base URL；后续端点只写路径部分。
Base URL: https://fishaudio.org/api/open/v1例如 POST /api/open/v1/speech/tts 的完整地址是：
https://fishaudio.org/api/open/v1/speech/tts鉴权
公开 API 使用 Bearer API 密钥。所有生产请求都应从服务端发起，并在请求头中携带 API 密钥：
Authorization: Bearer YOUR_API_KEY不要把 API 密钥放在浏览器、移动端客户端、URL 查询参数、公开仓库、日志或分析事件里。生成类接口会消耗账户额度，API 密钥泄露会直接造成用量风险。
当前 API 能力
| 能力 | 方法与路径 | 状态 | 文档 |
|---|---|---|---|
| 同步文字转语音 | POST /api/open/v1/speech/tts | 当前稳定 HTTP 能力 | 文字转语音（同步） |
| 异步文字转语音 | POST /v1/tts/tasks、GET /v1/tts/tasks、GET /v1/tts/tasks/{taskId} | 当前稳定 HTTP 能力 | 文字转语音（异步） |
| 实时文字转语音 | GET /v1/tts/live | 独立实时服务，需确认生产开通 | 实时 TTS |
| 异步语音转文字 | POST /v1/asr/tasks、GET /v1/asr/tasks、GET /v1/asr/tasks/{taskId} | 当前稳定 HTTP 能力 | 语音转文字（同步） |
| 实时语音转文字 | GET /v1/asr/live | 独立实时服务，需确认生产开通 | 实时 ASR |
| 图像生成 | POST /v1/images/tasks、GET /v1/images/tasks、GET /v1/images/tasks/{taskId} | 当前稳定 HTTP 能力 | 图像生成 |
| 视频生成 | POST /v1/videos/tasks、GET /v1/videos/tasks、GET /v1/videos/tasks/{taskId} | 当前稳定 HTTP 能力 | 视频生成 |
| 口型同步 | POST /v1/lip-sync/tasks、GET /v1/lip-sync/tasks、GET /v1/lip-sync/tasks/{taskId} | 当前稳定 HTTP 能力 | 口型同步 |
| 音色管理 | GET /api/open/v1/voices、POST /api/open/v1/voices、DELETE /api/open/v1/voices/{voiceId} | 当前稳定 HTTP 能力 | 音色管理 |
| 用量与余额 | GET /v1/usage | 当前稳定 HTTP 能力 | 用量与余额 |
实时 TTS 和实时 ASR 由独立 WebSocket 服务承载，不属于普通 Next.js HTTP 路由。生产可用性取决于部署拓扑和账号能力；未确认开通前，请使用同步 TTS、异步 TTS 或异步 ASR 作为稳定接入路径。
机器可读 schema：
GET /api/openapi.json请求格式
JSON 接口请发送：
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY同步 TTS 是一个例外：成功时响应体是音频二进制，而不是 JSON。其它任务类接口通常返回任务对象或任务列表。
任务模型
除同步 TTS 和只读查询外，大多数媒体能力采用异步任务模型：
POST /v1/.../tasks创建任务。- 服务端返回
taskId、status和creditsCharged。 - 客户端使用
GET /v1/.../tasks/{taskId}查询任务详情。 - 任务成功后读取
audioUrl、transcript、resultImageUrl或resultVideoUrl等结果字段。
任务列表接口通常支持 limit、offset 和 status 查询参数，状态包括 pending、processing、succeeded 和 failed。
响应与错误
成功响应随端点不同而变化：同步 TTS 返回 audio/mpeg 或 audio/wav，任务创建返回 JSON，列表接口返回 data 和 pagination。
错误响应使用嵌套结构：
{
"error": {
"code": "invalid_request",
"message": "Invalid request",
"requestId": "req_xxx"
}
}常见状态码包括 400 请求参数错误、401 鉴权失败、402 额度不足、403 权限不足、404 任务不存在，以及 500 服务端错误。排查问题时请记录 requestId。
计费与积分
生成类接口会返回或记录 creditsCharged，表示本次任务实际扣费。用量汇总可以通过 GET /v1/usage 查询。典型口径：
- 同步 TTS 成功时会通过响应头
x-kitta-credits-charged返回扣费值。 - 异步 TTS 创建时返回
creditsCharged，任务详情也会保留该字段。 - ASR、图片、视频和口型同步任务都在任务 DTO 中返回
creditsCharged。 - 只读列表、任务查询、音色列表和用量查询不创建新任务，但仍需要鉴权。
扣费接口通常会先校验额度，任务失败时以任务状态和用量记录为准。客户端不要只根据 HTTP 请求是否发出判断是否扣费，应读取响应或任务详情中的 creditsCharged。
兼容性
新客户端应优先使用本页列出的 /v1 路径。旧路径迁移关系见 迁移指南。不要把旧开放 API 路径混用到同一个 SDK 层；建议先迁移只读接口，再迁移扣费和任务创建接口。