在 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 帳戶承擔。

自行建立私人外掛

若不希望安裝商店外掛，可以下載並匯入下列檔案：

• FishAudio TTS 文字转语音 OpenAPI
• FishAudio 图片/视频对口型 OpenAPI
• FishAudio 文字对口型 OpenAPI
• FishAudio 专属语音合成 OpenAPI
• 中文匯入說明
• 套件版本清單

在 Coze 建立以現有服務為基礎的雲端外掛並匯入 YAML。授權方式選擇不需要授權，由客戶在執行工具時填寫自己的 Authorization。檔案中不包含真實 API Key。

建議優先使用頁面右上角的「匯入」，此入口只需要 OpenAPI YAML。若頁面左側顯示 ai_plugin（JSON）、右側顯示 openapi（YAML），表示已進入 </> 程式碼建立頁面；此時 ai_plugin 不能留空。左側貼上與 YAML 同名前綴的 *.ai-plugin.json，右側貼上 *.openapi.yaml。manifest.json 只是 FishAudio 交付套件清單，不能作為 ai_plugin。完整配對請參考中文匯入說明。

目前可用方式如下：FishAudio TTS 文字转语音與FishAudio 图片/视频对口型可從外掛商店安裝；FishAudio 文字对口型與FishAudio 专属语音合成僅作為私人匯入外掛提供。

使用 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，否則可能建立重複任務並重複扣點。

組合「文字產生同步影片」工作流程

可以依下列方式串接兩個商店外掛，或匯入把 TTS 與口型同步合併為一次建立操作的私人外掛 FishAudio 文字对口型：

文字 + 音色 ID
      ↓
FishAudio TTS 文字转语音
      ↓ audio_url
影片 URL + audio_url
      ↓
create_media_sync
      ↓ data.id
儲存 jobId → 等待 → get_media_sync_job
      ↓
completed：輸出 data.result_url
failed：輸出 data.error_message

建議在查詢節點前等待 15～30 秒。若要自動輪詢，請設定最大查詢次數和總逾時時間。

私人外掛先呼叫 create_text_lip_sync，再以 get_text_lip_sync_job 查詢。每個新任務都要使用新的 Idempotency-Key；只有重試完全相同的請求時才沿用原值。

媒體 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 外掛商店