Fish Audio Voice Design API - Text-to-Voice Preview

Generate candidate voices from a natural-language prompt. Synchronous endpoint that returns base64-encoded WAV audio.

Generate short voice candidates from a natural-language prompt. Use it to explore a voice direction before a longer TTS workflow or creating a persistent voice model.

Synchronous endpoint: returns candidates immediately—no task polling. Accepts application/json only; MessagePack, multipart, and inline reference audio are not supported. Candidate audio is WAV bytes encoded as base64. Billing is once per successful generation request, not per candidate.

Base URL

https://api.autorouter.top — Production

Authentication

BearerAuth: http (bearer) Authenticate using a Bearer Token. Format: Authorization: Bearer sk-xxxxxx

Endpoints

POST `/fishaudio/v1/voice-design`

Create Voice Design Request

Send a voice description prompt and receive one or more candidate voices with preview audio.

The model: voice-design-1 header is required. Extra request fields are rejected.

Headers

Name	Type	Required	Description
`Authorization`	string	Yes	Request authentication. Format: `Bearer sk-xxxxxx`
`Content-Type`	string	Yes	Must be `application/json`
`model`	string	Yes	Voice-design model. Must be `voice-design-1`

Request Body

Content-Type: application/json

Example:

{
  "instruction": "Warm, confident studio narrator with a natural tone",
  "reference_text": "Welcome to Fish Audio.",
  "language": "en",
  "n": 2,
  "speed": 1,
  "num_step": 32,
  "guidance_scale": 2,
  "instruct_guidance_scale": 0,
  "seed": 42
}

Properties:

Name	Type	Required	Default	Description
`instruction`	string	Yes	—	Voice design prompt: voice, age, delivery, tone, accent, pacing, and context. 1 to 2000 characters
`reference_text`	string \| null	No	`null`	Optional preview text so candidates read the same line for comparison. Up to 150 characters
`language`	string \| null	No	`null`	Optional language hint such as `en`, `zh`, or `ja`
`n`	integer	No	`2`	Number of candidates to generate. Range `[1, 4]`
`speed`	number	No	`1.0`	Speaking speed multiplier. Must be greater than `0` and at most `3`
`num_step`	integer	No	`32`	Diffusion steps. Range `[1, 128]`
`guidance_scale`	number	No	`2.0`	Classifier-free guidance. Higher values follow the prompt more strongly. Must be `>= 0`
`instruct_guidance_scale`	number	No	`0.0`	Prompt conditioning guidance. Must be `>= 0`
`seed`	integer \| null	No	`null`	Optional deterministic seed for candidate generation

instructionstring(required)

Primary voice design prompt. Describe the desired voice in natural language, for example:

Age and gender lean
Delivery and tone (warm, confident, bright)
Accent, diction, and pacing
Context (studio narration, product update)

Length must be 1 to 2000 characters.

reference_textstring | null(optional)

Preview text. When provided, candidates read that text so you can compare voices on the same line.

Keep it short
Maximum 150 characters
If omitted, candidates are still generated; preview content is model-determined

Responses

200: Generation succeeded

Content-Type: application/json

401: Unauthorized

Content-Type: application/json

402: Insufficient balance

Content-Type: application/json

503: Service overloaded

Content-Type: application/json

Request examples

curl --request POST "https://api.autorouter.top/fishaudio/v1/voice-design" \
  --header "Authorization: Bearer sk-xxxxxx" \
  --header "Content-Type: application/json" \
  --header "model: voice-design-1" \
  --data '{
  "instruction": "Warm, confident studio narrator with a natural tone",
  "reference_text": "Welcome to Fish Audio.",
  "language": "en",
  "n": 2,
  "speed": 1,
  "num_step": 32,
  "guidance_scale": 2,
  "instruct_guidance_scale": 0,
  "seed": 42
}'

Response examples

{
  "candidates": [
    {
      "id": "candidate-id",
      "index": 0,
      "audio_base64": "UklGRg...",
      "sample_rate": 44100,
      "duration_ms": 3100,
      "text": "Welcome to Fish Audio.",
      "language": "en"
    }
  ]
}

Response fields:

Name	Type	Description
`candidates`	object[]	Generated voice candidates
`candidates[].id`	string	Stable candidate identifier for this response
`candidates[].index`	integer	Candidate index to preserve model order, starting at `0`
`candidates[].audio_base64`	string	Base64-encoded WAV audio; decode and write to a file
`candidates[].sample_rate`	integer	Sample rate in Hz
`candidates[].duration_ms`	integer	Audio duration in milliseconds
`candidates[].text`	string \| null	Preview text for this candidate, when available
`candidates[].instruct`	string \| null	Instruction text for this candidate, when available
`candidates[].language`	string \| null	Detected or requested language, when available

The endpoint is stateless: it does not create batches, samples, voice models, or presigned URLs. Use decoded audio for preview; to persist a reusable voice, call Create Model.

Error handling

HTTP 400 parameter errors (blocked before upstream; not billed)

AutoRouter validates required fields before forwarding upstream:

Scenario	Response
Missing `instruction`	`{"code":"InvalidParameter","message":"...","request_id":"..."}`
Missing or invalid `model` header	`{"code":"InvalidParameter","message":"...","request_id":"..."}`
MessagePack / multipart / extra fields	Request rejected

Authentication errors, validation errors, insufficient credit, concurrency limits, upstream errors, and empty candidate responses are not billed.

HTTP 401 / 403 authentication errors

401 Unauthorized: Invalid or expired API key
403 Forbidden: API key is not allowed to access this model (check the token model allowlist)

HTTP 402 insufficient balance

Returns insufficient user quota. Top up in the AutoRouter console.

HTTP 503 service overloaded

The server is under high load and cannot process the request. Retry later.

Voice Design

instructionstring(required)

reference_textstring | null(optional)

On this page