> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kymaapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Voice Design (MiniMax)

> Generate a synthesized voice profile from a natural-language description. No reference recording needed. Returns a voice_id usable in /v1/audio/speech.

Synchronous endpoint. Describe a voice in plain English, get back a `voice_id` you can immediately use in [`/v1/audio/speech`](/api-reference/audio-speech) on any MiniMax voice model.

Use this when you don't have voice talent, you're prototyping a fictional character, or you want a brand-safe persona voice from scratch.

```bash theme={null}
curl -X POST https://kymaapi.com/v1/audio/voice-design \
  -H "Authorization: Bearer $KYMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Warm female narrator with a slight British accent, mid-30s, calm cadence",
    "gender": "female",
    "age_group": "young"
  }'
```

## Request

`application/json` body.

<ParamField body="description" type="string" required>
  Natural-language voice description. Max 1000 characters. Also accepts the alias `text`.
</ParamField>

<ParamField body="model" type="string" default="minimax-voice-design">
  Voice design SKU. Currently only `minimax-voice-design` is supported.
</ParamField>

<ParamField body="name" type="string">
  Optional human-readable label, max 64 chars.
</ParamField>

<ParamField body="preview_text" type="string">
  Optional sample text MiniMax will render in the new voice for an internal preview. Max 500 characters. Doesn't appear in the response — the audio bytes are not returned (you'd call `/v1/audio/speech` afterward to render).
</ParamField>

<ParamField body="gender" type="string">
  Optional hint: `male` or `female`.
</ParamField>

<ParamField body="age_group" type="string">
  Optional hint: `child`, `young`, `middle-aged`, or `elderly`.
</ParamField>

## Response

`200 OK` JSON. Same shape as [`/v1/audio/voice-clone`](/api-reference/audio-voice-clone).

```json theme={null}
{
  "voice_id": "kyma_a91f4d2e7c8b5301",
  "name": null,
  "model": "minimax-voice-design",
  "cost_usd": 4.20,
  "balance_usd": 45.80
}
```

## Pricing

Flat **\$4.20 per designed voice**. One-time charge — once designed, the `voice_id` is reusable in unlimited TTS calls.

Voice design costs \~2× voice clone because synthesizing timbre from text is strictly more compute-intensive than reproducing a captured voice.

## Ownership

Same gating as [voice clone](/api-reference/audio-voice-clone) — designed voice IDs are owned by the requesting user. Sharing the `voice_id` with another account is rejected with `403 voice_not_owned`.

## Errors

| Status | `error.code`               | When                                             |
| ------ | -------------------------- | ------------------------------------------------ |
| `400`  | `not_a_voice_design_model` | `model` is not a design SKU                      |
| `400`  | `description_too_long`     | description > 1000 chars                         |
| `400`  | `invalid_request`          | missing description                              |
| `402`  | `insufficient_credits`     | balance below \$4.20                             |
| `500`  | `ownership_write_failed`   | design succeeded but ownership row insert failed |
| `502`  | `provider_error`           | upstream MiniMax failure                         |

## See also

* [`POST /v1/audio/voice-clone`](/api-reference/audio-voice-clone) — clone from reference audio instead
* [`POST /v1/audio/speech`](/api-reference/audio-speech) — use the designed voice
* [Voice Design (model)](/models/minimax-voice-design) — service overview