API Documentation

NovAI provides an OpenAI-compatible REST API. If you've used OpenAI's API before, you already know how to use NovAI — just change the base URL and API key.

Overview

NovAI is an AI API gateway based in Hong Kong, offering low-latency access to Chinese AI models through a unified, OpenAI-compatible interface.

Authentication

All API requests require an API key passed via the Authorization header:

Authorization: Bearer nvai-your-api-key-here

Get your API key by signing up at aiapi-pro.com. Registration requires only an email address.

Base URL

https://aiapi-pro.com/v1

Replace https://api.openai.com/v1 with the URL above in any existing OpenAI integration.

Available Models

Chat Models

Embedding Models

Quick Start Example

curl https://aiapi-pro.com/v1/chat/completions \
  -H "Authorization: Bearer nvai-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-4.6v-flash",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

API Playground TRY FREE — NO SIGNUP

Test the API right here in your browser. Uses the free GLM-4.6V-Flash model — no API key required.

Chat Completions

POST /v1/chat/completions

Creates a model response for the given conversation.

Request Body

Message Object

Example Request

curl https://aiapi-pro.com/v1/chat/completions \
  -H "Authorization: Bearer nvai-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello!"}
    ],
    "temperature": 0.7,
    "max_tokens": 500
  }'

Example Response

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1709942400,
  "model": "glm-5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 9,
    "total_tokens": 29
  }
}

Responses API NEW — EXCLUSIVE

POST /v1/responses

NovAI is the first and only API platform supporting OpenAI's new Responses API for Chinese AI models. This enables tools like Open Cowork, OpenAI Agents SDK, and any Responses API-based application to use GLM-5, MiniMax, and more China-exclusive models.

Request Body

Example: Simple Request

curl https://aiapi-pro.com/v1/responses \
  -H "Authorization: Bearer nvai-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5",
    "input": "Explain quantum computing simply.",
    "stream": false
  }'

Example: Conversation with Instructions

curl https://aiapi-pro.com/v1/responses \
  -H "Authorization: Bearer nvai-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5",
    "instructions": "You are a senior code reviewer.",
    "input": [
      {"role": "user", "content": "Review: def add(a,b): return a+b"}
    ],
    "stream": true
  }'

Example Response

{
  "id": "resp_abc123...",
  "object": "response",
  "status": "completed",
  "model": "glm-5",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {"type": "output_text", "text": "Quantum computing uses..."}
      ]
    }
  ],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 150,
    "total_tokens": 162
  }
}

Compatible Tools

The following tools work out of the box with NovAI's Responses API endpoint:

• Open Cowork — Set Base URL to https://aiapi-pro.com/v1
• OpenAI Agents SDK — Pass NovAI client to Runner
• OpenAI Python SDK (responses mode) — Set base_url
• Any custom application using POST /v1/responses

Read the full guide: Responses API for Chinese Models →

Embeddings NEW

POST /v1/embeddings

Creates a vector representation of the input, powered by Tencent Kinfra embedding models. Text models return 1024–2560 dimension vectors; multimodal (VL) models embed text, images and video in one shared space for cross-modal retrieval.

Available models

Request Body

Example Request (text)

curl https://aiapi-pro.com/v1/embeddings \
  -H "Authorization: Bearer nvai-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kinfra-text-embedding-4b",
    "input": "The quick brown fox"
  }'

Example Request (multimodal)

curl https://aiapi-pro.com/v1/embeddings \
  -H "Authorization: Bearer nvai-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kinfra-vl-embedding-8b",
    "input": [{"type": "text", "text": "a cat sitting on a mat"}]
  }'

Example Response

{
  "object": "list",
  "data": [
    {"object": "embedding", "index": 0, "embedding": [0.0023, -0.0091, ...]}
  ],
  "model": "kinfra-text-embedding-4b",
  "usage": {"prompt_tokens": 5, "total_tokens": 5}
}

Billing: only input tokens are charged (at the per-1M rate above); the returned vectors are free.

Image Generation NEW

POST /v1/images/generations

Generates images from a text prompt, powered by Tencent Hunyuan, Vidu, ByteDance Seedream and WAND Vega image models via the TokenHub gateway. Returns an OpenAI-compatible {created, data:[{url}]} response. Even for models that are asynchronous upstream, NovAI polls to completion internally and returns the final image URL synchronously.

Available models

Request Body

Example Request (text-to-image)

curl https://aiapi-pro.com/v1/images/generations \
  -H "Authorization: Bearer nvai-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hy-image-v3",
    "prompt": "a cute orange cat on a windowsill, soft sunlight",
    "size": "1024x1024",
    "n": 1
  }'

