Use FishAudio in Coze

FishAudio provides two plugins in the Coze plugin store. Installing the plugins is the recommended setup; use the advanced HTTP configuration only when you need a custom request.

Prepare an API key

1. Create a dedicated Coze key on the Fish Audio API management page.
2. Check that your API credit balance is sufficient.
3. Pass the key to plugin tools in this format:

Authorization: Bearer YOUR_FISH_AUDIO_API_KEY

There must be one space after Bearer. Both plugins use the customer's own API key, and usage is charged to that Fish Audio account.

Create a private plugin

If you do not want to install the store plugins, download and import these files:

• 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
• English import guide
• Package manifest

The recommended route is to click Import in the upper-right corner and upload only the relevant OpenAPI YAML. Select no authorization; the customer supplies their own Authorization at runtime. The files contain no real API key.

If the page shows ai_plugin (JSON) on the left and openapi (YAML) on the right, you are on the </> code-creation page. Do not leave ai_plugin empty: paste the matching *.ai-plugin.json on the left and the *.openapi.yaml with the same prefix on the right. manifest.json is only the FishAudio package inventory and must not be used as ai_plugin. See the English import guide for the complete pairing table.

Current availability: FishAudio TTS 文字转语音 and FishAudio 图片/视频对口型 are public store plugins; FishAudio 文字对口型 and FishAudio 专属语音合成 are private-import plugins only.

FishAudio 文字对口型 uses the same combined API as the website Video Dubbing workbench: provide a video URL, text, and an existing voice ID; the service generates TTS audio and then creates the lip-sync job automatically. FishAudio 专属语音合成 creates a private voice from source audio and synthesizes the target text. Both are currently private-import plugins.

Use FishAudio TTS 文字转语音

1. Open FishAudio TTS 文字转语音 and add it to your Coze workspace.
2. Add the FishAudio TTS 文字转语音 tool to an agent or workflow.
3. Enter Authorization, the input text, a Voice ID, and any optional controls.
4. Run the tool and connect the returned audio_url to playback, download, or the Media Sync plugin.

Use a short sentence for the first test. The Voice ID must be a valid system voice or a custom voice available to the current Fish Audio account.

Use FishAudio 图片/视频对口型

Open FishAudio 图片/视频对口型 and add it to your workspace. The plugin provides two tools:

Create a job

Main create_media_sync inputs:

Save data.id from the create response and use it as jobId for subsequent queries. Creating a job consumes API credits.

Query a job

Pass the same Authorization and the original jobId to get_media_sync_job:

• processing: wait and query the same jobId again.
• completed: read data.result_url.
• failed: read data.error_message.

Do not call create_media_sync again just because a query times out or the job is still processing. Doing so may create and charge for a duplicate job.

Use FishAudio 文字对口型

Text-to-Lip-Sync combines TTS and lip sync in one create tool:

Video URL + text + Voice ID + Idempotency-Key
      ↓
create_text_lip_sync
      ↓ data.id
Save jobId → wait → get_text_lip_sync_job
      ↓
completed: output data.result_url
failed: output data.error_message

Use a new Idempotency-Key for every new job; reuse the original value only when retrying the exact same request. Start with a 15–30 second wait before the query node. If you automate polling, set a maximum number of queries and a total timeout.

Set the optional fit_audio_to_video input to true when the generated narration should automatically speed up or slow down to match the video duration. The default is false, and the supported adjustment range is 0.5x–2x without pitch changes.

Media URL requirements

Video and audio URLs must be directly downloadable by the Fish Audio service. Web page URLs, local file paths, and expired signed URLs cannot be used.

For temporary URLs generated from Coze uploads, make sure the URL remains valid while the job is created and Fish Audio downloads the media. Download or transfer completed results promptly.

Upload local reference audio in a workflow

The standalone FishAudio 专属语音合成 test page accepts source_audio_url as text and cannot select a local computer file. To let an end user upload local audio, add four required inputs to a Coze workflow Start node: source_audio (Audio, not File), text (String), authorization (String), and idempotency_key (String).

Bind create_personal_voice.source_audio_url to source_audio, text to text, and the two headers to authorization and idempotency_key. Coze converts the Audio input to a temporary accessible URL, so the user does not need to enter a separate source_audio_url.

Build and run the minimal flow first to verify upload and creation:

Start (Audio + text + key + idempotency value)
  → create_personal_voice
  → End (voice_id + jobId)

The Coze upload control may show a 500 MB limit, but this Fish Audio endpoint is limited to 10 MB. If the tool input in the run log contains a https://...byteimg.com/... URL, Coze successfully converted the local file to a temporary URL. A later 401 ERR_UNAUTHORIZED means the key is invalid, revoked, or malformed; it does not mean the upload failed.

After the create tool returns data.id, either wait 15–30 seconds and manually run get_personal_voice_job, or add automatic polling with a Loop node. Inside the loop, use a Python Code node with await asyncio.sleep(15), query the same data.id, and use a Selector to inspect the status. Terminate for completed or failed, and continue for processing. Limit the loop to 20 iterations and return the original jobId if that limit is reached; never create another job.

Use a new Idempotency-Key for each new generation. Re-uploading a file creates a new temporary URL and therefore also requires a new key. See the private plugin import-package guide for the complete input table, minimal flow, automatic polling, and error diagnosis.

API key and log safety

Authorization is a normal tool input and may appear in Coze conversations, debug records, or runtime logs. Recommended practices:

• Create a separate API key for Coze.
• Do not share screenshots or workflow templates containing a real key.
• Rotate or revoke demonstration and test keys when they are no longer needed.
• Each customer should use their own key; never embed a shared key in a public plugin.

Troubleshooting

• 401 / ERR_UNAUTHORIZED: confirm the value starts with Bearer , contains no extra spaces, and has not been revoked. If the log already contains a byteimg.com URL, the upload path succeeded.
• 402: check API credits; membership and API credits are separate balances.
• 413 / file too large: follow Fish Audio's 10 MB limit, not the 500 MB limit displayed by the Coze upload control.
• Media download failed / 415: verify that the URL is directly accessible, its signature lasts long enough, and the file uses a common audio format.
• Job remains processing: continue querying the same jobId; do not create another job.
• No audio_url or result_url: read the returned data object and check the task status.
• A key appears in Coze records: revoke it and create a new dedicated Coze key.

Advanced: call the TTS HTTP API directly

Without the store plugin, use a Coze HTTP request node:

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

Configure the response as a file or binary value instead of JSON.

Related documentation

• OpenAI-compatible TTS
• Lip Sync API
• Create a custom voice
• Coze plugin store