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

# Introduction

> NavTalk REST API for managing AI providers, models, voices, avatars, and video generation

## Welcome to NavTalk API

The NavTalk REST API provides programmatic access to manage your AI providers, models, voices, digital human avatars, and video generation tasks. This API complements the [Real-time Digital Human API](/api/real-time-digital-human-api/overview) by allowing you to manage the resources needed for real-time conversations and video synthesis.

<CardGroup cols={2}>
  <Card title="Real-time Digital Human API" icon="comments" href="/api/real-time-digital-human-api/overview">
    WebSocket-based API for real-time conversations with digital humans
  </Card>

  <Card title="Video Synthesis API" icon="video" href="/api-reference/endpoint/navtalk/video-compose-submit">
    Generate high-quality videos with digital human avatars
  </Card>
</CardGroup>

## Base URL

```
https://api.navtalk.ai
```

**Alternative Environments:**

* QA Environment: `https://qaapi.navtalk.ai`
* Development Environment: `https://devapi.navtalk.ai`

## Authentication

All API endpoints require authentication using your NavTalk license key. You can provide the license key in two ways:

### Method 1: Query Parameter

```bash theme={null}
GET https://api.navtalk.ai/api/open/v1/provider/list?license=your-license-key
```

### Method 2: License Header

```bash theme={null}
curl https://api.navtalk.ai/api/open/v1/provider/list \
  -H "license: your-license-key"
```

