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

# FAQ

> Common questions and answers about NavTalk API

## Account and Authentication

<AccordionGroup>
  <Accordion title="How do I obtain an API Key?">
    Please visit the console at [console.navtalk.ai](https://console.navtalk.ai/login#/dashboard). After registering and logging in, you can generate your License Key on the "API Key Management" page.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Quick Start Questions

<AccordionGroup>
  <Accordion title="How can I quickly call the one-time synthesis interface?">
    Use the Video Synthesis API submit endpoint:

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

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

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Real-time WebSocket Connection Issues

<AccordionGroup>
  <Accordion title="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?
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Character and Behavior Settings

<AccordionGroup>
  <Accordion title="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:

    ```javascript theme={null}
    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) }
      }));
    };
    ```
  </Accordion>

  <Accordion title="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](/api/real-time-digital-human-api/voice-styles) for complete descriptions and audio previews.
  </Accordion>
</AccordionGroup>

## Context and Memory Issues

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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`?
  </Accordion>
</AccordionGroup>

## Function Call Issues

<AccordionGroup>
  <Accordion title="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"`.
  </Accordion>

  <Accordion title="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:

    ```javascript theme={null}
    socket.send(JSON.stringify({
      type: "realtime.function_call_output",
      data: {
        content: result,
        call_id: callId,
        reply: "1"
      }
    }));
    ```
  </Accordion>
</AccordionGroup>

## Media Interface Call Issues

<AccordionGroup>
  <Accordion title="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:

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

  <Accordion title="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.
  </Accordion>
</AccordionGroup>