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

# 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

```text theme={null}
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

<ResponseField name="title" type="string">
  Optional task title saved with the generation record.
</ResponseField>

<ResponseField name="audioFile" type="file">
  Uploaded audio file used for lip sync.
</ResponseField>

<ResponseField name="audioUrl" type="string">
  Public audio URL. Use a directly accessible audio file URL. `MP3` and `WAV` are recommended.
</ResponseField>

<ResponseField name="textContent" type="string">
  Text to synthesize into speech before video generation. Requires `avatarId`.
</ResponseField>

<ResponseField name="characterFile" type="file">
  Uploaded image or video used as the visual source.
</ResponseField>

<ResponseField name="characterUrl" type="string">
  Public image or video URL used as the visual source.
</ResponseField>

<ResponseField name="avatarId" type="string">
  Existing trained avatar ID. Required when `textContent` is used.
</ResponseField>

<ResponseField name="bboxShift" type="integer" default="0">
  Optional face crop offset.
</ResponseField>

<ResponseField name="extraMargin" type="integer" default="10">
  Optional extra face margin.
</ResponseField>

<ResponseField name="parsingMode" type="string" default="&#x22;jaw&#x22;">
  Optional parsing mode. Current default is `jaw`.
</ResponseField>

<ResponseField name="leftCheekWidth" type="integer" default="90">
  Optional left cheek blend width.
</ResponseField>

<ResponseField name="rightCheekWidth" type="integer" default="90">
  Optional right cheek blend width.
</ResponseField>

### Submit Example

<CodeGroup>
  ```bash curl theme={null}
  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"
  ```

  ```bash curl theme={null}
  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"
  ```
</CodeGroup>

### Submit Response

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

<ResponseField name="taskId" type="string">
  Unique task identifier used for polling and task history queries.
</ResponseField>

<ResponseField name="status" type="string">
  Initial task status. A successful submit returns `Processing`.
</ResponseField>

## Status Endpoint

```text theme={null}
GET /api/open/v1/video-compose/status
```

### Query Parameters

<ResponseField name="taskId" type="string" required>
  Task ID returned by the submit endpoint.
</ResponseField>

### Response Fields

<ResponseField name="taskId" type="string">
  Task ID.
</ResponseField>

<ResponseField name="status" type="string">
  Current task status. Common values:

  * `Draft`
  * `Processing`
  * `Published`
  * `Fail`
</ResponseField>

<ResponseField name="title" type="string">
  Task title, if one was supplied during submission.
</ResponseField>

<ResponseField name="videoUrl" type="string">
  Full public URL for the source visual asset associated with the task.
</ResponseField>

<ResponseField name="thumbnailUrl" type="string">
  Full public thumbnail URL when available.
</ResponseField>

<ResponseField name="audioUrl" type="string">
  Full public URL for the source audio used in the task.
</ResponseField>

<ResponseField name="resultUrl" type="string">
  Full public URL for the final generated video. Present when generation succeeds.
</ResponseField>

<ResponseField name="failMessage" type="string">
  Failure message when `status` is `Fail`.
</ResponseField>

<ResponseField name="prompt" type="string">
  The original `textContent` submitted for TTS tasks.
</ResponseField>

<ResponseField name="voice" type="string">
  Voice key bound to the avatar when TTS is used.
</ResponseField>

<ResponseField name="voiceName" type="string">
  Voice display name currently returned by the service.
</ResponseField>

<ResponseField name="avatarId" type="string">
  Avatar ID used for this task, if applicable.
</ResponseField>

### Status Example

```bash theme={null}
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

```text theme={null}
GET /api/open/v1/video-compose/list
```

### Query Parameters

<ResponseField name="page" type="integer" default="1">
  Page number.
</ResponseField>

<ResponseField name="size" type="integer" default="10">
  Page size.
</ResponseField>

### Response Shape

```json theme={null}
{
  "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