Use the fish.audio-style POST /v1/tts contract with Fish Audio API keys for clients such as RikkaHub.

Fish Audio Compatible TTS

Use this endpoint when a client hard-codes the fish.audio POST /v1/tts request shape. It maps that payload into the Fish Audio Open TTS pipeline while keeping API key auth, quota, and billing on your Fish Audio account.

For a native Open API integration, prefer Sync HTTP. For OpenAI POST /v1/audio/speech clients, use OpenAI-Compatible TTS.

Endpoint

POST /v1/tts
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
model: s2.1-pro

Full URL:

https://fishaudio.org/v1/tts

If the third-party app asks for a Fish Audio API base such as https://api.fish.audio, set it to https://fishaudio.org and leave the path as /v1/tts.

Keep the API key in the client's protected credential field. Create a dedicated key for each app so you can monitor or revoke it independently.

Request

{
  "text": "Hello from Fish Audio.",
  "reference_id": "00a1b221-6137-4b73-ad62-b0cbce134167",
  "format": "mp3",
  "temperature": 0.7,
  "top_p": 0.7,
  "normalize": true,
  "prosody": {
    "speed": 1
  }
}

Field / header	Type	Required	Notes
`model` header	string	No	fish.audio engine label such as `s2.1-pro`, `s2.1-pro-flash`, or `s2-pro`
`text`	string	Yes	Text to synthesize
`reference_id`	string	Yes	Fish Audio Voice ID; the server does not silently pick a default voice
`format`	string	No	`mp3`, `wav`, or `pcm`; unsupported values such as `opus` fall back to `mp3`
`prosody.speed`	number	No	Speaking speed from `0.5` to `2`; `speed` at the top level is also accepted
`temperature`	number	No	Mapped to Fish Audio stability (`0.5`–`1.5`)
`top_p`	number	No	Mapped to Fish Audio similarity (`0.5`–`1.5`)
`normalize`	boolean	No	Mapped to text normalization
`chunk_length`	number	No	Accepted for client compatibility and ignored
`latency`	string	No	Accepted for client compatibility and ignored

Model header mapping

`model` header value	Fish Audio engine model id
`s2.1-pro`	`fishaudio-s21pro`
`s2.1-pro-free`	`fishaudio-s21pro-free`
`s2.1-flash`	`fishaudio-s21-flash`
`s2.1-pro-flash`	`fishaudio-s21pro-flash`
`s2-pro`	`fishaudio-s2pro`
`s1` / `s1-mini`	`fishaudio-s1`
`speech-1.5` / `1.6`	`fishaudio-s1`

Unknown header values are ignored and the server default engine applies. You can also send a native engine id such as fishaudio-s21pro-flash in the header.

Get Voice IDs from GET /api/open/v1/voices. For a quick connection test, use the public system voice 00a1b221-6137-4b73-ad62-b0cbce134167.

Response

A successful request returns binary audio:

HTTP/1.1 200 OK
Content-Type: audio/mpeg
X-OpenAPI-Quota-Remaining: 987988
X-OpenAPI-Credits-Used: 12

<binary audio data>

Errors are JSON and share authentication, quota, and generation behavior with Sync HTTP.

curl Example

curl -X POST "https://fishaudio.org/v1/tts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "model: s2.1-pro" \
  -d '{
    "text": "Hello from Fish Audio.",
    "reference_id": "00a1b221-6137-4b73-ad62-b0cbce134167",
    "format": "mp3",
    "prosody": { "speed": 1 }
  }' \
  --output speech.mp3

Connect RikkaHub

For API key, Base URL, model, and voice setup in RikkaHub, follow the dedicated RikkaHub setup guide.

Errors

Status	Meaning	Action
`400`	Invalid text, missing `reference_id`, or bad JSON	Correct the request before retrying
`401`	API key is missing or invalid	Check or replace the integration key
`402`	API quota is insufficient	Add quota before generating more audio
`429`	Request rate limit exceeded	Retry with exponential backoff
`500`	TTS generation failed	Retry only with duplicate-charge awareness

Fish Audio Compatible TTS

On this page