# Design Voice
Purpose: API operation reference for `POST /v1/audio/voices/design`.
Last updated: 2026-09-15

## Endpoint

```txt
POST /v1/audio/voices/design
```

## Description

Send a description and, optionally, the text the previews should speak. Each preview comes back with base64 audio and a `design_id`; keep the one you want with `POST /v1/audio/voices`. A preview is guaranteed savable until `expires_at`.

Synthesize previews of a voice described in words, each savable by its design id.

Raises:
    GatewayError: 400 when the model designs no voices or more previews were asked for than the
        deployment synthesizes, 404 when voice design is unavailable, 502 when the model returned no audio.

## Request body

Content type: `application/json`

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| `model` | Yes | `string` | model name to route to (may be an alias; rejected if blank) |
| `description` | Yes | `string` | natural-language description of the voice to design |
| `input` | No | `string \| null` | text the previews speak; omitted speaks the model's own script, which is sized to save |
| `n` | No | `integer` | how many previews to synthesize; capped by the deployment |

## Success response

Status: `200`
Content type: `application/json`

| Field | Required | Type | Description |
| --- | --- | --- | --- |
| `object` | No | `"list"` | envelope type discriminator; always 'list' |
| `data` | Yes | `array<VoiceDesignPreview>` | the previews, in synthesis order |
| `input` | Yes | `string` | the text every preview speaks |

## Error responses

| Status | Description |
| --- | --- |
| `400` | The request was malformed, or a field value was invalid. |
| `401` | Missing, invalid, or expired credentials. |
| `402` | The account is out of credit. |
| `403` | Authenticated, but not a member of the requested organization. |
| `404` | The requested model does not exist or is not available. |
| `429` | Rate limit exceeded. |
| `502` | The model backend answered with something the gateway could not serve. |
| `503` | Authentication, rate limiting, or a backing service is temporarily unavailable. |

## Related links

- [Markdown reference](https://sprag.ai/docs/api/audio/voices/design.md)
- [OpenAPI spec](https://sprag.ai/openapi.json)
- [Authentication](https://sprag.ai/docs/authentication.md)
- [Errors](https://sprag.ai/docs/errors.md)