# Generate designed speech

- **Method:** `POST`
- **Path:** `/api/v1/generation/design`
- **Operation ID:** `start_design_api_v1_generation_design_post`
- **Tags:** Design

Generate speech using a natural language voice description.

Describe the desired voice in `instruct_text` (e.g. 'a deep male voice
with an American accent, speaking confidently'). The model creates a
new voice matching the description each time — results vary between calls.
To reuse a designed voice, save it via `POST /api/v1/voices` and use
`POST /api/v1/generation/design/saved` instead.

## Effective servers

- `http://127.0.0.1:8100`

  Voice Creator Pro on this computer

## Query parameters

- **`sync`**: `boolean`, default: `false`

  Wait for generation to complete and return audio directly

## Request body

**Required:** `true`

**Content type:** `application/json`

schema: `DesignRequest`

- **`instruct_text` (required)**: `string`

  Natural language description of the voice
- **`generation_params`**: `object | null`, schema: `GenerationParamsModel`

  Advanced sampling parameters
  - **`seed`**: `integer | null`

    Random seed for reproducible generation
- **`language`**: `string`, default: `"Auto"`

  Target language. Query GET /api/v1/models/active for supported languages per variant.
- **`model_family`**: `string | null`

  TTS model to use. If omitted, uses the currently configured model.
- **`target_text`**: `string`, default: `""`

  Text to generate speech for. Required for most models; for Dramabox, the instruct\_text prompt contains both stage directions and spoken text.
- **`voice_reference_path`**: `string | null`

  Path to a reference audio file for voice conditioning (Dramabox only).

**Example:**

```json
{
  "instruct_text": "A warm female voice with a British accent, speaking at a moderate pace",
  "target_text": "Welcome to our application.",
  "language": "English",
  "generation_params": {
    "seed": 42,
    "additionalProperty": "anything"
  },
  "model_family": "qwen3-tts",
  "voice_reference_path": ""
}
```

## Responses

### 200 Generation started (async) or completed result (sync).

**Content type:** `application/json`

**Any of:**

- `object`, schema: `GenerationStartedResponse`
  - **`queue_position` (required)**: `integer`

    Position in the generation queue (0 = next to run)
  - **`started` (required)**: `boolean`

    Whether the generation job was enqueued
- `object`, schema: `GenerationResult`
  - **`status` (required)**: `string`

    Human-readable status message
  - **`success` (required)**: `boolean`

    Whether generation completed successfully
  - **`audio_base64`**: `string | null`

    Base64-encoded audio output (WAV format)
  - **`error_code`**: `string | null`

    Machine-readable failure code when success is false
  - **`error_detail`**: `string | null`

    Extra detail for the failure code

**One of:**

- *Schema `GenerationStartedResponse` is shown above.*
- *Schema `GenerationResult` is shown above.*

**Example:**

```json
{
  "started": true,
  "queue_position": 0
}
```

### 422 Validation Error

**Content type:** `application/json`

schema: `HTTPValidationError`

- **`detail`**: `array`

  **Items:**

  schema: `ValidationError`
  - **`loc` (required)**: `array of (string | integer)`
  - **`msg` (required)**: `string`
  - **`type` (required)**: `string`
  - **`ctx`**: `object`
  - **`input`**: `any`

**Example:**

```json
{
  "detail": [
    {
      "loc": [
        ""
      ],
      "msg": "",
      "type": "",
      "input": null,
      "ctx": {}
    }
  ]
}
```

### 504 Sync generation timed out (600s limit).

## Schemas

- `DesignRequest` — shown above.
- `GenerationParamsModel` — shown above.
- `GenerationResult` — shown above.
- `GenerationStartedResponse` — shown above.
- `HTTPValidationError` — shown above.
- `ValidationError` — shown above.