在 Coze 中使用 FishAudio

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

准备 API Key

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

Authorization: Bearer YOUR_FISH_AUDIO_API_KEY

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

自己创建私有插件

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

• FishAudio TTS 文字转语音 OpenAPI
• FishAudio TTS 文字转语音 ai_plugin JSON
• FishAudio 图片/视频对口型 OpenAPI
• FishAudio 图片/视频对口型 ai_plugin JSON
• FishAudio 文字对口型 OpenAPI
• FishAudio 文字对口型 ai_plugin JSON
• FishAudio 专属语音合成 OpenAPI
• FishAudio 专属语音合成 ai_plugin JSON
• 中文导入说明
• 交付包版本清单

推荐点击页面右上角「导入」，只上传对应的 OpenAPI YAML。授权方式选择「不需要授权」，客户在工具运行时填写自己的 Authorization。文件中不包含任何真实 API Key。

如果看到左侧 ai_plugin（填写 json）、右侧 openapi（填写 yaml） 两个编辑框，说明进入了 </> 代码创建页面。此时 ai_plugin 不能留空：左侧粘贴与 YAML 同名前缀的 *.ai-plugin.json，右侧粘贴 *.openapi.yaml。manifest.json 只是 FishAudio 交付包清单，不能粘贴到 ai_plugin 输入框。完整配对表见中文导入说明。

当前可用方式如下：FishAudio TTS 文字转语音和FishAudio 图片/视频对口型可从插件商店安装；FishAudio 文字对口型和FishAudio 专属语音合成仅作为私有导入插件提供。

“文字对口型”使用网站工作台“视频配音”的二合一接口：输入视频 URL、文本和已有音色 ID，服务端先生成 TTS 音频，再自动创建口型同步任务。“专属语音合成”使用素材音频创建私有音色并合成目标文本。两者目前都作为私有导入插件提供。

使用 FishAudio TTS 文字转语音

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

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

使用 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 秒。需要自动轮询时，应设置最大查询次数和总超时时间。

需要让配音自动匹配视频时长时，可将可选参数 fit_audio_to_video 设为 true。该参数默认是 false，支持在不改变音高的情况下进行 0.5x～2x 加减速。

媒体 URL 要求

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

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

在工作流中上传本地参考音频

FishAudio 专属语音合成 的单独试运行页面只接受 source_audio_url 文本参数，不能直接选择电脑文件。要让最终使用者上传本地音频，请在 Coze 工作流开始节点增加 source_audio（Audio，不要选 File）、text（String）、authorization（String）和 idempotency_key（String）四个必填输入。

将 create_personal_voice 工具的 source_audio_url 绑定到 source_audio，text 绑定到 text，两个 Header 分别绑定到 authorization 和 idempotency_key。Coze 会将 Audio 输入转换为临时可访问 URL；不要再让客户手工填写 source_audio_url。

先搭建并试运行最小流程，确认上传和创建成功：

开始（Audio + 文本 + Key + 幂等键）
  → create_personal_voice
  → 结束（voice_id + jobId）

Coze 上传控件可能显示最大 500 MB，但 Fish Audio 此接口限制为 10 MB。如果运行日志的工具输入中出现 https://...byteimg.com/...，说明本地文件已经成功转换为临时 URL。此后出现 401 ERR_UNAUTHORIZED 表示 Key 无效、已撤销或格式错误，不代表上传失败。

创建工具返回 data.id 后，可以等待 15～30 秒手动调用一次 get_personal_voice_job。需要自动查询时，再使用“循环节点”：循环体内先用 Python 代码节点执行 await asyncio.sleep(15)，再查询同一个 data.id，最后用选择器判断状态；completed 或 failed 时终止循环，processing 时进入下一轮。建议最多循环 20 次，达到上限后返回原 jobId，不要重新创建任务。

每次新生成使用新的 Idempotency-Key；重新上传文件会产生新的临时 URL，也应使用新的幂等键。完整输入表格、最小流程、自动轮询和错误判读见私有插件导入包说明。

API Key 与日志安全

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

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

常见问题

• 401 / ERR_UNAUTHORIZED：确认以 Bearer 开头，Key 前后没有多余空格且尚未被撤销；如果日志已有 byteimg.com URL，则上传链路已经成功；
• 402：检查 API 积分；会员积分和 API 积分是两个独立余额；
• 413 / 文件过大：以 Fish Audio 的 10 MB 限制为准，不要以 Coze 上传控件显示的 500 MB 为准；
• 媒体下载失败 / 415：确认 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 插件商店