Fish Audio S2.1 Pro API: Pricing, Documentation

Authentication

All requests require an API key passed via header.

Webhook (Optional)

Instead of polling, you can receive a Webhook callback when the request reaches a terminal state. Provide a Webhook URL via header on the submit request.

Example: enable Webhook

curl -X POST 'https://gateway.pixazo.ai/fish-audio-drama-3/v1/text-to-speech' \
  -H 'Content-Type: application/json' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
  -H 'X-Webhook-URL: https://your-server.com/webhook' \
  --data-raw '{"text": "[tired, trying to sound upbeat] I told you this would happen. [sigh] <whisper>But I am glad you came back.</whisper>", "reference_id": "f3a2b90078d54a65af4b95f63bc7798e", "format": "mp3"}'

Callback Payload (success)

{
  "request_id": "fish-audio-drama-3_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "fish-audio-drama-3",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/fish-audio-drama-3_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.mp3"
    ],
    "media_type": "audio/mpeg"
  },
  "created_at": "2026-10-14T16:40:58.264Z",
  "updated_at": "2026-10-14 16:42:31",
  "completed_at": "2026-10-14 16:42:31"
}

Failure callback shape

{
  "request_id": "fish-audio-drama-3_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "fish-audio-drama-3",
  "error": "Description of the failure",
  "output": null,
  "created_at": "2026-10-14T16:40:58.264Z",
  "updated_at": "2026-10-14 16:42:31",
  "completed_at": "2026-10-14 16:42:31"
}

Delivery semantics

• terminal mode: one Webhook callback when the request is COMPLETED or ERROR.
• sync mode: a Webhook callback on each status change.
• Callbacks are idempotent on request_id — de-duplicate on it.
• Respond 200 within a few seconds; the Webhook endpoint must be HTTPS.

Request Parameters

How text is measured

Billed on the UTF-8 bytes of text, including every direction, tag and speaker marker, rounded up to whole 1,000-byte blocks (minimum one). Most non-Latin scripts use 2–4 bytes per character. The rate is in the pricing panel on this page.

Billing is measured in UTF-8 bytes, not characters. For English and other Latin-script text the two are the same — one character is one byte — but characters outside the ASCII range take more than one byte. Directions and tags are text too: [sigh] adds 6 bytes and <|speaker:0|> adds 13.

The 5,000-character limit on text counts characters, not bytes — and characters outside the Basic Multilingual Plane (most emoji) count as two toward it.

Parameters not supported

Worth reading if you are porting existing Fish Audio code — some parameters are rejected outright, some fail once the request is processed, and others are accepted and then ignored.

Rejected with 400

Checked when you submit: the request is rejected before it is queued.

Accepted, then the request fails

These values pass the submit check, so the submit returns 202, but they are validated while the request is processed: the request fails, and the status endpoint (or Webhook) reports status: "ERROR" with an error message that names the problem.

Accepted but ignored

These are silently dropped — the request still returns 202, but the value has no effect on the generated audio. Only the parameters listed in the table above are forwarded.

Voice, Directions & Dialogue

Choosing a voice

reference_id accepts two forms. Omit it entirely to use the provider default voice. A voice that fits the role makes the biggest difference to how well a performance lands.

Voice ids are 32-character hexadecimal strings. Browse the Fish Audio voice library at fish.audio — the id is the last path segment of fish.audio/m/<id>. Three public voices to start with:

Directions and tags

Directions are plain text inside text, and you can mix them freely in the same line. Bracketed directions are performance notes, not words to speak. There is no fixed list: describe tone, pacing and character in your own words.

• Paired tags are written exactly as listed; in this API the speed tags are <fast> and <slow>.
• Language tags are experimental: they are not guaranteed for every language or voice, and the model may switch language on its own when the text is already multilingual. Wrap only the words that change language; a voice whose speaker is fluent in both languages works best.
• Directions, tags and speaker markers count toward the 5,000-character limit and toward the billed size (see How text is measured above).

Multi-Speaker Dialogue

Pass an array of voice ids and start each turn in text with a <|speaker:N|> tag. The index in the tag selects the voice at that position in the array — <|speaker:0|> uses the first id, <|speaker:1|> the second, and so on. Directions and paired tags work inside each turn. This scene uses two voices:

{
  "text": "<|speaker:0|>[calm, measured storyteller voice] The ship had been silent for three days.<|speaker:1|>[low, gravelly, tired but in control] Status report.<|speaker:0|>[barely above a whisper] Nobody answered.<|speaker:1|>[slow, dangerously quiet] Then we wait. <emphasis>Together.</emphasis>",
  "reference_id": [
    "c70cfb98867a4bfb9ae20d2401257b92",
    "bf322df2096a46f18c579d0baa36f41d"
  ],
  "format": "mp3"
}

• Text before any tag is spoken by the first voice in the array.
• Supply one id per speaker index you use, up to 8 ids.
• With two or more ids and no <|speaker:N|> tag in text, the request fails, because every line would otherwise be rendered in the first voice.
• For a single speaker, pass the id as a plain string — tags are not needed.

Request Headers

Response Handling