Example Request (image editing)

curl https://aiapi-pro.com/v1/images/generations \
  -H "Authorization: Bearer nvai-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "vidu-image-q2",
    "prompt": "change the background to a snowy mountain",
    "images": ["https://example.com/input.jpg"],
    "size": "1024x1024"
  }'

Example Response

{
  "created": 1730000000,
  "data": [
    {"url": "https://.../generated-image.png"}
  ],
  "usage": {"total_tokens": 20000}
}

Billing: the response usage.total_tokens reflects the real upstream token count; the charge is total_tokens / 1000 × token_price. For example, hy-image-v3 at 1024² returns ~20000 tokens ≈ $0.031. Async upstream models (Vidu, WAND Vega) are polled to completion (up to ~180s) before the URL is returned.

Audio NEW

Two OpenAI-compatible audio endpoints powered by MiniMax and Tencent models via the TokenHub gateway: /v1/audio/speech (text → audio: TTS + music) and /v1/audio/transcriptions (audio → text: ASR). Both are synchronous.

Speech & music models — POST /v1/audio/speech

Transcription models — POST /v1/audio/transcriptions

Speech request body

Example Request (TTS → audio URL)

curl https://aiapi-pro.com/v1/audio/speech \
  -H "Authorization: Bearer nvai-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-speech-2.8-hd",
    "input": "Hello, welcome to NovAI.",
    "voice": "male-qn-qingse",
    "response_format": "url"
  }'

Example Response (response_format=url)

{
  "id": "audgen-...",
  "model": "minimax-speech-2.8-hd",
  "status": "completed",
  "audio_url": "https://.../speech/....mp3",
  "usage": {"total_tokens": 1505, "characters": 43}
}

With the default response_format=mp3 the endpoint instead streams raw audio bytes (Content-Type: audio/mpeg), exactly like OpenAI’s native /v1/audio/speech — so the OpenAI SDK works unchanged.

Example Request (transcription)

# JSON form: transcribe from a URL
curl https://aiapi-pro.com/v1/audio/transcriptions \
  -H "Authorization: Bearer nvai-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model": "wand-asr-v1", "file_url": "https://example.com/audio.mp3"}'

# OpenAI multipart form: upload a file
curl https://aiapi-pro.com/v1/audio/transcriptions \
  -H "Authorization: Bearer nvai-your-key" \
  -F model=hy-asr-3.0-preview \
  -F [email protected]

Example Response (transcription)

{
  "text": "Hello, welcome to NovAI.",
  "language": "en",
  "duration_ms": 2426,
  "sentences": [{"begin_ms": 0, "end_ms": 2426, "text": "Hello, welcome to NovAI."}],
  "subtitle_url": "https://.../....srt",
  "usage": {"total_tokens": 121}
}

Billing: the charge is usage.total_tokens / 1000 × token_price (token_price = $0.0015385/1K). Transcription accepts either a multipart file upload (OpenAI-native) or a JSON file_url / base64 data field.

Video Generation NEW

POST /v1/video/generations  +  GET /v1/video/generations/{id}

Generates video from a text prompt (and optional source image), powered by MiniMax Hailuo and Tencent Hunyuan video models via the TokenHub gateway. Video generation is asynchronous: submit a task to get an id, then poll the GET endpoint until status is succeeded (the mp4 is in video_url) or failed (auto-refunded).

Available models

Submit request body

Example Request (text-to-video)

curl https://aiapi-pro.com/v1/video/generations \
  -H "Authorization: Bearer nvai-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-video-h3",
    "prompt": "A red sports car driving along a coastal road at sunset, cinematic",
    "resolution": "720p",
    "duration": 5,
    "ratio": "16:9"
  }'

Example Request (image-to-video)

curl https://aiapi-pro.com/v1/video/generations \
  -H "Authorization: Bearer nvai-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hy-video-v1.5",
    "prompt": "Animate this scene with smooth cinematic motion",
    "image": "https://example.com/first-frame.jpg",
    "duration": 5
  }'

Example Response (submit)

{
  "id": "<task_id>",
  "status": "queued",
  "model": "minimax-video-h3",
  "resolution": "720p",
  "duration": 5
}

Poll the task

curl "https://aiapi-pro.com/v1/video/generations/<task_id>?model=minimax-video-h3" \
  -H "Authorization: Bearer nvai-your-key"

Example Response (poll, completed)

