---
title: "Create or add a version to a voice design"
method: POST
path: "/voice_designs"
tags: ["Voice Designs"]
---

# Create or add a version to a voice design

`POST /voice_designs`

Creates a new voice design (version 1) when `voice_design_id` is omitted. When `voice_design_id` is provided, adds a new version to the existing design instead. A design can have at most 50 versions.

## Request body

- VoiceDesignRequest — Request body for creating a new voice design or adding a version to an existing one. Omit `voice_design_id` to create a new design; include it to add a new version.
  - `name` string — Name for the voice design. Required when creating a new design (`voice_design_id` is not provided); ignored when adding a version. Cannot be a UUID.
  - `voice_design_id` string, uuid — ID of an existing voice design to add a new version to. When provided, a new version is created instead of a new design.
  - `text` string, required — Sample text to synthesize for this voice design.
  - `prompt` string, required — Natural language description of the voice style, e.g. 'Speak in a warm, friendly tone with a slight British accent'.
  - `language` string — Language for synthesis. Supported values: Auto, Chinese, English, Japanese, Korean, German, French, Russian, Portuguese, Spanish, Italian. Defaults to Auto.
  - `temperature` number, float — Sampling temperature controlling randomness. Higher values produce more varied output. Default: 0.9.
  - `top_k` integer — Top-k sampling parameter — limits the token vocabulary considered at each step. Default: 50.
  - `top_p` number, float — Top-p (nucleus) sampling parameter — cumulative probability cutoff for token selection. Default: 1.0.
  - `repetition_penalty` number, float — Repetition penalty to reduce repeated patterns in generated audio. Default: 1.05.
  - `max_new_tokens` integer — Maximum number of tokens to generate. Default: 2048.
  - `provider` 'telnyx' | 'minimax' — Voice synthesis provider. `telnyx` uses the Qwen3TTS model; `minimax` uses the Minimax speech models. Case-insensitive. Defaults to `telnyx`.

## Response `201`

Voice design created or new version added successfully.

- VoiceDesignResponse — Response envelope for a single voice design with full version detail.
  - `data` VoiceDesignData — A voice design object with full version detail.
    - `record_type` 'voice_design' — Identifies the resource type.
    - `id` string, uuid — Unique identifier for the voice design.
    - `name` string — Name of the voice design.
    - `version` integer — Version number of this voice design.
    - `text` string — Sample text used to synthesize this version.
    - `prompt` string — Natural language prompt used to define the voice style for this version.
    - `voice_sample_size` integer — Size of the voice sample audio in bytes.
    - `version_created_at` string, date-time — Timestamp when this specific version was created.
    - `created_at` string, date-time — Timestamp when the voice design was first created.
    - `updated_at` string, date-time — Timestamp when the voice design was last updated.
    - `provider` 'telnyx' | 'minimax' | 'null', nullable — Voice synthesis provider used for this design.
    - `provider_supported_models` string[] — List of TTS model identifiers supported by this design's provider (e.g. `Qwen3TTS`, `speech-02-turbo`).
    - `provider_voice_id` string, nullable — Provider-specific voice identifier. For Telnyx designs this is the design version ID; for Minimax it is the Minimax-assigned voice ID.

## Other responses

- `401` — Unauthorized — missing or invalid bearer token.
- `404` — Voice design not found — the specified `voice_design_id` does not exist.
- `409` — Conflict — the voice design has reached the maximum of 50 versions.
- `422` — Unprocessable entity — validation error in the request body.
- `502` — Bad gateway — upstream voice synthesis service is unavailable.

---

[API](https://skmtc.net/team-telnyx/apis/telnyx-api.md) · [All operations](https://skmtc.net/team-telnyx/apis/telnyx-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/team-telnyx/telnyx-api/versions/e32d46c5945b/schema)