在 Coze 中使用 FishAudio

FishAudio 已在 Coze 插件商店提供两个插件。推荐直接安装插件；只有需要自定义 HTTP 请求时，才使用页面后面的高级配置。

准备 API Key

1. 在 Kitta AI API 管理页面创建一个专用于 Coze 的 API Key；
2. 确认 API 积分充足；
3. 在插件参数中按下面的格式填写：

Authorization: Bearer YOUR_FISH_AUDIO_API_KEY

Bearer 后面必须有一个空格。两个插件都使用客户自己的 API Key，调用额度由该 Kitta AI 账户承担。

自己创建私有插件

不希望安装商店插件时，可以下载并导入以下 OpenAPI 文件：

• FishAudio TTS OpenAPI
• FishAudio 音视频同步 OpenAPI
• FishAudio 文字对口型 OpenAPI
• 客户定制私有语音合成 OpenAPI
• 中文导入说明
• 交付包版本清单

在 Coze 中选择「云端插件」和「基于已有服务创建」，然后导入对应 YAML。授权方式选择「不需要授权」，客户在工具运行时填写自己的 Authorization。文件中不包含任何真实 API Key。

“文字对口型”使用网站工作台“视频配音”的二合一接口：输入视频 URL、文本和已有音色 ID，服务端先生成 TTS 音频，再自动创建口型同步任务。素材音频克隆并立即合成文本属于客户定制私有插件，不作为商店插件发布。

使用 FishAudio TTS 文字转语音

1. 打开 FishAudio TTS，将插件添加到自己的 Coze 空间；
2. 在智能体或工作流中添加 FishAudio TTS 工具；
3. 填写 Authorization、待合成文本、音色 ID 和其他可选参数；
4. 运行工具并将返回的 audio_url 连接到播放器、下载节点或后续音视频同步工具。

首次测试建议使用短文本。音色 ID 必须来自有效的系统音色或当前 Kitta AI 账户可用的自定义音色。

使用 FishAudio 图片/视频对口型

打开 FishAudio 图片/视频对口型并添加到自己的空间。插件包含两个工具：

创建任务

create_media_sync 的主要输入：

保存创建结果中的 data.id，后续将它作为 jobId 查询。创建任务会消耗 API 额度。

查询任务

将相同的 Authorization 和原任务的 jobId 传给 get_media_sync_job：

• processing：等待后继续查询同一个 jobId；
• completed：读取 data.result_url；
• failed：读取 data.error_message。

不要因为查询超时或任务仍在处理中而再次调用 create_media_sync，否则可能创建重复任务并重复扣费。

使用 FishAudio 文字对口型

文字对口型把 TTS 和口型同步合并在一个创建工具中：

视频 URL + 文本 + 音色 ID + Idempotency-Key
      ↓
create_text_lip_sync
      ↓ data.id
保存 jobId → 等待 → get_text_lip_sync_job
      ↓
completed：输出 data.result_url
failed：输出 data.error_message

每个新任务必须使用新的 Idempotency-Key；只有重试完全相同的请求时才复用原值。建议在查询节点前等待 15～30 秒。需要自动轮询时，应设置最大查询次数和总超时时间。

媒体 URL 要求

视频和音频 URL 必须允许 Kitta AI 服务端直接下载。网页地址、本地文件路径和过期的签名 URL 不能作为输入。

如果使用 Coze 上传文件生成的临时 URL，请确保它在任务创建和 Kitta AI 下载期间持续有效。生成完成后应及时下载或转存结果。

API Key 与日志安全

Authorization 是普通工具输入参数，可能出现在 Coze 的对话、调试或运行记录中。建议：

• 为 Coze 单独创建 API Key；
• 不要共享包含真实 Key 的截图或工作流模板；
• 测试或演示结束后及时轮换或撤销 Key；
• 客户使用自己的 Key，不要在公开插件中内置统一 Key。

常见问题

• 401：确认以 Bearer 开头，Key 前后没有多余空格且尚未被撤销；
• 402：检查 API 积分；会员积分和 API 积分是两个独立余额；
• 媒体下载失败：确认 URL 可公开访问，且签名有效期足够；
• 一直 processing：继续查询同一个 jobId，不要重新创建任务；
• 没有 audio_url 或 result_url：确认读取的是工具返回的 data 字段，并检查任务状态；
• Coze 记录中出现 Key：撤销该 Key，并为 Coze 创建新的专用 Key。

高级：直接调用 TTS HTTP API

不使用商店插件时，可以在 Coze HTTP 请求节点中调用：

{
  "model": "fishaudio-s21pro-flash",
  "voice": "YOUR_VOICE_ID",
  "input": "{{text}}",
  "response_format": "mp3"
}

将响应类型配置为文件或二进制，而不是 JSON。

相关文档

• OpenAI 兼容 TTS
• 口型同步 API
• 创建自定义音色
• Coze 插件商店