API Reference

Reference for the open Video Synthesis API submit, status, and list endpoints

The open Video Synthesis API is built around three REST endpoints:

• POST /api/open/v1/video-compose/submit
• GET /api/open/v1/video-compose/status
• GET /api/open/v1/video-compose/list

Authentication

All endpoints use the same public API-key authentication model as the other open APIs.

• Recommended: license: your-api-key
• Compatible fallback: ?license=your-api-key

Submit Endpoint

POST /api/open/v1/video-compose/submit
Content-Type: multipart/form-data

Request Rules

• Exactly one of audioFile, audioUrl, or textContent is required
• Exactly one of characterFile, characterUrl, or avatarId is required
• If textContent is used, avatarId is required

Request Fields

title · string

Optional task title saved with the generation record.

audioFile · file

Uploaded audio file used for lip sync.

audioUrl · string

Public audio URL. Use a directly accessible audio file URL. MP3 and WAV are recommended.

textContent · string

Text to synthesize into speech before video generation. Requires avatarId.

characterFile · file

Uploaded image or video used as the visual source.

characterUrl · string

Public image or video URL used as the visual source.

avatarId · string

Existing trained avatar ID. Required when textContent is used.

bboxShift · integer · default: "0"

Optional face crop offset.

extraMargin · integer · default: "10"

Optional extra face margin.

parsingMode · string · default: "\"jaw\""

Optional parsing mode. Current default is jaw.

leftCheekWidth · integer · default: "90"

Optional left cheek blend width.

rightCheekWidth · integer · default: "90"

Optional right cheek blend width.

Submit Example

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=Welcome to NavTalk." \
  -F "title=Launch video"

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"

Submit Response

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

taskId · string

Unique task identifier used for polling and task history queries.

status · string

Initial task status. A successful submit returns Processing.

Status Endpoint

GET /api/open/v1/video-compose/status

Query Parameters

taskId · string · required

Task ID returned by the submit endpoint.

Response Fields

taskId · string

Task ID.

status · string

Current task status. Common values:

• Draft
• Processing
• Published
• Fail

title · string

Task title, if one was supplied during submission.

videoUrl · string

Full public URL for the source visual asset associated with the task.

thumbnailUrl · string

Full public thumbnail URL when available.

audioUrl · string

Full public URL for the source audio used in the task.

resultUrl · string

Full public URL for the final generated video. Present when generation succeeds.

failMessage · string

Failure message when status is Fail.

prompt · string

The original textContent submitted for TTS tasks.

voice · string

Voice key bound to the avatar when TTS is used.

voiceName · string

Voice display name currently returned by the service.

avatarId · string

Avatar ID used for this task, if applicable.

Status Example

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

List Endpoint

GET /api/open/v1/video-compose/list

Query Parameters

page · integer · default: "1"

Page number.

size · integer · default: "10"

Page size.

Response Shape

{
  "code": 200,
  "message": "SUCCESS",
  "data": {
    "list": [
      {
        "taskId": "6d7e24b7-412d-46ec-8d95-940099a3e979",
        "status": "Published",
        "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/voice.mp3",
        "resultUrl": "https://api.navtalk.ai/uploadFiles/2026-05-18/final-result.mp4"
      }
    ],
    "page": 1,
    "size": 10,
    "total": 1,
    "pages": 1,
    "hasMore": false
  }
}

The list items use the same field structure as /status.

TTS Provider Behavior

When you submit textContent with an avatarId, the service does not use a global fixed voice list. Instead, it:

1. Loads the selected avatar
2. Reads the avatar’s bound provider and voice key
3. Generates audio with that provider
4. Uses the generated audio for video synthesis

Supported TTS providers currently include:

• OpenAI
• ElevenLabs
• Cartesia

External Media Notes

• External characterUrl values can be image or video URLs
• External audioUrl values should be directly accessible audio files
• For best compatibility during duration validation, use MP3 or WAV for external audio URLs