> ## 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.

# Get Avatar Detail by Name

> Query detailed information of a specific avatar by its name. Searches both custom avatars (owned by the current license) and system avatars. Returns complete avatar configuration including provider settings, model, voice, prompt information, and provider name.

This endpoint is useful when you need to query avatar details using the avatar name instead of the ID, especially for WebSocket connections where the character name parameter is used.



## OpenAPI

````yaml GET /api/open/v1/avatar/getByName
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/getByName:
    get:
      tags:
        - Avatar
      summary: Get Avatar Detail by Name
      description: >-
        Query detailed information of a specific avatar by its name. Searches
        both custom avatars (owned by the current license) and system avatars.
        Returns complete avatar configuration including provider settings,
        model, voice, prompt information, and provider name.


        This endpoint is useful when you need to query avatar details using the
        avatar name instead of the ID, especially for WebSocket connections
        where the character name parameter is used.
      operationId: getAvatarByName
      parameters:
        - name: name
          in: query
          description: >-
            The avatar name to query (e.g., 'my-avatar' or system avatar like
            'navtalk.Leo')
          required: true
          schema:
            type: string
            example: navtalk.Leo
      responses:
        '200':
          description: Avatar detail retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvatarDetailByNameResponse'
              example:
                code: 200
                message: SUCCESS
                data:
                  id: fbc269dcd0a738cf8e5e0f465671303c
                  name: navtalk.Leo
                  url: https://example.com/photo.jpg
                  thumbnailUrl: https://example.com/photo-thumbnail.jpg
                  providerId: b92a28fb2ea737457c7f13ba554759c0
                  providerName: openai
                  model: agent_3201khcbet2vf349gpmtfg83q0hy
                  voice: CwhRBWXzGAHq8TQ4Fs17
                  firstMessage: Hi! How can I help you today?
                  prompt: You are a helpful assistant.
                  videoFile: false
                  status: Success
        '400':
          description: Avatar not found or license validation failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NavtalkErrorResponse'
              examples:
                notFound:
                  summary: Avatar not found
                  value:
                    code: 400
                    message: Avatar not found
                licenseFailed:
                  summary: License validation failed
                  value:
                    code: 400
                    message: Invalid license key
      security:
        - navtalkLicenseAuth: []
components:
  schemas:
    AvatarDetailByNameResponse:
      type: object
      properties:
        code:
          type: integer
          example: 200
        message:
          type: string
          example: SUCCESS
        data:
          $ref: '#/components/schemas/OpenAvatarExtend'
    NavtalkErrorResponse:
      type: object
      properties:
        code:
          type: integer
          example: 400
        message:
          type: string
          example: Invalid license key
    OpenAvatarExtend:
      type: object
      properties:
        id:
          type: string
          description: The unique avatar ID.
          example: fbc269dcd0a738cf8e5e0f465671303c
        name:
          type: string
          description: Display name of the avatar.
          example: navtalk.Leo
        url:
          type: string
          description: >-
            Source media URL used to create the avatar. Supported image formats:
            jpg, jpeg, png, bmp, webp. Supported video formats: mp4, mov, webm,
            avi, m4v.
          example: https://example.com/avatar.mp4
        thumbnailUrl:
          type: string
          description: Thumbnail image URL for previewing the avatar.
          example: https://example.com/avatar-thumbnail.jpg
        providerId:
          type: string
          description: Provider ID associated with this avatar.
          example: b92a28fb2ea737457c7f13ba554759c0
        providerName:
          type: string
          description: Provider type identifier (e.g., 'openai', 'elevenlabs').
          example: openai
        model:
          type: string
          description: >-
            Model key used by this avatar. 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: Voice key used by this avatar.
          example: CwhRBWXzGAHq8TQ4Fs17
        firstMessage:
          type: string
          description: Opening message spoken by the avatar.
          example: Hi! How can I help you today?
        prompt:
          type: string
          description: System prompt for the avatar.
          example: You are a helpful assistant.
        videoFile:
          type: boolean
          description: >-
            Whether the source media is a video file (`true`) or an image file
            (`false`).
          example: true
        status:
          type: string
          enum:
            - Draft
            - Pending
            - Processing
            - Success
            - Failed
          description: Current training status of the avatar.
          example: Success
  securitySchemes:
    navtalkLicenseAuth:
      type: apiKey
      in: header
      name: license
      description: NavTalk API license key (e.g. sk_navtalk_...)

````