FAQ

Common questions and answers about NavTalk API

Account and Authentication

How do I obtain an API Key?

Please visit the console at console.navtalk.ai. After registering and logging in, you can generate your License Key on the “API Key Management” page.

Does the License have an expiration date? Can it be reset?

The License is valid indefinitely. If you believe it has been compromised, you can reset it immediately in the console.

Quick Start Questions

How can I quickly call the one-time synthesis interface?

Use the Video Synthesis API submit endpoint:

POST /api/open/v1/video-compose/submit

Provide exactly one audio input (audioFile, audioUrl, or textContent) and exactly one visual input (characterFile, characterUrl, or avatarId). For the common avatar TTS workflow, send avatarId and textContent.

The initial response returns a taskId:

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

Then poll GET /api/open/v1/video-compose/status?taskId={taskId} until the task reaches Published or Fail.

What are the minimum steps required for the real-time digital person to connect for the first time?

1. Choose either supported connection method:
   • REST token flow: call POST /api/open/v1/realtime-chat/connection with exactly one of avatarId or name, then connect to the returned wsUrl.
   • Direct WebSocket flow: connect to wss://transfer.navtalk.ai/wss/v2/realtime-chat with license and either name or avatarId in the URL.
2. Wait for conversation.connected.success event containing session ID and ICE servers.
3. Optionally send conversation history via conversation.item.create messages.
4. Capture microphone audio and send it via realtime.input_audio_buffer.append.
5. Receive AI response text/audio stream/video stream (WebRTC through the same connection).

You can download our complete code and run it directly.

Real-time WebSocket Connection Issues

What should I do if the WebSocket connection fails?

Please check:

• Is the license valid?
• Is the WebSocket address correct: wss://transfer.navtalk.ai/wss/v2/realtime-chat?
• If you use the REST token flow, are you connecting to the returned wsUrl before it expires?
• If you use the direct WebSocket flow, does the URL include license and either name or avatarId?
• Does Chrome allow microphone access?

Do I need to configure WebRTC to get the digital person's video on the webpage?

Yes, WebRTC is the only method for displaying video. Please ensure that after connecting to the WebSocket, you simultaneously establish a WebRTC video channel and bind it to the video tag to play.

Character and Behavior Settings

How do I specify the character settings and greeting of the digital person?

Please set this in the prompt field of the realtime.input_config message, for example:

socket.onopen = () => {
  const config = {
    voice: 'cedar',
    prompt: `You are a gentle psychological counselor.
Please respond in zh-CN.
Please greet with "Hello, I am your intelligent assistant."`,
    tools: []  // Optional: Function calling tools (OpenAI models only)
  };
  
  socket.send(JSON.stringify({
    type: 'realtime.input_config',
    data: { content: JSON.stringify(config) }
  }));
};

Can I specify the tone of the digital person? What are the options?

Yes, you can. Set it using voice: "nova", which supports the following 9 tones: alloy, shimmer, coral, echo, ballad, ash, sage, verse.

See Voice Styles for complete descriptions and audio previews.

Context and Memory Issues

How can I make the digital person remember the user's history of conversations?

Two methods are supported:

• Embed conversation context in the prompt field of realtime.input_config to simulate full context.
• Use conversation.item.create to send historical messages (only supports user messages) after receiving the realtime.session.created event.

Why can't the AI remember the previous conversation?

Please confirm:

• Does your realtime.input_config message include contextual content in the prompt field?
• Did you send conversation history using conversation.item.create after receiving realtime.session.created?

Function Call Issues

Why is there no response after configuring the function call?

• Please confirm that the tools parameter has been correctly registered.
• Check if you are listening for the realtime.response.function_call_arguments.done event.
• If the AI should continue after your business logic runs, send realtime.function_call_output with data.content, data.call_id, and data.reply: "1".

After the function call result is pushed, why is there no response from the AI?

For NavTalk clients, do not send a separate model-response trigger directly. Put reply: "1" on the realtime.function_call_output message:

socket.send(JSON.stringify({
  type: "realtime.function_call_output",
  data: {
    content: result,
    call_id: callId,
    reply: "1"
  }
}));

Media Interface Call Issues

How long will it take to receive results after synthesizing video and audio?

Generally, it can be completed within 5 to 30 seconds. Poll GET /api/open/v1/video-compose/status?taskId={taskId} until the response data.status is Published or Fail.

When generation succeeds, data.resultUrl contains the final generated video URL:

{
  "code": 200,
  "message": "SUCCESS",
  "data": {
    "taskId": "6d7e24b7-412d-46ec-8d95-940099a3e979",
    "status": "Published",
    "resultUrl": "https://api.navtalk.ai/uploadFiles/2026-05-18/final-result.mp4"
  }
}

Can I upload files directly?

It is recommended to upload audio and video files to a public cloud and use the URL for the call. If you need to use the platform’s upload feature, please log in to the console to get the upload link.