{
  "id": "<task_id>",
  "status": "succeeded",
  "video_url": "https://.../output.mp4",
  "video_result": [{"url": "https://.../output.mp4"}],
  "duration": 5,
  "tokenhub_usage": {"total_tokens": 250000},
  "novai_token_settlement": {
    "prepaid_usd": 0.384625, "actual_usd": 0.384625,
    "adjustment_usd": 0.0, "total_tokens": 250000
  }
}

Billing: while status is queued/processing keep polling (generation typically takes 1–5 minutes). On succeeded the pre-deducted estimate is reconciled to the real token count and novai_token_settlement reports the adjustment. On failed/cancelled the pre-deducted amount is automatically refunded.

3D Generation NEW

POST /v1/three_d/generations  +  GET /v1/three_d/generations/{id}

Generates a 3D model (mesh) from a text prompt and/or a source image, powered by Tencent Hunyuan 3D and Tripo (VAST) models via the TokenHub gateway. 3D generation is asynchronous: submit a task to get an id, then poll the GET endpoint until status is succeeded (downloadable model URLs are in outputs, primary in model_url) or failed (auto-refunded).

Available models

Submit request body

Example Request (text-to-3D)

curl https://aiapi-pro.com/v1/three_d/generations \
  -H "Authorization: Bearer nvai-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hy-3d-3.1",
    "prompt": "a cute cartoon dog"
  }'

Example Request (image-to-3D)

curl https://aiapi-pro.com/v1/three_d/generations \
  -H "Authorization: Bearer nvai-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tripo-3d-3.1",
    "image": "https://example.com/object.png"
  }'

Example Response (submit)

{
  "id": "<task_id>",
  "request_id": "3dgen-...",
  "status": "queued",
  "model": "hy-3d-3.1"
}

Poll the task

curl "https://aiapi-pro.com/v1/three_d/generations/<task_id>?model=hy-3d-3.1" \
  -H "Authorization: Bearer nvai-your-key"

Example Response (poll, completed)

{
  "id": "<task_id>",
  "status": "succeeded",
  "upstream_status": "completed",
  "model_url": "https://.../model.glb",
  "outputs": [
    {"type": "obj", "url": "https://.../model.obj.zip", "preview_image_url": "https://.../preview.png"},
    {"type": "glb", "url": "https://.../model.glb", "preview_image_url": "https://.../preview.png"}
  ],
  "model": "hy-3d-3.1"
}

Billing: while status is queued/processing keep polling (generation typically takes 1–8 minutes). On succeeded the flat pre-deducted price is final (no token reconciliation). On failed/cancelled the pre-deducted amount is automatically refunded (novai_refund is reported in the response). model_url is the primary downloadable asset (glb preferred); outputs lists every available format.

Streaming

Set "stream": true to receive responses as Server-Sent Events (SSE):

curl https://aiapi-pro.com/v1/chat/completions \
  -H "Authorization: Bearer nvai-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": true
  }'

Each SSE event contains a JSON chunk with delta.content for the new token. The stream ends with [DONE].

List Models

GET /v1/models

Returns a list of all available models.

curl https://aiapi-pro.com/v1/models \
  -H "Authorization: Bearer nvai-your-key"

Error Codes

Rate Limits

Current rate limits per API key:

• Free models (glm-4.6v-flash): 30 requests/minute
• Paid models: 60 requests/minute

SDKs & Libraries

NovAI works with any OpenAI-compatible SDK. Just set the base URL:

Python

pip install openai

from openai import OpenAI
client = OpenAI(api_key="nvai-...", base_url="https://aiapi-pro.com/v1")

Node.js

npm install openai

import OpenAI from 'openai';
const client = new OpenAI({ apiKey: 'nvai-...', baseURL: 'https://aiapi-pro.com/v1' });

LangChain

from langchain_openai import ChatOpenAI
llm = ChatOpenAI(model="glm-5", openai_api_key="nvai-...", openai_api_base="https://aiapi-pro.com/v1")

Cursor IDE / Continue

Set base URL to https://aiapi-pro.com/v1 in your IDE settings. See our Cursor setup guide.

More examples: GitHub Repository | Blog & Tutorials

Supported Email Providers

Due to bot attacks targeting our free welcome credit, NovAI restricts new account registration to major email providers. This policy applies to new registrations only — all existing accounts are fully unaffected.

If your email provider is not listed below, please contact [email protected] for manual approval.

Note: Custom domain emails, dynamic DNS addresses, and temporary/disposable email services are not accepted. This restriction was introduced on June 24, 2026 to combat bot abuse. All 3,000+ users registered before this date are fully unaffected.