---
canonical_url: "https://docs.composio.dev/toolkits/fish_audio"
markdown_url: "https://docs.composio.dev/toolkits/fish_audio.md"
product: "platform"
version: null
last_updated: null
---

# Fish Audio

Fish Audio provides speech synthesis, transcription, voice cloning, and conversational voice-agent APIs.

- **Category:** audio & speech
- **Auth:** API_KEY
- **Composio-managed OAuth available?** N/A
- **Tools:** 12
- **Triggers:** 0
- **Slug:** `FISH_AUDIO`
- **Version:** 20261014_01
- **Instant:** Supported on the latest version. Support varies by tool.

## Tools

### Configure Agent

**Slug:** `FISH_AUDIO_CONFIGURE_AGENT`

Partially update an agent's draft prompt, voice, and core conversation behavior without publishing it.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | Yes | Agent ID to configure. |
| `timezone` | string | No | Conversation timezone, up to 64 characters. |
| `eagerness` | string ("relaxed" | "balanced" | "eager") | No | Response timing: relaxed, balanced, or eager. |
| `record_audio` | boolean | No | Whether future sessions should record audio. |
| `first_message` | string | No | Fixed greeting text when first_message_mode is fixed. |
| `interruptible` | boolean | No | Whether callers may interrupt the agent while it speaks. |
| `system_prompt` | string | No | Replacement draft system prompt; Fish Audio limits it to 4000 tokens. |
| `voice_model_id` | string | No | Replacement voice model ID returned by List Voice Models. |
| `speaking_language` | string ("en" | "ja" | "zh" | "ko" | "es" | "fr" | "de") | No | Speaking language: en, ja, zh, ko, es, fr, or de. |
| `first_message_mode` | string ("off" | "fixed" | "prompt") | No | Greeting mode: off, fixed, or prompt. |
| `first_message_prompt` | string | No | Instructions for generating the greeting when first_message_mode is prompt. |
| `max_duration_seconds` | integer | No | Maximum session duration from 60 to 3600 seconds. |
| `interruption_sensitivity` | string ("low" | "balanced" | "high") | No | Interruption sensitivity: low, balanced, or high. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Create Agent

**Slug:** `FISH_AUDIO_CREATE_AGENT`

Create a private Fish Audio agent, optionally with an initial prompt, voice, and core conversation settings. The new agent remains a draft until separately published.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Agent name (1-120 characters). |
| `description` | string | No | Agent purpose or operator-facing description (up to 2000 characters). |
| `record_audio` | boolean | No | Whether sessions should record audio. |
| `first_message` | string | No | Fixed initial greeting when first_message_mode is fixed. |
| `system_prompt` | string | No | Initial system prompt; Fish Audio limits it to 4000 tokens. |
| `voice_model_id` | string | No | Voice model ID returned by List Voice Models. |
| `speaking_language` | string ("en" | "ja" | "zh" | "ko" | "es" | "fr" | "de") | No | Speaking language: en, ja, zh, ko, es, fr, or de. |
| `first_message_mode` | string ("off" | "fixed" | "prompt") | No | Initial greeting mode: off, fixed, or prompt. |
| `max_duration_seconds` | integer | No | Maximum session duration from 60 to 3600 seconds. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Delete Agent

**Slug:** `FISH_AUDIO_DELETE_AGENT`

Permanently delete a Fish Audio agent by ID; use only when deletion is explicitly intended.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | Yes | ID of the agent to permanently delete. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Design Voice

**Slug:** `FISH_AUDIO_DESIGN_VOICE`

Generate original voice previews synchronously from a voice description, without cloning or saving a voice model.

**Instant:** Supported on the latest version.

**Instant pricing:** $0.01 per successful voice-design request (1–4 candidates)

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `n` | integer | No | Number of voice candidates (1–4); the request is billed once. |
| `seed` | integer | No | Optional deterministic generation seed. |
| `speed` | number | No | Preview speaking speed multiplier, greater than zero and at most 3. |
| `language` | string | No | Optional BCP-47 language hint, such as en or ja. |
| `num_step` | integer | No | Number of diffusion steps (1–128). |
| `instruction` | string | Yes | Describe the desired original voice; do not impersonate an identifiable person. |
| `guidance_scale` | number | No | Nonnegative classifier-free guidance scale. |
| `reference_text` | string | No | Optional preview text, up to 150 characters. |
| `instruct_guidance_scale` | number | No | Nonnegative instruction guidance scale. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Account Balance

**Slug:** `FISH_AUDIO_GET_ACCOUNT_BALANCE`

Return the connected Fish Audio account's package allowance and API credit so an agent can distinguish free quota from paid credit.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `team_id` | string | No | Optional team ID whose API credit should be checked; omit for the connected account's active workspace. |
| `check_free_credit` | boolean | No | Ask Fish Audio to include current free-credit eligibility in the API-credit result. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Agent

**Slug:** `FISH_AUDIO_GET_AGENT`

Return an agent's workspace metadata together with its current draft conversation configuration.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | Yes | Agent ID returned by List Agents or Create Agent. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Get Voice Model

**Slug:** `FISH_AUDIO_GET_VOICE_MODEL`

Get a Fish Audio voice model by ID and inspect whether it is trained and suitable for synthesis.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `model_id` | string | Yes | Voice model ID returned by List Voice Models. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Agents

**Slug:** `FISH_AUDIO_LIST_AGENTS`