<Note>
  You can obtain your license key from the [NavTalk Dashboard](https://console.navtalk.ai/#/projects).
</Note>

<Warning>
  Some API business errors may be returned with HTTP 200 and a JSON body such as `{ "code": 400, "message": "Invalid license key" }`. Always check both the HTTP status code and the response body `code`.
</Warning>

## Core Data Resources

The NavTalk API is organized around four core data resources that work together to create and manage digital human experiences.

### Providers

**Providers** represent the AI service providers (e.g., OpenAI, ElevenLabs) that you have connected to your NavTalk account.

* **Purpose**: Manage your connected AI providers
* **Usage**: Required when creating avatars or querying available models and voices
* **Key Fields**: `id`, `provider`, `name`, `scopeType`

<Card title="List Providers" icon="plug" href="/api-reference/endpoint/navtalk/provider-list">
  `GET /api/open/v1/provider/list`
</Card>

**Example Response:**

```json theme={null}
{
  "code": 200,
  "message": "SUCCESS",
  "data": [
    {
      "id": "b92a28fb2ea737457c7f13ba554759c0",
      "provider": "openai",
      "name": "My OpenAI Provider",
      "scopeType": "USER"
    },
    {
      "id": "a83b19ec1da626346b6e02a9443648d1",
      "provider": "elevenlabs",
      "name": "My ElevenLabs Provider",
      "scopeType": "USER"
    }
  ]
}
```

### Models

**Models** are the AI models available from each provider. Different models offer different capabilities, performance characteristics, and pricing.

* **Purpose**: Query available AI models for a specific provider
* **Usage**: Select a model when creating an avatar
* **Key Fields**: `id`, `model`, `provider`

<Card title="List Models" icon="brain" href="/api-reference/endpoint/navtalk/model-list">
  `GET /api/open/v1/model/list?providerId={providerId}`
</Card>

**Example Response:**

```json theme={null}
{
  "code": 200,
  "message": "SUCCESS",
  "data": [
    {
      "id": "agent_3201khcbet2vf349gpmtfg83q0hy",
      "model": "gpt-4o-realtime-preview-2024-12-17",
      "provider": "openai"
    }
  ]
}
```

### Voices

**Voices** are the text-to-speech voices available from each provider. Each voice has unique characteristics like tone, accent, and language support.

* **Purpose**: Query available voices for a specific provider
* **Usage**: Select a voice when creating an avatar
* **Key Fields**: `id`, `voice`, `provider`

<CardGroup cols={2}>
  <Card title="List Voices" icon="microphone" href="/api-reference/endpoint/navtalk/voice-list">
    `GET /api/open/v1/voice/list?providerId={providerId}`
  </Card>

  <Card title="List Voices (Paginated)" icon="list" href="/api-reference/endpoint/navtalk/voice-page">
    `GET /api/open/v1/voice/page?providerId={providerId}&page=1&size=20`
  </Card>
</CardGroup>

Use **`/voice/page`** when you have many voices and want to paginate (`size` is 1–100; cursor providers use `nextPageToken` from the response).

**Example Response:**

```json theme={null}
{
  "code": 200,
  "message": "SUCCESS",
  "data": [
    {
      "id": "CwhRBWXzGAHq8TQ4Fs17",
      "voice": "Rachel",
      "provider": "elevenlabs"
    },
    {
      "id": "ash",
      "voice": "ash",
      "provider": "openai"
    }
  ]
}
```

### Avatars

**Avatars** are digital human characters that you create and manage. Avatars can be created from videos or images and are used in real-time conversations and video synthesis.

* **Purpose**: Create, manage, and configure digital human avatars
* **Usage**: Use avatars in real-time conversations or video generation
* **Key Operations**: Create, List, Update, Delete, Check Status

<CardGroup cols={2}>
  <Card title="Add Avatar" icon="plus" href="/api-reference/endpoint/navtalk/avatar-add">
    Create a new avatar from video or image
  </Card>

  <Card title="List Avatars" icon="list" href="/api-reference/endpoint/navtalk/avatar-list">
    Get all avatars for your account
  </Card>

  <Card title="Avatar Detail" icon="info" href="/api-reference/endpoint/navtalk/avatar-detail">
    Get detailed information about an avatar
  </Card>

  <Card title="Avatar Cover" icon="image" href="/api-reference/endpoint/navtalk/avatar-cover">
    Fetch the avatar cover image directly by avatar ID
  </Card>

  <Card title="Avatar Video" icon="video" href="/api-reference/endpoint/navtalk/avatar-video">
    Fetch the avatar video directly by avatar ID
  </Card>

  <Card title="Update Avatar" icon="pen" href="/api-reference/endpoint/navtalk/avatar-update">
    Update avatar configuration
  </Card>

  <Card title="Check Status" icon="clock" href="/api-reference/endpoint/navtalk/avatar-status">
    Check avatar training status
  </Card>

  <Card title="Delete Avatar" icon="trash" href="/api-reference/endpoint/navtalk/avatar-delete">
    Remove an avatar from your account
  </Card>
</CardGroup>

**Avatar Creation Flow:**

```mermaid theme={null}
graph LR
    A[Upload Video/Image] --> B[Create Avatar]
    B --> C[Poll Status]
    C --> D{Training Complete?}
    D -->|No| C
    D -->|Yes| E[Use Avatar]
    E --> F[Real-time Chat]
    E --> G[Video Synthesis]
```

### Realtime Chat Connection

Use this REST endpoint to create a short-lived WebSocket URL before starting a realtime digital human session. The endpoint validates the license and avatar, then returns a `wsUrl` that connects to `/wss/v2/realtime-chat` with a generated token.

<Card title="Create Realtime Chat Connection" icon="link" href="/api-reference/endpoint/navtalk/realtime-chat-connection">
  `POST /api/open/v1/realtime-chat/connection`
</Card>

## Additional Resources

### File Upload

Upload media files (videos, images, audio) to NavTalk's storage for use in avatar creation and video generation.

<Card title="Upload File" icon="upload" href="/api-reference/endpoint/navtalk/file-upload">
  `POST /api/open/v1/file/upload`
</Card>

## Typical Workflow

Here's a typical workflow for getting started with the NavTalk API:

<Steps>
  <Step title="List Your Providers">
    Call `GET /api/open/v1/provider/list` to see which AI providers you have connected.
  </Step>

  <Step title="Query Available Models and Voices">
    For each provider, query available models and voices:

    * `GET /api/open/v1/model/list?providerId={providerId}`
    * `GET /api/open/v1/voice/list?providerId={providerId}` (full list)
    * `GET /api/open/v1/voice/page?providerId={providerId}&page=1&size=20` (paginated; use `nextPageToken` when `hasMore` is true for cursor-based providers)
  </Step>

  <Step title="Create an Avatar">
    Upload a video or image and create an avatar:

    ```bash theme={null}
    POST /api/open/v1/avatar/add
    {
      "name": "my-avatar",
      "url": "https://example.com/video.mp4",
      "providerId": "b92a28fb2ea737457c7f13ba554759c0",
      "model": "agent_3201khcbet2vf349gpmtfg83q0hy",
      "voice": "CwhRBWXzGAHq8TQ4Fs17",
      "firstMessage": "Hello!",
      "prompt": "You are a helpful assistant."
    }
    ```
  </Step>

  <Step title="Check Training Status">
    Poll the avatar training status:

    ```bash theme={null}
    GET /api/open/v1/avatar/status?jobId={jobId}
    ```
  </Step>

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

    * [Real-time conversations](/api/real-time-digital-human-api/overview)
  </Step>
</Steps>

## Need Help?

<CardGroup cols={2}>
  <Card title="Real-time API Quick Start" icon="rocket" href="/api/real-time-digital-human-api/quick-start/get-api-key">
    Get started with real-time digital human conversations
  </Card>

  <Card title="Video Synthesis Quick Start" icon="video" href="/api/video-synthesis-api/quick-start">
    Learn how to generate videos with avatars
  </Card>

  <Card title="Custom Avatar Training" icon="sparkles" href="/api/custom-avatar/overview">
    Create custom avatars from your own videos or images
  </Card>

  <Card title="Support" icon="life-ring" href="mailto:hi@navtalk.ai">
    Contact our support team for assistance
  </Card>
</CardGroup>