> ## Documentation Index > Fetch the complete documentation index at: https://anam.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # create avatar video > Creates an asynchronous avatar-video render backed by a normal recorded Anam session. A saved persona contributes only its snapshotted avatar, voice, language, model and director notes; its greeting, brain, prompt and tools never run. The request is rejected rather than queued when either concurrency limit is full. ## OpenAPI ````yaml https://api.anam.ai/swagger.json post /v1/avatar-videos openapi: 3.1.0 info: title: Anam AI API version: '1.0' servers: - url: https://api.anam.ai description: Anam API security: - BearerAuth: [] tags: - name: Sessions - name: Avatar Videos - name: Meetings - name: Personas - name: Avatars - name: Voices - name: Pronunciation Dictionaries - name: LLMs - name: Knowledge - name: Tools - name: Share Links - name: Engine paths: /v1/avatar-videos: post: tags: - Avatar Videos summary: Create an avatar video description: >- Creates an asynchronous avatar-video render backed by a normal recorded Anam session. A saved persona contributes only its snapshotted avatar, voice, language, model and director notes; its greeting, brain, prompt and tools never run. The request is rejected rather than queued when either concurrency limit is full. operationId: createAvatarVideo parameters: - in: header name: Idempotency-Key required: true schema: type: string minLength: 1 maxLength: 255 description: >- Stable caller-generated key. Reusing it with the same body returns the original resource; a different body returns 409. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAvatarVideoRequest' examples: savedPersona: $ref: '#/components/examples/AvatarVideoCreateWithPersona' direct: $ref: '#/components/examples/AvatarVideoCreateDirect' responses: '202': description: Accepted. Poll the returned resource. headers: Location: schema: type: string description: Relative resource URL. Idempotent-Replayed: schema: type: boolean description: True when this key/body returned an existing job. content: application/json: schema: $ref: '#/components/schemas/AvatarVideo' '400': description: Invalid request or avatar-video configuration content: application/json: schema: $ref: '#/components/schemas/AvatarVideoError' '401': description: Missing or invalid API key content: application/json: schema: $ref: '#/components/schemas/AvatarVideoError' '403': description: >- API key permission or avatar-model entitlement denied, or environment sent by a non-internal account content: application/json: schema: $ref: '#/components/schemas/AvatarVideoError' '404': description: Persona, avatar or voice not found content: application/json: schema: $ref: '#/components/schemas/AvatarVideoError' '409': description: Idempotency key conflict content: application/json: schema: $ref: '#/components/schemas/AvatarVideoError' '410': description: Referenced resource was deleted content: application/json: schema: $ref: '#/components/schemas/AvatarVideoError' '429': description: Normal session or avatar-video concurrency limit reached. headers: Retry-After: schema: type: integer description: Conservative retry delay in seconds. content: application/json: schema: $ref: '#/components/schemas/AvatarVideoError' '502': description: Worker or session dispatch failed content: application/json: schema: $ref: '#/components/schemas/AvatarVideoError' '503': description: >- Avatar-video generation is disabled or the worker is unavailable, or the API key could not be checked because of a temporary server problem (the key may be valid; retry after `Retry-After` seconds). headers: Retry-After: description: Seconds to wait before retrying, when known. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/AvatarVideoError' components: schemas: CreateAvatarVideoRequest: type: object additionalProperties: false required: - script oneOf: - required: - personaId not: anyOf: - required: - avatarId - required: - voiceId - required: - avatarModel - required: - directorNotes - required: - languageCode - required: - voiceSpeed - required: - voiceGenerationOptions - required: - videoWidth - required: - videoHeight - required: - avatarId - voiceId not: required: - personaId dependentRequired: videoWidth: - videoHeight videoHeight: - videoWidth properties: script: type: string minLength: 1 maxLength: 20000 description: Exact text spoken through TTS; the brain is never invoked. personaId: type: string description: >- Saved persona to snapshot. Mutually exclusive with direct configuration fields. avatarId: type: string voiceId: type: string avatarModel: type: string example: cara-4-latest directorNotes: type: - object - 'null' properties: expressivity: type: - number - 'null' minimum: 0 maximum: 1 customStylePrompt: type: - string - 'null' presetStyle: type: - string - 'null' languageCode: type: string example: en voiceSpeed: type: number minimum: -1 maximum: 1 voiceGenerationOptions: oneOf: - $ref: '#/components/schemas/CartesiaSonic3VoiceGenerationOptions' - $ref: '#/components/schemas/ElevenLabsV1VoiceGenerationOptions' - $ref: '#/components/schemas/ElevenLabsV2VoiceGenerationOptions' - $ref: '#/components/schemas/ElevenLabsV3VoiceGenerationOptions' - $ref: '#/components/schemas/ElevenLabsV4VoiceGenerationOptions' - $ref: '#/components/schemas/FishAudioVoiceGenerationOptions' videoWidth: type: integer minimum: 1 videoHeight: type: integer minimum: 1 environment: type: object additionalProperties: false required: - namespace description: >- Optional engine routing for the render session, as on the session token endpoint. Internal accounts only; other accounts get 403. properties: namespace: type: string minLength: 1 maxLength: 63 pattern: >- ^(?:anam-engine-preview-\d+|devspace-[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)$ description: Engine namespace to render on, for example a preview engine. example: anam-engine-preview-3874 metadata: type: object additionalProperties: true description: >- Caller metadata, up to 16 KB serialized. It is stored and returned as sent. A zero-data-retention video, which includes every video created on a regional host, doesn't store it: its responses return `{}`. Keep your own mapping from the video id to your records. retentionSeconds: type: integer minimum: 300 maximum: 2592000 description: >- Seconds to keep the recording, session report and job content after the job ends; Lab then deletes them within about a minute. Without a value they are kept until deleted, except with Zero Data Retention, where the default is 600 and the most 43200. Download the recording as soon as it is ready. AvatarVideo: type: object required: - id - status - truncated - effectiveMaxDurationSeconds - region - zeroDataRetention - content - createdAt - metadata properties: id: type: string example: avv_123 status: type: string enum: - pending - running - finalizing - completed - failed - cancelled completionReason: type: - string - 'null' enum: - script_completed - max_duration_reached - cancelled - null truncated: type: boolean durationSeconds: type: - number - 'null' effectiveMaxDurationSeconds: type: integer sessionId: type: - string - 'null' description: >- Underlying normal EngineSession ID. Use its recording deletion endpoint for deletion. region: type: - string - 'null' enum: - eu - us - null description: >- Region the job is pinned to: eu when created on api.eu.anam.ai, us when created on api.us.anam.ai. Its session, recording and retries stay in that region. Null when created on api.anam.ai. zeroDataRetention: type: boolean description: >- Whether the job runs with Zero Data Retention, which keeps its script, and a direct request's style prompts, out of Lab's database. A persona-sourced job's director notes stay in its stored persona. Always true for a job created on a regional host. content: type: object required: - available - deleteAt properties: available: type: boolean deleteAt: type: - string - 'null' format: date-time description: >- When the recording, report and job content are deleted. Null while the job runs, or when they are kept until deleted. Not the URL expiry. url: type: string format: uri expiresAt: type: string format: date-time description: When this presigned url expires (one hour). failure: type: - object - 'null' properties: code: type: string message: type: string retryable: type: boolean description: >- Whether a retry can work, as far as the job record shows. False when the same failure would recur or the content a retry reuses has been deleted; create a new avatar video instead. When true, POST /v1/avatar-videos/{id}/retry can still return 409 content_expired if the content turns out to be gone. retryOf: type: - string - 'null' createdAt: type: string format: date-time startedAt: type: - string - 'null' format: date-time completedAt: type: - string - 'null' format: date-time metadata: type: object additionalProperties: true AvatarVideoError: type: object required: - code - message - requestId - retryable properties: code: type: string description: Stable machine-readable failure code. message: type: string requestId: type: string retryable: type: boolean details: type: object additionalProperties: true CartesiaSonic3VoiceGenerationOptions: title: Cartesia Sonic-3 type: object description: Voice generation options for Cartesia Sonic-3 models. properties: volume: type: number description: >- Controls the volume level of the generated voice as a multiplier, between 0.5 (quieter) and 2.0 (louder). example: 1 minimum: 0.5 maximum: 2 speed: type: number description: >- Controls the speed of the spoken voice as a multiplier, between 0.6 (slower) and 1.5 (faster). example: 1 minimum: 0.6 maximum: 1.5 emotion: type: string description: >- Sets the emotional tone of the generated voice. Supported emotions are: neutral, calm, angry, content, sad, scared. example: neutral oneOf: - type: string enum: - neutral - calm - angry - content - sad - scared ElevenLabsV1VoiceGenerationOptions: title: ElevenLabs V1 type: object description: Voice generation options for ElevenLabs V1 models. properties: stability: type: number description: >- Controls how stable the generated voice is between each generation, between 0 (more varied/higher emotional range) and 1 (more stable/less emotional range). example: 0.5 minimum: 0 maximum: 1 similarityBoost: type: number description: >- Controls how close the generated voice is to the original speaker, between 0 (more varied) and 1 (more similar). example: 0 minimum: 0 maximum: 1 speed: type: number description: >- Controls the speed of the spoken voice as a multiplier, between 0.7 (slower) and 1.2 (faster). example: 1 minimum: 0.7 maximum: 1.2 ElevenLabsV2VoiceGenerationOptions: title: ElevenLabs V2 type: object description: Voice generation options for ElevenLabs V2 models. properties: stability: type: number description: >- Controls how stable the generated voice is between each generation, between 0 (more varied/higher emotional range) and 1 (more stable/less emotional range). example: 0.5 minimum: 0 maximum: 1 similarityBoost: type: number description: >- Controls how close the generated voice is to the original speaker, between 0 (more varied) and 1 (more similar). example: 0.75 minimum: 0 maximum: 1 style: type: number description: >- Amplifies the style of the original speaker, between 0 and 1, it is recommended to keep this value low (0) to reduce latency. example: 0 minimum: 0 maximum: 1 useSpeakerBoost: type: boolean description: >- Whether to use speaker boost for the generated voice, enhancing the similarity to the original speaker. example: true speed: type: number description: >- Controls the speed of the spoken voice as a multiplier, between 0.7 (slower) and 1.2 (faster). example: 1 minimum: 0.7 maximum: 1.2 model: $ref: '#/components/schemas/ElevenLabsModelOverride' ElevenLabsV3VoiceGenerationOptions: title: ElevenLabs V3 type: object additionalProperties: false description: >- Voice generation options for an eleven_v3 or eleven_v3_conversational voice, or for any voice whose model override is one of them. Only stability is supported. properties: stability: type: number description: >- Controls how stable the generated voice is, from 0 (more varied) to 1 (more stable). example: 0.5 minimum: 0 maximum: 1 model: $ref: '#/components/schemas/ElevenLabsModelOverride' ElevenLabsV4VoiceGenerationOptions: title: ElevenLabs V4 type: object additionalProperties: false description: >- Voice generation options for an eleven_v4 or eleven_v4_turbo voice, or for any voice whose model override is one of them. Only stability and similarityBoost are supported. properties: stability: type: number description: >- Controls how stable the generated voice is, from 0 (more varied) to 1 (more stable). example: 0.5 minimum: 0 maximum: 1 similarityBoost: type: number description: >- Controls how close the generated voice is to the original speaker, between 0 (more varied) and 1 (more similar). example: 0.75 minimum: 0 maximum: 1 model: $ref: '#/components/schemas/ElevenLabsModelOverride' FishAudioVoiceGenerationOptions: title: Fish Audio type: object description: Voice generation options for Fish Audio models. properties: volume: type: number description: >- Controls the volume level of the generated voice as a multiplier, between 0.5 (quieter) and 2.0 (louder). example: 1 minimum: 0.5 maximum: 2 speed: type: number description: >- Controls the speed of the spoken voice as a multiplier, between 0.5 (slower) and 2.0 (faster). example: 1 minimum: 0.5 maximum: 2 ElevenLabsModelOverride: type: string enum: - eleven_v4_turbo - eleven_v3_conversational - eleven_v4 - eleven_v3 - eleven_flash_v2_5 - eleven_multilingual_v2 - eleven_flash_v2 - eleven_turbo_v2_5 description: >- Replaces the voice's ElevenLabs model for generation. Must be an ElevenLabs model supported for voice imports. The other options must be valid for this model: for example, eleven_v4 accepts only stability and similarityBoost. examples: AvatarVideoCreateWithPersona: summary: Render a script with a saved persona snapshot value: script: Welcome to the product tour. personaId: 00000000-0000-0000-0000-000000000000 metadata: customerJobId: onboarding-42 AvatarVideoCreateDirect: summary: Render with explicit avatar and voice configuration value: script: Welcome to the product tour. avatarId: 071b0286-4cce-4808-bee2-e642f1062de3 voiceId: de23e340-1416-4dd8-977d-065a7ca11697 avatarModel: cara-4-latest directorNotes: customStylePrompt: Warm and clear languageCode: en voiceSpeed: 0 videoWidth: 1152 videoHeight: 768 metadata: customerJobId: onboarding-42 securitySchemes: BearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.