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-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.