Problems that can only be detected while the request is processed (“Accepted, then the request fails” above) are not a 400: they are reported through the status endpoint or Webhook with status: "ERROR".

Error Responses

A 400 names every rejected parameter in violations:

{
  "error": "Invalid request parameters",
  "message": "'format' must be one of: \"mp3\", \"wav\" (got \"opus\")",
  "violations": [
    "'format' must be one of: \"mp3\", \"wav\" (got \"opus\")"
  ]
}

A request that fails after it was queued is reported via the status endpoint (or Webhook) with status: "ERROR" and an error message — for example when reference_id does not name an existing voice.

Retrieving Results

Poll the status endpoint with the request_id from the submit response until status is COMPLETED or ERROR, then download the audio from output.media_url.

curl 'https://gateway.pixazo.ai/v2/requests/status/fish-audio-drama-3_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY'

Completed response

Captured from a real Drama 3 request at launch; the request id is masked.

{
  "request_id": "fish-audio-drama-3_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "fish-audio-drama-3",
  "error": null,
  "output": {
    "media_url": [
      "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/fish-audio-drama-3_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/output.mp3"
    ],
    "media_type": "audio/mpeg"
  },
  "created_at": "2026-10-14T16:40:58.264Z",
  "updated_at": "2026-10-14 16:42:31",
  "completed_at": "2026-10-14 16:42:31"
}

Response Fields

Status Values & Flow

QUEUED → PROCESSING → COMPLETED (success) or ERROR (failure). Treat any status other than QUEUED, PROCESSING or COMPLETED as a failure.

• Save the request_id from the 202 response.
• Poll the status endpoint every few seconds, or use a Webhook instead.
• When status is COMPLETED, download the audio from output.media_url.

Authentication

All requests require an API key passed via header.

Webhook (Optional)

Instead of polling, you can receive a Webhook callback when the request reaches a terminal state. Provide a Webhook URL via header on the submit request.

Example: enable Webhook

curl -X POST 'https://gateway.pixazo.ai/fish-audio-s2-1-pro/v1/text-to-speech' \
  -H 'Content-Type: application/json' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
  -H 'X-Webhook-URL: https://your-server.com/webhook' \
  --data-raw '{"text": "[whispering] When you are building something new, there is this mix of wonder and fear. [chuckling] But that is what makes it worth building.", "reference_id": "933563129e564b19a115bedd57b7406a", "format": "mp3", "mp3_bitrate": 128}'

Callback Payload (success)

{
  "request_id": "fish-audio-s2-1-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "fish-audio-s2-1-pro",
  "output": {
    "media_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/fish-audio/1785407392754-66f0f615.mp3",
    "media_type": "audio/mpeg"
  },
  "created_at": "2026-07-30T10:29:44.313Z",
  "completed_at": "2026-07-30T10:29:53.391Z"
}

Failure callback shape

{
  "request_id": "fish-audio-s2-1-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "fish-audio-s2-1-pro",
  "error": "Description of the failure"
}

Delivery semantics

• terminal mode: one Webhook callback when the request is COMPLETED or ERROR.
• sync mode: a Webhook callback on each status change.
• Callbacks are idempotent on request_id — de-duplicate on it.
• Respond 200 within a few seconds; the Webhook endpoint must be HTTPS.

Request Parameters

Parameters not supported

Worth reading if you are porting existing Fish Audio code — some parameters are rejected outright, while others are accepted and then ignored.

Rejected with 400

Accepted but ignored

These are silently dropped — the request still returns 202, but the value has no effect on the generated audio. Only the parameters listed in the table above are forwarded.

Voice & Emotion Control

Choosing a voice

reference_id accepts two forms. Omit it entirely to use the provider default voice.

Voice ids are 32-character hexadecimal strings. Browse the Fish Audio voice library at fish.audio — the id is the last path segment of fish.audio/m/<id>.

Multi-Speaker Dialogue

Pass an array of voice ids and mark speaker changes in text with <|speaker:N|> tags. The index in the tag selects the voice at that position in the array — <|speaker:0|> uses the first id, <|speaker:1|> the second, and so on.

{
  "text": "<|speaker:0|>Good morning!<|speaker:1|>Good morning! How are you?<|speaker:0|>I am great, thanks for asking!",
  "reference_id": [
    "933563129e564b19a115bedd57b7406a",
    "d13f84b987ad4f22b56d2b47f4eb838e"
  ],
  "format": "mp3"
}

• Text before any tag is spoken by the first voice in the array.
• A tag index with no matching array entry is not valid — supply one id per speaker index you use.
• Passing two or more ids without any <|speaker:N|> tag returns 400, because every line would otherwise be rendered in the first voice.
• For a single speaker, pass the id as a plain string — tags are not needed.

Emotion & effect markers

Place markers inline in text using square brackets. They are interpreted as performance direction and are not spoken aloud.

Markers are not restricted to this list — any descriptive phrase works, for example [whispers sweetly] or [laughing nervously]. Use at most three emotion markers per sentence, and place sentence-level direction at the start of the sentence. Markers add no character cost and no latency.

Request Headers

Response Handling

Error Responses

