> ## Documentation Index
> Fetch the complete documentation index at: https://docs.navtalk.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Add Avatar

> Create a new avatar training job from a media URL.

**Supported image formats**: `jpg`, `jpeg`, `png`, `bmp`, `webp`.

**Supported video formats**: `mp4`, `mov`, `webm`, `avi`, `m4v`.

**Video constraints**:
- Minimum duration: `2` seconds
- Maximum resolution: `1920x1080`

Returns a `jobId` (for polling status) and an `avatarId` (for referencing the avatar in sessions).

The `license` key can be passed as either a query parameter or a request header.

## Media Requirements

The `url` field now supports both image and video files:

* Images: `jpg`, `jpeg`, `png`, `bmp`, `webp`
* Videos: `mp4`, `mov`, `webm`, `avi`, `m4v`

When using a video URL, the backend enforces:

* Minimum duration: **2 seconds**
* Maximum resolution: **1920x1080**


## OpenAPI

````yaml POST /api/open/v1/avatar/add
openapi: 3.1.0
info:
  title: NavTalk API
  description: NavTalk API for AI avatar management, file uploads, and video generation
  version: 1.0.0
servers:
  - url: https://api.navtalk.ai
    description: NavTalk Production Environment Server
  - url: https://qaapi.navtalk.ai
    description: NavTalk QA Environment Server
  - url: https://devapi.navtalk.ai
    description: NavTalk Development Environment Server
security:
  - navtalkLicenseAuth: []
paths:
  /api/open/v1/avatar/add:
    post:
      tags:
        - Avatar
      summary: Add Avatar
      description: >-
        Create a new avatar training job from a media URL.


        **Supported image formats**: `jpg`, `jpeg`, `png`, `bmp`, `webp`.


        **Supported video formats**: `mp4`, `mov`, `webm`, `avi`, `m4v`.


        **Video constraints**:

        - Minimum duration: `2` seconds

        - Maximum resolution: `1920x1080`


        Returns a `jobId` (for polling status) and an `avatarId` (for
        referencing the avatar in sessions).


        The `license` key can be passed as either a query parameter or a request
        header.
      operationId: addAvatar
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AvatarAddRequest'
            example:
              name: my-video-avatar
              url: https://example.com/avatar.mp4
              providerId: b92a28fb2ea737457c7f13ba554759c0
              model: agent_3201khcbet2vf349gpmtfg83q0hy
              voice: CwhRBWXzGAHq8TQ4Fs17
              firstMessage: Hi! How can I help you today?
              prompt: You are a helpful assistant.
      responses:
        '200':
          description: Avatar training job created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvatarAddResponse'
              example:
                code: 200
                message: SUCCESS
                data:
                  jobId: 096f43cf-4dbf-47d5-9583-8e3d0c3a5641
                  avatarId: fbc269dcd0a738cf8e5e0f465671303c
        '400':
          description: Validation failed or server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NavtalkErrorResponse'
              examples:
                invalidProvider:
                  summary: Provider not found
                  value:
                    code: 400
                    message: Provider not found
                invalidModel:
                  summary: Model not supported
                  value:
                    code: 400
                    message: Model 'xxx' is not supported by this provider
                invalidUrl:
                  summary: Invalid media URL format
                  value:
                    code: 400
                    message: >-
                      The url must point to a supported media file (Images: JPG,
                      JPEG, PNG, BMP, WebP; Videos: MP4, MOV, WebM, AVI, M4V).
                videoDurationTooShort:
                  summary: Video duration too short
                  value:
                    code: 400
                    message: Video duration must be at least 2 seconds.
                videoResolutionExceeded:
                  summary: Video resolution exceeded
                  value:
                    code: 400
                    message: >-
                      Video resolution must not exceed 1920x1080. Current:
                      2560x1440.
                duplicateName:
                  summary: Duplicate name
                  value:
                    code: 400
                    message: The name already exists
      security:
        - navtalkLicenseAuth: []
components:
  schemas:
    AvatarAddRequest:
      required:
        - name
        - url
        - providerId
        - model
        - voice
      type: object
      properties:
        name:
          type: string
          description: Display name for the avatar. Must be unique per account.
          example: my-video-avatar
        url:
          type: string
          description: >-
            URL of the source media file.


            Supported image formats: `jpg`, `jpeg`, `png`, `bmp`, `webp`.


            Supported video formats: `mp4`, `mov`, `webm`, `avi`, `m4v`.


            Video constraints: minimum duration `2` seconds; maximum resolution
            `1920x1080`.
          example: https://example.com/avatar.mp4
        providerId:
          type: string
          description: The provider ID to use (obtained from `/provider/list`).
          example: b92a28fb2ea737457c7f13ba554759c0
        model:
          type: string
          description: >-
            The model key to use (obtained from `/model/list`). For ElevenLabs
            agents, see [ElevenLabs Agents
            Quickstart](https://elevenlabs.io/docs/eleven-agents/quickstart).
            For Cartesia agents, see [Cartesia Voices Agents
            Quickstart](https://play.cartesia.ai/agents).
          example: agent_3201khcbet2vf349gpmtfg83q0hy
        voice:
          type: string
          description: The voice key to use (obtained from `/voice/list`).
          example: CwhRBWXzGAHq8TQ4Fs17
        firstMessage:
          type: string
          description: >-
            Optional opening message the avatar says at the start of a
            conversation.
          example: Hi! How can I help you today?
        prompt:
          type: string
          description: >-
            Optional system prompt that controls the avatar's behavior and
            personality.
          example: You are a helpful assistant.
    AvatarAddResponse:
      type: object
      properties:
        code:
          type: integer
          example: 200
        message:
          type: string
          example: SUCCESS
        data:
          type: object
          properties:
            jobId:
              type: string
              description: Use this ID to poll `/avatar/status`.
              example: 096f43cf-4dbf-47d5-9583-8e3d0c3a5641
            avatarId:
              type: string
              description: Use this ID to reference the avatar in sessions.
              example: fbc269dcd0a738cf8e5e0f465671303c
    NavtalkErrorResponse:
      type: object
      properties:
        code:
          type: integer
          example: 400
        message:
          type: string
          example: Invalid license key
  securitySchemes:
    navtalkLicenseAuth:
      type: apiKey
      in: header
      name: license
      description: NavTalk API license key (e.g. sk_navtalk_...)

````