> ## Documentation Index > Fetch the complete documentation index at: https://docs.tavus.io/llms.txt > Use this file to discover all available pages before exploring further. # Create Voice > Creates a voice from a sample of audio and returns immediately with `status: "started"`. **A new voice can take up to a few minutes to be ready.** Cloning runs after this call returns, so the voice cannot speak yet and a conversation that references it will not resolve a voice. Wait for `status` to reach `completed`, in one of two ways: - **Pass `callback_url`** and Tavus posts an `application.voice_status_changed` event once the status settles, carrying `voice_id`, `voice_name`, and `status`. On `error` it also carries `error_message`. The payload is a state snapshot, so a duplicate delivery is safe to apply twice. - **Poll [Get Voice](/api-reference/voices/get-voice)** if you would rather not receive a webhook. `completed` means the voice can speak. It stays `completed` while Tavus continues preparing the remaining languages, so you do not need to wait for those. Once ready, use the `voice_id` as `layers.tts.voice_id` on a PAL, or as a face's `default_voice_id`. Most teams create and audition voices in [PAL Maker](https://maker.tavus.io/dev/voices/create), where you can hear the result before shipping it. See [Voices](/sections/conversational-video-interface/voices). You must hold the rights to the voice in your training audio. For AI agents, use `https://docs.tavus.io/openapi.yaml` for the full HTTP API contract. ## OpenAPI ````yaml post /v2/voices openapi: 3.0.3 info: title: Tavus Developer API Collection version: 1.0.0 contact: {} servers: - url: https://tavusapi.com security: - apiKey: [] tags: - name: Videos - name: Faces - name: Voices - name: Conversations - name: Deployments - name: PALs - name: Tools - name: PAL Tools - name: Pronunciation Dictionaries - name: Replacements - name: Transcriptions - name: Documents paths: /v2/voices: post: tags: - Voices summary: Create Voice description: > Creates a voice from a sample of audio and returns immediately with `status: "started"`. **A new voice can take up to a few minutes to be ready.** Cloning runs after this call returns, so the voice cannot speak yet and a conversation that references it will not resolve a voice. Wait for `status` to reach `completed`, in one of two ways: - **Pass `callback_url`** and Tavus posts an `application.voice_status_changed` event once the status settles, carrying `voice_id`, `voice_name`, and `status`. On `error` it also carries `error_message`. The payload is a state snapshot, so a duplicate delivery is safe to apply twice. - **Poll [Get Voice](/api-reference/voices/get-voice)** if you would rather not receive a webhook. `completed` means the voice can speak. It stays `completed` while Tavus continues preparing the remaining languages, so you do not need to wait for those. Once ready, use the `voice_id` as `layers.tts.voice_id` on a PAL, or as a face's `default_voice_id`. Most teams create and audition voices in [PAL Maker](https://maker.tavus.io/dev/voices/create), where you can hear the result before shipping it. See [Voices](/sections/conversational-video-interface/voices). You must hold the rights to the voice in your training audio. operationId: createVoice requestBody: required: true content: application/json: schema: type: object required: - voice_name - training_audio_url properties: voice_name: type: string minLength: 1 maxLength: 255 description: A name for the voice. example: Ana training_audio_url: type: string maxLength: 2048 description: >- Publicly accessible link to the training audio. Accepts `.mp3`, `.wav`, `.m4a`, `.flac`, `.ogg`, `.oga`, `.webm`, `.mp4`, `.mov`, a video file is fine, the audio track is what is used. example: https://example.com/ana.mp3 description: type: string maxLength: 1000 description: Free-text note about the voice, returned on reads. example: Warm, unhurried, mid-Atlantic callback_url: type: string maxLength: 2048 description: >- URL to receive the `application.voice_status_changed` webhook when the voice reaches `completed` or `error`. example: https://example.com/webhooks/voices tags: type: array description: >- Up to 50 tags, 64 characters each. Filter on them with the `tag` query parameter on List Voices. maxItems: 50 items: type: string maxLength: 64 example: - support - en responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/Voice' '400': description: BAD REQUEST content: application/json: schema: type: object properties: error: type: string example: Voice creation requires a user-scoped API key '401': description: UNAUTHORIZED content: application/json: schema: type: object properties: message: type: string example: Invalid access token '429': description: TOO MANY REQUESTS security: - apiKey: [] components: schemas: Voice: type: object description: >- A Tavus Voice. Reference it by `voice_id`; Tavus picks the provider that is the best fit for the language(s) of the conversation. properties: voice_id: type: string description: >- Stable identifier. Use as `layers.tts.voice_id` on a PAL, or `default_voice_id` on a face. example: v0a1b2c3d4e5f voice_name: type: string example: Ana description: type: string nullable: true example: Warm, unhurried, mid-Atlantic voice_type: type: string description: '`user` for voices you created, `system` for the Tavus catalog.' enum: - user - system example: user status: type: string description: >- `started` while the voice is still being created, `completed` once it is ready to use, `error` if creation failed (see `error_message`). enum: - started - completed - error example: completed error_message: type: string description: Present only when `status` is `error`. tags: type: array items: type: string example: - support - en created_at: type: string format: date-time example: '2026-08-17T12:00:00.000000' securitySchemes: apiKey: type: apiKey in: header name: x-api-key ````