{
  "error": "Insufficient Balance",
  "message": "Your wallet does not have enough balance."
}

A failed generation is reported via the status endpoint (or Webhook) with status: "ERROR" and an error message — for example Reference not found when reference_id does not name an existing voice.

Retrieving Results

Poll the status endpoint with the request_id from the submit response until status is COMPLETED (or FAILED/ERROR).

curl 'https://gateway.pixazo.ai/v2/requests/status/fish-audio-s2-1-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY'

Completed response

{
  "request_id": "fish-audio-s2-1-pro_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "fish-audio-s2-1-pro",
  "output": {
    "media_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/fish-audio/1785407392754-66f0f615.mp3",
    "media_type": "audio/mpeg"
  },
  "created_at": "2026-07-30T10:29:44.313Z",
  "completed_at": "2026-07-30T10:29:53.391Z"
}

Response Fields

Status Values & Flow

QUEUED → PROCESSING → COMPLETED (success) or FAILED/ERROR (failure).

Pricing

Billed at $0.02 per 1,000 UTF-8 bytes of input text, rounded up to the next whole 1,000. Every request bills at least one block.

Billing is measured in UTF-8 bytes, not characters. For English and other Latin-script text the two are the same — one character is one byte — but characters outside the ASCII range take more than one byte, so the same character count costs more in those languages.

The 5,000-character limit on text counts characters, not bytes — and characters outside the Basic Multilingual Plane (most emoji) count as two toward it. The most expensive possible request is therefore 5,000 three-byte characters, such as Chinese or Japanese: 15,000 bytes, or $0.30. Text made of 4-byte characters hits the limit at 2,500 characters, or $0.20.

Authentication

All requests require an API key passed via header.

Webhook (Optional)

Instead of polling, you can receive a Webhook callback when the request reaches a terminal state. Provide a Webhook URL via header on the submit request.

Example: enable Webhook

curl -X POST 'https://gateway.pixazo.ai/fish-audio-speech-to-text/v1/speech-to-text' \
  -H 'Content-Type: application/json' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY' \
  -H 'X-Webhook-URL: https://your-server.com/webhook' \
  --data-raw '{"audio_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/doc-assets/audio/speech-17s.mp3", "language": "en", "ignore_timestamps": false}'

Callback Payload (success)

{
  "request_id": "fish-audio-speech-to-text_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "fish-audio-speech-to-text",
  "output": {
    "media_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.json",
    "media_type": "application/json"
  },
  "created_at": "2026-07-30T14:49:39.898Z",
  "completed_at": "2026-07-30T14:49:59.000Z"
}

Failure callback shape

{
  "request_id": "fish-audio-speech-to-text_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "ERROR",
  "model_id": "fish-audio-speech-to-text",
  "error": "Description of the failure"
}

Delivery semantics

• terminal mode: one Webhook callback when the request is COMPLETED or ERROR.
• sync mode: a Webhook callback on each status change.
• Callbacks are idempotent on request_id — de-duplicate on it.
• Respond 200 within a few seconds; the Webhook endpoint must be HTTPS.

Request Parameters

Audio limits

• The audio file must be at most 25 MB. Larger files are rejected before transcription starts.
• audio_url must be an http or https URL and must be publicly reachable.
• There is no fixed duration limit; cost scales with the length of the audio (see Pricing).

Transcript Format

The completed request returns output.media_url, a JSON file containing the transcript. Fetch that URL to read the result.

{
  "text": "Strong consistency test. This should complete in a few seconds, not sixty.",
  "language": "English",
  "language_code": "en",
  "duration": 5.8253125,
  "segments": [
    {
      "text": "Strong",
      "start": 0,
      "end": 0.56
    },
    {
      "text": "consistency",
      "start": 0.56,
      "end": 1.12
    }
  ]
}

Request Headers

Response Handling

An unreachable audio_url, an oversized file, or a file that is not recognisable audio is reported through the status endpoint as status: "ERROR", not as a synchronous error. Failed requests are not billed.

Retrieving Results

Poll the status endpoint with the request_id from the submit response until status is COMPLETED (or FAILED/ERROR), then fetch output.media_url for the transcript.

curl 'https://gateway.pixazo.ai/v2/requests/status/fish-audio-speech-to-text_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
  -H 'Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY'

Completed response

{
  "request_id": "fish-audio-speech-to-text_019dxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "model_id": "fish-audio-speech-to-text",
  "output": {
    "media_url": "https://pub-582b7213209642b9b995c96c95a30381.r2.dev/v1/{request_id}/output.json",
    "media_type": "application/json"
  },
  "created_at": "2026-07-30T14:49:39.898Z",
  "completed_at": "2026-07-30T14:49:59.000Z"
}

Response Fields

Status Values & Flow

QUEUED → PROCESSING → COMPLETED (success) or FAILED/ERROR (failure).

Pricing

Billed at $0.006 per minute of audio ($0.36 per audio hour), rounded up to the next whole minute. Billing is based on the length of the audio you submit, not on the size of the transcript.

A hold is placed when the request is submitted, because the audio length is not known until transcription completes. The hold is reduced to the real cost once the duration is known, and released in full if the request fails.