> ## 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: 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 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 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/FishAudioVoiceGenerationOptions' videoWidth: type: integer minimum: 1 videoHeight: type: integer minimum: 1 metadata: type: object additionalProperties: true description: Caller metadata, up to 16 KB serialized. AvatarVideo: type: object required: - id - status - truncated - effectiveMaxDurationSeconds - 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. content: type: object required: - available properties: available: type: boolean url: type: string format: uri expiresAt: type: string format: date-time failure: type: - object - 'null' properties: code: type: string message: type: string retryable: type: boolean 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: type: string description: The ElevenLabs model ID to use for voice generation. 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 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 ````