---
title: "Voice Design"
method: POST
path: "/v1/voice-design"
tags: ["OpenAPI v1"]
---

# Voice Design

`POST /v1/voice-design`

## Headers

- `model` 'voice-design-1', required

## Request body

- VoiceDesignRequest — Request body for synchronous voice design generation. The endpoint returns generated voice candidates with base64-encoded audio.
  - `instruction` string, required — Voice design prompt. Must contain 1 to 2000 characters.
  - `reference_text` string, nullable — Optional text used as reference content for the generated voice.
  - `language` string, nullable — Optional BCP-47 language hint, such as `en`, `zh`, or `ja`.
  - `n` integer — Number of voice candidates to generate.
  - `speed` number — Speaking speed multiplier for candidate generation.
  - `num_step` integer — Number of diffusion steps used by the voice-design model.
  - `guidance_scale` number — Classifier-free guidance scale. Higher values follow the prompt more strongly.
  - `instruct_guidance_scale` number — Instruction guidance scale for prompt conditioning.
  - `seed` integer, nullable — Optional deterministic seed for candidate generation.

## Response `200`

Request fulfilled, document follows

- object
  - `candidates` VoiceDesignCandidate[], required — Generated voice candidates.
    - `id` string, required — Stable candidate identifier.
    - `index` integer, required — Candidate index in this response.
    - `audio_base64` string, required — Base64 encoded generated audio.
    - `sample_rate` integer, required — Audio sample rate in Hz.
    - `duration_ms` integer, required — Audio duration in milliseconds.
    - `text` string, nullable — Preview text associated with this generated voice, when available.
    - `instruct` string, nullable — Instruction text associated with this candidate, when available.
    - `language` string, nullable — Detected or requested candidate language, when available.

## Other responses

- `401` — No permission -- see authorization schemes
- `402` — No payment -- see charging schemes
- `422`

---

[API](https://skmtc.dev/fish/apis/fishaudio-openapi.md) · [All operations](https://skmtc.dev/fish/apis/fishaudio-openapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/fish/fishaudio-openapi/revisions/bca9c1115c42/schema)