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 by allowing you to manage the resources needed for real-time conversations and video synthesis.

Real-time Digital Human API

WebSocket-based API for real-time conversations with digital humans

Video Synthesis API

Generate high-quality videos with digital human avatars

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

GET https://api.navtalk.ai/api/open/v1/provider/list?license=your-license-key

Method 2: License Header

curl https://api.navtalk.ai/api/open/v1/provider/list \
  -H "license: your-license-key"

You can obtain your license key from the NavTalk Dashboard.

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.

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

List Providers

GET /api/open/v1/provider/list

Example Response:

{
  "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

List Models

GET /api/open/v1/model/list?providerId={providerId}

Example Response:

{
  "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

List Voices

GET /api/open/v1/voice/list?providerId={providerId}

List Voices (Paginated)

GET /api/open/v1/voice/page?providerId={providerId}&page=1&size=20

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:

{
  "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

Add Avatar

Create a new avatar from video or image

List Avatars

Get all avatars for your account

Avatar Detail

Get detailed information about an avatar

Avatar Cover

Fetch the avatar cover image directly by avatar ID

Avatar Video

Fetch the avatar video directly by avatar ID

Update Avatar

Update avatar configuration

Check Status

Check avatar training status

Delete Avatar

Remove an avatar from your account

Avatar Creation Flow:

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.

Create Realtime Chat Connection

POST /api/open/v1/realtime-chat/connection

Additional Resources

File Upload

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

Upload File

POST /api/open/v1/file/upload

Typical Workflow

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

1. List Your Providers

   Call GET /api/open/v1/provider/list to see which AI providers you have connected.

2. 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)
3. Create an Avatar

   Upload a video or image and create an avatar:

   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."
   }
   
4. Check Training Status

   Poll the avatar training status:

   GET /api/open/v1/avatar/status?jobId={jobId}
   
5. Use Your Avatar

   Once training is complete, use your avatar in:

   • Real-time conversations

Need Help?

Real-time API Quick Start

Get started with real-time digital human conversations

Video Synthesis Quick Start

Learn how to generate videos with avatars

Custom Avatar Training

Create custom avatars from your own videos or images

Support

Contact our support team for assistance