迁移指南

新接入应使用当前 /v1 路径，并以 https://kittaaudio.com 作为 Base URL。旧客户端里可能存在历史 /api/open/* 路径、海外 OpenAPI 路径或早期草案路径。迁移时请统一到当前合同。

Base URL: https://fishaudio.org/api/open/v1

推荐迁移顺序

1. 先迁移只读接口，例如用量查询、音色列表和任务详情。
2. 再迁移任务创建接口，例如同步 TTS、异步 TTS、ASR、图片、视频和口型同步。
3. 灰度期间同时记录旧路径和新路径的请求量、状态码和 requestId。
4. 确认生产流量不再依赖旧路径后，再删除 SDK 中的旧路径分支。

不要一次性替换所有接口后直接上线。扣费接口需要特别关注重试和额度对账。

路径迁移表

下表左侧是旧路径或旧概念，右侧是当前 API 路径。实时 TTS 和实时 ASR 由独立 WebSocket 服务承载，迁移前需确认生产部署和账号能力；未确认前请迁移到稳定的 HTTP 同步或异步任务路径。

旧路径示例：POST /api/open/tts、POST /api/open/tts/jobs、POST /api/open/speech-to-text、POST /api/open/lip-sync/create、GET /api/open/lip-sync/list、GET /api/open/lip-sync/query?id=... 都应迁移到上表对应的当前路径。

如果旧客户端曾使用海外路径，例如 POST /v1/speech/tts、POST /v1/speech/transcriptions、POST /v1/media/lip-sync/jobs，也应迁移到 POST /api/open/v1/speech/tts、POST /v1/asr/tasks、POST /v1/lip-sync/tasks。

字段迁移要点

TTS

当前 TTS 请求只需要这些公开字段：

{
  "text": "Hello",
  "voiceId": "clara",
  "engineModelId": "fishaudio-s2pro",
  "speed": 1,
  "emotion": "calm"
}

text、voiceId 为核心字段；异步 TTS 如需指定引擎模型，使用 engineModelId。迁移 SDK 时应把内部音色选择统一映射到 voiceId，不要把国内站的 model 枚举传到海外 Open API。

同步 TTS 成功响应不是 JSON，而是音频二进制。需要查询生成后的余额时，调用 GET /api/open/v1/profile 读取当前账户额度。

ASR

当前 ASR 创建任务使用：

{
  "audioUrl": "https://example.com/audio.mp3",
  "model": "kitta-asr-v1",
  "durationSeconds": 65,
  "languageHints": ["zh"],
  "language": "zh"
}

audioUrl 为必填。旧客户端如果使用 snake_case 音频字段，需要在 SDK 层转换为 audioUrl。

口型同步

当前口型同步创建任务使用：

{
  "model": "kitta-lip-sync-v1",
  "inputMode": "video",
  "videoUrl": "https://example.com/video.mp4",
  "audioUrl": "https://example.com/audio.mp3",
  "durationSeconds": 12
}

图片驱动时传 inputMode: "image" 和 imageUrl，可选 referenceImageUrl。

音色

当前公开 /v1 只提供 GET /v1/voices。创建、删除和单个音色详情不是当前公开合同的一部分。旧 SDK 如果暴露音色管理方法，应在当前版本中标记为不可用，或改为引导用户使用站内产品能力。

错误结构迁移

旧客户端可能按顶层 code / message 解析错误。当前 /v1 错误结构是：

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request",
    "requestId": "req_xxx"
  }
}

迁移 SDK 时应读取 response.error，并保留未知字段。

响应兼容

典型差异：

• 同步 TTS 成功时返回音频二进制。需要生成后的额度信息时，调用 GET /api/open/v1/profile。
• 异步 TTS 创建任务返回 { taskId, status, creditsCharged }。
• TTS、ASR、图片、视频和口型同步任务详情都使用任务 DTO，并保留 creditsCharged、时间戳和错误字段。
• 列表接口返回 data 和 pagination。
• 用量查询取代旧账户信息接口，用于查询余额、API 用量和近期流水。

计费迁移检查

迁移扣费接口时请同时检查：

• 同步 TTS 完成后是否按需调用 GET /api/open/v1/profile 对账。
• 异步任务创建和任务详情是否保存 creditsCharged。
• ASR、图片、视频和口型同步是否按任务 DTO 对账。
• 用量页是否改为读取 GET /v1/usage，而不是旧账户信息字段。

灰度验证清单

• 使用测试 API 密钥调用 GET /v1/usage，确认鉴权和 Base URL 正确。
• 调用 GET /api/open/v1/voices，选取一个可用 voiceId 和 defaultEngineModelId。
• 用短文本调用 POST /api/open/v1/speech/tts，验证音频响应。
• 创建一个异步 TTS 任务并查询到终态。
• 用短音频创建 ASR 任务，确认 transcript 和 creditsCharged。
• 创建一个短口型同步任务，确认 taskId、状态轮询和最终 resultVideoUrl。
• 故意使用错误 API 密钥和不足额度场景，确认 SDK 能解析嵌套 error 响应。

完成以上验证后，再把生产流量切到当前 /v1 路径。