Quick Start

Submit your first video composition task with the open Video Synthesis API

This guide walks through the fastest path to generating a video with the open Video Synthesis API.

Prerequisites

Before you begin, make sure you have:

• A NavTalk API key
• A trained avatar ID if you want to use textContent
• A public audio URL or local audio file if you do not want to use TTS

Base URL

All examples below use:

https://api.navtalk.ai

Step-by-Step Process

1. Choose an Input Combination

   Pick one audio source and one visual source:

   • Audio: audioFile or audioUrl or textContent
   • Visual: characterFile or characterUrl or avatarId

   For the most common production workflow, use:

   • avatarId
   • textContent

   This lets NavTalk synthesize speech using the voice already bound to the avatar.

2. Submit a Task

   Send a multipart/form-data request to POST /api/open/v1/video-compose/submit.

   curl

   curl -X POST "https://api.navtalk.ai/api/open/v1/video-compose/submit" \
     -H "license: your-api-key-here" \
     -F "avatarId=4024d39983b4d4b488bba9377268fbac" \
     -F "textContent=Hello, welcome to NavTalk." \
     -F "title=My first synthesis task" \
     -F "bboxShift=0" \
     -F "extraMargin=10" \
     -F "parsingMode=jaw" \
     -F "leftCheekWidth=90" \
     -F "rightCheekWidth=90"
   

   const form = new FormData();
   form.append('avatarId', '4024d39983b4d4b488bba9377268fbac');
   form.append('textContent', 'Hello, welcome to NavTalk.');
   form.append('title', 'My first synthesis task');
   form.append('bboxShift', '0');
   form.append('extraMargin', '10');
   form.append('parsingMode', 'jaw');
   form.append('leftCheekWidth', '90');
   form.append('rightCheekWidth', '90');
   
   const response = await fetch(
     'https://api.navtalk.ai/api/open/v1/video-compose/submit',
     {
       method: 'POST',
       headers: {
         license: 'your-api-key-here'
       },
       body: form
     }
   );
   
   const result = await response.json();
   console.log(result);
   

   import requests
   
   response = requests.post(
       'https://api.navtalk.ai/api/open/v1/video-compose/submit',
       headers={'license': 'your-api-key-here'},
       files={},
       data={
           'avatarId': '4024d39983b4d4b488bba9377268fbac',
           'textContent': 'Hello, welcome to NavTalk.',
           'title': 'My first synthesis task',
           'bboxShift': 0,
           'extraMargin': 10,
           'parsingMode': 'jaw',
           'leftCheekWidth': 90,
           'rightCheekWidth': 90,
       }
   )
   
   result = response.json()
   print(result)
   

   Response

   {
     "code": 200,
     "message": "SUCCESS",
     "data": {
       "taskId": "6d7e24b7-412d-46ec-8d95-940099a3e979",
       "status": "Processing"
     }
   }
   
3. Poll Task Status

   Use the returned taskId with GET /api/open/v1/video-compose/status.

   curl

   curl "https://api.navtalk.ai/api/open/v1/video-compose/status?taskId=6d7e24b7-412d-46ec-8d95-940099a3e979" \
     -H "license: your-api-key-here"
   

   const taskId = result.data.taskId;
   
   const statusResponse = await fetch(
     `https://api.navtalk.ai/api/open/v1/video-compose/status?taskId=${encodeURIComponent(taskId)}`,
     {
       headers: {
         license: 'your-api-key-here'
       }
     }
   );
   
   const status = await statusResponse.json();
   console.log(status);
   

   task_id = result['data']['taskId']
   
   status_response = requests.get(
       'https://api.navtalk.ai/api/open/v1/video-compose/status',
       headers={'license': 'your-api-key-here'},
       params={'taskId': task_id}
   )
   
   status = status_response.json()
   print(status)
   

   Successful response

   {
     "code": 200,
     "message": "SUCCESS",
     "data": {
       "taskId": "6d7e24b7-412d-46ec-8d95-940099a3e979",
       "status": "Published",
       "title": "My first synthesis task",
       "videoUrl": "https://api.navtalk.ai/uploadFiles/navtalk.Brain.mp4",
       "thumbnailUrl": "https://api.navtalk.ai/uploadFiles/navtalk.Brain.png",
       "audioUrl": "https://api.navtalk.ai/uploadFiles/2026-05-18/e9d1d875-1895-4f5e-b8d2-15252013ded5.mp3",
       "resultUrl": "https://api.navtalk.ai/uploadFiles/2026-05-18/final-result.mp4",
       "failMessage": null,
       "prompt": "Hello, welcome to NavTalk.",
       "voice": "cedar",
       "voiceName": "cedar",
       "avatarId": "4024d39983b4d4b488bba9377268fbac"
     }
   }
   

   Failed response

   {
     "code": 200,
     "message": "SUCCESS",
     "data": {
       "taskId": "6d7e24b7-412d-46ec-8d95-940099a3e979",
       "status": "Fail",
       "resultUrl": null,
       "failMessage": "Failed to generate audio from text"
     }
   }
   
4. List Recent Tasks

   Use GET /api/open/v1/video-compose/list to retrieve recent tasks for the current API key.

   curl "https://api.navtalk.ai/api/open/v1/video-compose/list?page=1&size=10" \
     -H "license: your-api-key-here"
   

   This endpoint returns a paginated list with the same item structure used by /status.

Additional Examples

Avatar + Uploaded Audio File

curl -X POST "https://api.navtalk.ai/api/open/v1/video-compose/submit" \
  -H "license: your-api-key-here" \
  -F "avatarId=4024d39983b4d4b488bba9377268fbac" \
  -F "audioFile=@./voice.mp3"

External Video + External Audio

curl -X POST "https://api.navtalk.ai/api/open/v1/video-compose/submit" \
  -H "license: your-api-key-here" \
  -F "characterUrl=https://cdn.example.com/source.mp4" \
  -F "audioUrl=https://cdn.example.com/voice.mp3"

Uploaded Image + External Audio

curl -X POST "https://api.navtalk.ai/api/open/v1/video-compose/submit" \
  -H "license: your-api-key-here" \
  -F "characterFile=@./portrait.jpg" \
  -F "audioUrl=https://cdn.example.com/voice.wav"

Notes

• textContent requires avatarId
• /status and /list return full public URLs
• Public audio URLs should point to directly accessible audio files
• For external audio, MP3 and WAV are the safest formats

Next Steps

• Review all request fields in the API Reference
• Learn how provider-specific TTS works in Avatar Voice and TTS Providers
• Create reusable talking avatars with Custom Avatar