# FishAudio Coze 私有插件导入包

本目录用于不安装官方商店插件、希望在自己 Coze 空间创建私有插件的客户。

## 文件

- `fishaudio-tts.openapi.yaml`：`FishAudio TTS 文字转语音` 插件，一个 `generate_tts` 工具。
- `fishaudio-media-sync.openapi.yaml`：`FishAudio 图片/视频对口型` 插件，包含 `create_media_sync` 和 `get_media_sync_job`。
- `fishaudio-video-dubbing.openapi.yaml`：`FishAudio 文字对口型` 插件，包含 `create_text_lip_sync` 和 `get_text_lip_sync_job`。
- `fishaudio-personal-voice.openapi.yaml`：客户定制私有插件，包含 `create_personal_voice` 和 `get_personal_voice_job`，不作为商店插件发布。
- `fishaudio-tts-icon.png`：文字转语音插件头像，FishAudio Logo 加 `TTS` 角标。
- `fishaudio-media-sync-icon.png`：图片/视频对口型插件头像，FishAudio Logo 加 `LS` 角标。
- `fishaudio-video-dubbing-icon.png`：文字对口型插件头像，FishAudio Logo 加 `VD` 角标。
- `fishaudio-personal-voice-icon.png`：客户定制私有插件头像，FishAudio Logo 加 `PVS` 角标。
- `manifest.json`：交付包版本、端点和文件清单。

三个商店候选插件相互独立：已有音色生成音频时导入 TTS；已有音频生成口型视频时导入图片/视频对口型；已有音色和文本直接生成口型视频时导入文字对口型。素材音频克隆并合成音频属于客户定制私有插件，不作为商店候选。

## 在 Coze 导入

1. 进入「资源库」并新建插件。
2. 类型选择「云端插件」。
3. 创建方式选择「云侧插件 - 基于已有服务创建」。
4. 使用「导入」功能上传或粘贴对应的 OpenAPI YAML。
5. 插件 URL 应为 `https://fishaudio.org`。
6. 授权方式选择「不需要授权」。`Authorization` 由每位客户在工具运行时填写。
7. 启用导入的工具，使用客户自己的 Fish Audio API Key 完成试运行。
8. 发布到客户自己的空间；私有使用不需要等待插件商店审核。

## Authorization

每个工具都要求：

```text
Bearer YOUR_FISH_AUDIO_API_KEY
```

`Bearer` 后面必须有一个空格。不要把真实 Key 写入 YAML、截图或对外分享的工作流模板。建议为 Coze 单独创建 Key，并按需撤销或轮换。

## TTS 注意事项

TTS 文件调用：

```text
POST https://fishaudio.org/api/open/v1/speech/tts
```

请求中的 `cache` 必须保持为 `true`。这样接口返回包含 `audio_url` 的 JSON；如果改为 `false`，接口会返回音频二进制，Coze 可能报响应解析错误。

`audio_url` 是临时链接，目前保留三天。请及时下载或转存。

## 音视频同步注意事项

创建工具返回 `data.id`。必须保存该值，并把它作为查询工具的 `jobId`：

```text
create_media_sync → data.id → 等待 15～30 秒 → get_media_sync_job
```

- `processing`：继续查询同一个 `jobId`。
- `completed`：读取 `data.result_url`。
- `failed`：读取 `data.error_message`。

任务仍在处理或查询超时时不要重新调用 `create_media_sync`，否则可能重复创建任务并重复扣费。

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

视频模式默认按视频、音频中较短的时长向上取整计费。创建响应会返回 `billing_duration_seconds` 和 `credits_used`；任务成功后价格不再变化，失败则全额退款。只有明确需要把视频延长到音频长度时才设置 `video_extension: true`。

## 文字对口型注意事项

该插件调用网站工作台“视频配音”使用的二合一接口：服务端先用指定音色把文字生成音频，再自动创建口型同步任务：

```text
create_text_lip_sync → data.id → 等待 15～30 秒 → get_text_lip_sync_job
```

- 输入 `video_url`、目标 `text` 和已有音色 `reference_id`，无需预先生成或提供 `audio_url`。
- 每次新任务填写新的 `Idempotency-Key`；只有重试完全相同的请求时才复用原值。
- 创建响应中的 `data.audio_url` 是中间 TTS 音频；最终视频读取查询响应中的 `data.result_url`。
- `credits_used` 分别返回 `tts`、`lip_sync` 和 `total`。
- 查询同一个 `jobId` 不会重新生成语音或重复扣费；任务处理中不得再次创建。

## 客户定制私有语音合成注意事项

该插件把“创建持久私有音色”和“使用新音色合成文本”组合为一次创建操作，再通过查询工具取得音频：

```text
create_personal_voice → data.id → 等待 → get_personal_voice_job
```

- 输入 `source_audio_url` 和目标 `text`，不需要参考音频原文。
- `source_audio_url` 必须可由 Fish Audio 服务端直接下载，最大 10 MB。
- 每次新任务填写新的 `Idempotency-Key`；只有重试完全相同的请求时才复用原值。
- 创建成功后会保留一个私有音色，`data.voice_id` 可用于后续普通 TTS。
- `completed` 时读取 `data.audio_url`；该临时链接目前保留三天。
- 克隆和 TTS 分别计费。若音色已创建但 TTS 启动失败，错误会返回 `clone_completed: true` 和 `voice_id`，已创建音色及其费用会保留。

## 发布前检查

- 导入后工具数量正确：TTS 为 1 个，图片/视频对口型为 2 个，文字对口型为 2 个，客户定制私有语音合成为 2 个。
- TTS 试运行返回非空 `audio_url`。
- 创建同步任务返回非空 `data.id`。
- 查询工具能返回 `status`、`progress`、`result_url` 和 `error_message`。
- 文字对口型创建工具返回 `data.id` 和 `data.audio_url`，查询完成后返回 `data.result_url`。
- 客户定制私有语音合成创建工具返回 `voice_id` 和 `data.id`，查询完成后返回 `audio_url`。
- 插件或使用示例中没有真实 API Key。