Search agents in the connected Fish Audio workspace, including draft or archived agents when requested.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `search` | string | No | Case-insensitive search across agent names and descriptions. |
| `page_size` | integer | No | Maximum agents to return in this page (1-100). |
| `next_cursor` | string | No | Continuation cursor from a previous response. Omit for the first page; pass it back unchanged to fetch the next page. |
| `include_archived` | boolean | No | Whether to include archived agents. |
| `publication_state` | string ("all" | "live" | "draft") | No | Publication state to include: all, live, or draft. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Agent Sessions

**Slug:** `FISH_AUDIO_LIST_AGENT_SESSIONS`

List conversation sessions for the workspace or a specific agent, filtered by lifecycle status, caller, or creation time.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_id` | string | No | Only return sessions belonging to this agent ID. |
| `statuses` | array | No | Lifecycle statuses to include: pending, active, completed, failed, or unknown. A comma-separated string is also accepted. |
| `page_size` | integer | No | Maximum sessions to return in this page (1-100). |
| `next_cursor` | string | No | Continuation cursor from a previous response. Omit for the first page; pass it back unchanged to fetch the next page. |
| `caller_number` | string | No | Exact E.164 caller number for phone sessions. |
| `created_after` | string | No | Return sessions created after this ISO 8601 timestamp. |
| `created_before` | string | No | Return sessions created before this ISO 8601 timestamp. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### List Voice Models

**Slug:** `FISH_AUDIO_LIST_VOICE_MODELS`

Search public or workspace-owned Fish Audio voice models. Before synthesis, select an item whose type is tts; svc model IDs are not compatible with TTS.

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tags` | array | No | Filter by one or more model tags. A single or comma-separated string is accepted. |
| `title` | string | No | Filter models by title. |
| `sort_by` | string ("score" | "task_count" | "created_at") | No | Sort models by score, task_count, or created_at. |
| `licensed` | boolean | No | When true, discover only voices whose rights Fish Audio has secured; ignored by the provider for owned_only listings. |
| `author_id` | string | No | Filter public models by author ID; ignored when owned_only is true. |
| `languages` | array | No | Filter by one or more language codes such as en, es, or ja. |
| `page_size` | integer | No | Maximum models in this page (1-100). |
| `owned_only` | boolean | No | Return only models owned by the active workspace instead of public discovery models. |
| `next_cursor` | string | No | Continuation cursor returned by a previous call; omit for the first page. |
| `title_language` | array | No | Optional title-language filters. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Synthesize Speech

**Slug:** `FISH_AUDIO_SYNTHESIZE_SPEECH`

Generate downloadable speech synchronously using a selected Fish Audio model and voice IDs. Your own connection defaults to free S2.1; managed PAYG defaults to paid S2.1 Pro and uses paid models and public licensed voices.

**Instant:** Supported on the latest version.

**Instant pricing:** $15 per million UTF-8 input bytes for paid API speech models; free-model BYOK calls are excluded

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `text` | string | Yes | Text to synthesize. For multiple voices, use <&#124;speaker:0&#124;>, <&#124;speaker:1&#124;>, and matching indexes in voice_model_ids. |
| `model` | string ("s2.1-pro-free" | "s2.1-pro" | "s2-pro" | "s1") | No | Speech model. Omit for paid s2.1-pro on managed PAYG or s2.1-pro-free on your own connection. Preview models are excluded. |
| `speed` | number | No | Speaking-rate multiplier from 0.5 to 2.0. |
| `top_p` | number | No | Nucleus-sampling diversity from 0 to 1. |
| `format` | string ("mp3" | "wav" | "pcm" | "opus") | No | Output format: mp3, wav, pcm, or opus. |
| `volume` | number | No | Output volume adjustment in decibels. |
| `latency` | string ("normal" | "balanced" | "low") | No | Latency-quality tradeoff: normal, balanced, or low. |
| `temperature` | number | No | Expressiveness from 0 to 1; higher values are more varied. |
| `normalize_text` | boolean | No | Normalize English and Chinese text, including numbers, before synthesis. |
| `voice_model_ids` | array | Yes | One voice model ID for normal speech, or multiple IDs in speaker-tag order for dialogue. A single string is accepted as a one-item list. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |

### Transcribe Audio

**Slug:** `FISH_AUDIO_TRANSCRIBE_AUDIO`

Transcribe a previously uploaded audio file synchronously with Fish Audio. First upload through Composio files.upload in the SDK or the file-upload API; pass the returned file object, not a raw URL. Audio must be at most 64 MiB (a stricter platform limit may apply). Returns text, duration, optional segment timestamps and detected language. Long recordings may take several minutes.

**Instant:** Supported on the latest version.

**Instant pricing:** $0.36 per audio hour, rounded up to the next second per successful request

#### Input Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `audio` | object | Yes | Upload the recording first using Composio files.upload in the SDK or POST /api/v3.1/files/upload/request followed by uploading the bytes. Pass the returned file object here. Maximum 64 MiB; a raw URL or local filename alone is not accepted. Use audio you own or have permission to transcribe. |
| `model` | string ("transcribe-1" | "transcribe-1-pro") | No | Speech-to-text model; both models have the same published rate. |
| `language` | string | No | Optional language hint; Fish Audio still auto-detects the language. |
| `ignore_timestamps` | boolean | No | Whether to omit precise timestamps; false can increase latency for short recordings. |

#### Output

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `data` | string | Yes | Data from the action execution |
| `error` | string | No | Error if any occurred during the execution of the action |
| `successful` | boolean | Yes | Whether or not the action execution was successful or not |