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

# Quick Start

> Step-by-step guide to creating and training your first custom digital human avatar

This guide will walk you through the process of creating and training your first custom digital human avatar using NavTalk.

## Prerequisites

Before you begin, ensure you have:

* A NavTalk account with API access
* Your API key (obtain from the [dashboard](https://console.navtalk.ai/login#/dashboard))
* Training video ready (meeting the quality requirements)

## Step-by-Step Process

<Steps>
  <Step title="Prepare Training Video">
    Before uploading, ensure your training video meets the quality and content requirements. See the [Reference Materials Requirements](/api/custom-avatar/reference-materials) page for detailed specifications, recommended content, troubleshooting tips, and a reference video example.
  </Step>

  <Step title="Start Training Process">
    Initiate the avatar training:

    <CodeGroup>
      ```bash curl theme={null}
      curl -X POST "https://api.navtalk.ai/api/open/v1/avatar/add" \
        -H "license: your-license-key" \
        -H "Content-Type: application/json" \
        -d '{
          "name": "my-avatar",
          "url": "https://example.com/training-video.mp4",
          "providerId": "your-provider-id",
          "model": "your-model-id",
          "voice": "your-voice-id",
          "firstMessage": "Hello! How can I help you today?",
          "prompt": "You are a helpful assistant."
        }'
      ```

      ```javascript JavaScript theme={null}
      const trainingConfig = {
        name: 'my-avatar',
        url: 'https://example.com/training-video.mp4',
        providerId: 'your-provider-id',
        model: 'your-model-id',
        voice: 'your-voice-id',
        firstMessage: 'Hello! How can I help you today?',
        prompt: 'You are a helpful assistant.'
      };

      const trainingResponse = await fetch('https://api.navtalk.ai/api/open/v1/avatar/add', {
        method: 'POST',
        headers: {
          'license': LICENSE,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(trainingConfig)
      });

      const training = await trainingResponse.json();
      const jobId = training.data.jobId;
      const avatarId = training.data.avatarId;
      ```

      ```python Python theme={null}
      training_config = {
          'name': 'my-avatar',
          'url': 'https://example.com/training-video.mp4',
          'providerId': 'your-provider-id',
          'model': 'your-model-id',
          'voice': 'your-voice-id',
          'firstMessage': 'Hello! How can I help you today?',
          'prompt': 'You are a helpful assistant.'
      }

      response = requests.post(
          'https://api.navtalk.ai/api/open/v1/avatar/add',
          headers={
              'license': LICENSE,
              'Content-Type': 'application/json'
          },
          json=training_config
      )

      result = response.json()
      job_id = result['data']['jobId']
      avatar_id = result['data']['avatarId']
      ```
    </CodeGroup>

    <Note>
      You can get your `providerId`, `model`, and `voice` IDs by calling the [List Providers](/api-reference/endpoint/navtalk/provider-list), [List Models](/api-reference/endpoint/navtalk/model-list), and [List Voices](/api-reference/endpoint/navtalk/voice-list) endpoints respectively.
    </Note>
  </Step>

  <Step title="Monitor Training Progress">
    Check the training status periodically:

    <CodeGroup>
      ```bash curl theme={null}
      curl -X GET "https://api.navtalk.ai/api/open/v1/avatar/status?jobId={job_id}" \
        -H "license: your-license-key"
      ```

      ```javascript JavaScript theme={null}
      const checkStatus = async () => {
        const response = await fetch(
          `https://api.navtalk.ai/api/open/v1/avatar/status?jobId=${jobId}`,
          {
            headers: {
              'license': LICENSE
            }
          }
        );
        
        const result = await response.json();
        const status = result.data; // 'Pending', 'Processing', 'Success', 'Failed'
        console.log('Training status:', status);
        
        if (status === 'Success') {
          console.log('Avatar ready! Avatar ID:', avatarId);
        } else if (status === 'Failed') {
          console.error('Training failed');
        }
      };

      // Poll every 30 seconds
      setInterval(checkStatus, 30000);
      ```

      ```python Python theme={null}
      import time

      def check_status(job_id):
          response = requests.get(
              f'https://api.navtalk.ai/api/open/v1/avatar/status?jobId={job_id}',
              headers={'license': LICENSE}
          )
          
          result = response.json()
          status = result['data']  # 'Pending', 'Processing', 'Success', 'Failed'
          print(f'Training status: {status}')
          
          if status == 'Success':
              print(f'Avatar ready! Avatar ID: {avatar_id}')
              return True
          elif status == 'Failed':
              print('Training failed')
              return True
          
          return False

      # Poll every 30 seconds
      while not check_status(job_id):
          time.sleep(30)
      ```
    </CodeGroup>

    <Note>
      Training typically takes 15-60 minutes depending on the complexity and quality settings. You can check status periodically or set up webhooks for notifications.
    </Note>
  </Step>

  <Step title="Use Your Custom Avatar">
    Once training is complete, use your custom avatar in your applications:

    <CodeGroup>
      ```bash curl theme={null}
      # For Real-time Digital Human API
      # Use the avatarId returned from the training response
      # Connect via WebSocket: wss://transfer.navtalk.ai/wss/v2/realtime-chat?license=YOUR_KEY&avatarId=YOUR_AVATAR_ID
      ```

      ```javascript JavaScript theme={null}
      // For Real-time Digital Human API
      const websocketUrl = `wss://transfer.navtalk.ai/wss/v2/realtime-chat?license=${encodeURIComponent(LICENSE)}&avatarId=${encodeURIComponent(avatarId)}`;

      const socket = new WebSocket(websocketUrl);
      socket.binaryType = 'arraybuffer';

      socket.onopen = () => {
        console.log('Connected to digital human with custom avatar');
      };
      ```

      ```python Python theme={null}
      # For Real-time Digital Human API
      from urllib.parse import quote
      import websockets

      websocket_url = f'wss://transfer.navtalk.ai/wss/v2/realtime-chat?license={quote(LICENSE)}&avatarId={quote(avatar_id)}'

      async def connect():
          async with websockets.connect(websocket_url) as websocket:
              print('Connected to digital human with custom avatar')
              # Handle messages here
      ```
    </CodeGroup>

    <Note>
      For detailed WebSocket integration, see the [Real-time Digital Human API Quick Start](/api/real-time-digital-human-api/quick-start/establish-connection).
    </Note>
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Training fails or takes too long">
    * Check file sizes and formats (MP4, MOV recommended, under 50MB)
    * Verify video meets minimum requirements (at least 2 seconds, 1080p or lower)
    * Ensure videos are not corrupted
    * Check that your training video meets quality requirements (clear, well-lit, consistent appearance)
    * Contact support if issues persist
  </Accordion>

  <Accordion title="Training results don't match the reference materials">
    * Ensure videos meet quality requirements (1080p or lower, at least 2 seconds)
    * Check that lighting is consistent and adequate
    * Verify facial features are clearly visible throughout
    * Avoid videos with complex facial hair (beards, mustaches) - use portraits with little or no facial hair
  </Accordion>

  <Accordion title="Avatar lacks detail or shows distortion">
    * Ensure videos meet resolution requirements (1080p or lower, not higher)
    * Ensure good lighting throughout
    * **Avoid portraits with beards or complex facial hair** - use portraits with little or no facial hair
    * Consider using a video that can loop naturally for smoother synthesis
    * Try increasing training iterations or using higher quality settings
  </Accordion>

  <Accordion title="Avatar not appearing in applications">
    * Verify that training completed successfully and note the character name
    * Check that the training status shows 'completed' before attempting to use the avatar
  </Accordion>
</AccordionGroup>