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)
• Training video ready (meeting the quality requirements)

Step-by-Step Process

1. Prepare Training Video

   Before uploading, ensure your training video meets the quality and content requirements. See the Reference Materials Requirements page for detailed specifications, recommended content, troubleshooting tips, and a reference video example.

2. Start Training Process

   Initiate the avatar training:

   curl

   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."
     }'
   

   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;
   

   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']
   

   You can get your providerId, model, and voice IDs by calling the List Providers, List Models, and List Voices endpoints respectively.

3. Monitor Training Progress

   Check the training status periodically:

   curl

   curl -X GET "https://api.navtalk.ai/api/open/v1/avatar/status?jobId={job_id}" \
     -H "license: your-license-key"
   

   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);
   

   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)
   

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

4. Use Your Custom Avatar

   Once training is complete, use your custom avatar in your applications:

   curl

   # 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
   

   // 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');
   };
   

   # 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
   

   For detailed WebSocket integration, see the Real-time Digital Human API Quick Start.

Troubleshooting

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

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

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

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