> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argil.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a voice from audio
> Creates a custom voice by cloning from an audio file.
## Overview
Creates a custom voice by cloning from an uploaded audio file. The voice is available immediately after creation.
## Settings by Model
Settings vary depending on the model you choose. The `modelId` determines which provider (ElevenLabs or Minimax) handles TTS at generation time.
**Model:** `eleven_v3`
**Settings:**
* `voiceStability` (0-1, default: 0.5) — Higher = more consistent, lower = more expressive
* `voiceSimilarity` (0-1, default: 0.5) — Clarity and similarity to the original voice
* `voiceStyle` (0-1, default: 0.0) — Style exaggeration. Higher values are more expressive but slower.
* `voiceSpeed` (0.7-1.2, default: 1.0) — Playback speed
Speaker Boost is not available for this model.
**Models:** `eleven_multilingual_v2` (recommended), `eleven_multilingual_v1`, `eleven_monolingual_v1`, `eleven_turbo_v2`, `eleven_turbo_v2_5`, `eleven_flash_v2_5`
**Settings:**
* `voiceStability` (0-1, default: 0.8) — Higher = more consistent, lower = more expressive
* `voiceSimilarity` (0-1, default: 0.5) — Clarity and similarity to the original voice
* `voiceStyle` (0-1, default: 0.0) — Style exaggeration. Higher values are more expressive but slower.
* `voiceSpeed` (0.7-1.2, default: 1.0) — Playback speed
* `speakerBoost` (boolean, default: true) — Enhances speaker similarity
**Models:** `speech-2.8-hd` (recommended), `speech-2.8-turbo`, `speech-2.6-hd`, `speech-2.6-turbo`, `speech-2.5-hd-preview`, `speech-2.5-turbo-preview`, `speech-02-hd`, `speech-02-turbo`
**Settings:**
* `voiceSpeed` (0.7-1.2, default: 1.0) — Playback speed
* `languageBoost` (enum, default: "auto") — Boost a specific language for better pronunciation
* `emotion` (enum, default: "auto") — Voice emotion: `happy`, `sad`, `angry`, `fearful`, `disgusted`, `surprised`, `neutral`
## Default Model
If `modelId` is omitted, the default is `speech-2.5-hd-preview` (Minimax).
## Audio Requirements
* Must be accessible via HTTPS URL
* Duration must be between 30 seconds and 4 minutes
* Supported formats: MP3, WAV, M4A
## Voice Status
The created voice is returned with status `IDLE`, meaning it is ready to be used in video generation immediately.
## OpenAPI
````yaml post /voices
openapi: 3.0.1
info:
title: Argil API
description: API for AI clone video generation
version: 1.0.0
license:
name: MIT
servers:
- url: https://api.argil.ai/v1
security:
- ApiKeyAuth: []
paths:
/voices:
post:
summary: Create a voice from audio
description: |
Creates a custom voice by cloning from an audio file.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/VoiceCreateArgs'
examples:
minimax_default:
summary: Create voice with default Minimax model
value:
name: My Custom Voice
audioUrl: https://example.com/my-audio.mp3
minimax_with_settings:
summary: Create voice with Minimax settings
value:
name: My Custom Voice
audioUrl: https://example.com/my-audio.mp3
modelId: speech-2.8-hd
settings:
voiceSpeed: 1.1
languageBoost: English
emotion: happy
language: ENGLISH
gender: MALE
elevenlabs:
summary: Create voice with ElevenLabs model
value:
name: My Custom Voice
audioUrl: https://example.com/my-audio.mp3
modelId: eleven_multilingual_v2
settings:
voiceStability: 0.8
voiceSimilarity: 0.5
voiceStyle: 0
voiceSpeed: 1
speakerBoost: true
elevenlabs_v3:
summary: Create voice with ElevenLabs V3 model
value:
name: My Custom Voice
audioUrl: https://example.com/my-audio.mp3
modelId: eleven_v3
settings:
voiceStability: 0.5
responses:
'201':
description: Voice created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Voice'
'400':
description: Validation error (invalid audio, quota exceeded, etc.)
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
VoiceCreateArgs:
type: object
required:
- name
- audioUrl
properties:
name:
type: string
minLength: 1
maxLength: 256
description: Name of the voice
audioUrl:
type: string
format: uri
pattern: ^https://.*
description: >-
HTTPS URL to the audio file for voice cloning (MP3, WAV, M4A).
Duration must be between 30 seconds and 4 minutes.
modelId:
$ref: '#/components/schemas/VoiceModelId'
settings:
$ref: '#/components/schemas/VoiceSettings'
language:
$ref: '#/components/schemas/VoiceLanguage'
gender:
$ref: '#/components/schemas/VoiceGender'
additionalProperties: false
Voice:
type: object
properties:
id:
type: string
format: uuid
name:
type: string
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
status:
type: string
sampleUrl:
type: string
language:
allOf:
- $ref: '#/components/schemas/VoiceLanguage'
- nullable: true
gender:
allOf:
- $ref: '#/components/schemas/VoiceGender'
- nullable: true
Error:
type: object
properties:
code:
type: integer
format: int32
message:
type: string
VoiceModelId:
type: string
description: >-
Voice model to use for TTS. Determines which provider (ElevenLabs or
Minimax) and which settings are available.
enum:
- eleven_multilingual_v2
- eleven_multilingual_v1
- eleven_monolingual_v1
- eleven_turbo_v2
- eleven_turbo_v2_5
- eleven_flash_v2_5
- eleven_v3
- speech-02-hd
- speech-02-turbo
- speech-2.5-hd-preview
- speech-2.5-turbo-preview
- speech-2.6-hd
- speech-2.6-turbo
- speech-2.8-hd
- speech-2.8-turbo
VoiceSettings:
type: object
description: >-
Model-specific voice settings. Available fields depend on the chosen
modelId. See the Settings by Model section for details.
properties:
voiceStability:
type: number
minimum: 0
maximum: 1
description: >-
ElevenLabs only. Voice stability (0-1). Default: 0.8 (0.5 for
eleven_v3)
voiceSimilarity:
type: number
minimum: 0
maximum: 1
description: 'ElevenLabs only. Clarity + similarity (0-1). Default: 0.5'
voiceStyle:
type: number
minimum: 0
maximum: 1
description: 'ElevenLabs only. Style exaggeration (0-1). Default: 0.0'
voiceSpeed:
type: number
minimum: 0.7
maximum: 1.2
description: 'ElevenLabs and Minimax. Playback speed (0.7-1.2). Default: 1.0'
speakerBoost:
type: boolean
description: >-
ElevenLabs only (not available for eleven_v3). Enable speaker boost.
Default: true
languageBoost:
description: >-
Minimax only. Boost a specific language for better pronunciation.
Default: "auto"
allOf:
- $ref: '#/components/schemas/MinimaxLanguageBoost'
emotion:
description: 'Minimax only. Voice emotion. Default: "auto"'
allOf:
- $ref: '#/components/schemas/MinimaxEmotion'
VoiceLanguage:
type: string
enum:
- ENGLISH
- SPANISH
- FRENCH
- PORTUGUESE
- GERMAN
- RUSSIAN
- HINDI
- CHINESE
- DUTCH
- ARABIC
- POLISH
- BULGARIAN
- JAPANESE
- ITALIAN
VoiceGender:
type: string
enum:
- MALE
- FEMALE
MinimaxLanguageBoost:
type: string
enum:
- auto
- Afrikaans
- Arabic
- Bulgarian
- Catalan
- Chinese
- Chinese,Yue
- Croatian
- Czech
- Danish
- Dutch
- English
- Filipino
- Finnish
- French
- German
- Greek
- Hebrew
- Hindi
- Hungarian
- Indonesian
- Italian
- Japanese
- Korean
- Malay
- Norwegian
- Nynorsk
- Persian
- Polish
- Portuguese
- Romanian
- Russian
- Slovak
- Slovenian
- Spanish
- Swedish
- Tamil
- Thai
- Turkish
- Ukrainian
- Vietnamese
MinimaxEmotion:
type: string
enum:
- auto
- happy
- sad
- angry
- fearful
- disgusted
- surprised
- neutral
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: API key to be included in the x-api-key header
````