API 文档 — NavAPI

Quickstart

1 分钟跑通第一次调用。前提：已经注册账号并在个人中心 → API Key 拿到了一个 sk-nova-xxx。

# pip install openai
from openai import OpenAI

client = OpenAI(
    base_url="https://api.novaxml.com/v1",
    api_key="sk-nova-...",
)

resp = client.chat.completions.create(
    model="gpt-5",
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.choices[0].message.content)

// npm install openai
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.novaxml.com/v1",
  apiKey: "sk-nova-...",
});

const resp = await client.chat.completions.create({
  model: "gpt-5",
  messages: [{ role: "user", content: "Hello" }],
});
console.log(resp.choices[0].message.content);

curl https://api.novaxml.com/v1/chat/completions \
  -H "Authorization: Bearer sk-nova-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

鉴权

所有请求需在 HTTP Header 带上 Authorization: Bearer YOUR_API_KEY。Key 在个人中心 → API Key 创建。

每个账户可同时持有多个 key（生产 / 测试 / 子项目分开）
支持额度限制（按 key 设月度 / 总量上限）
支持模型白名单（限制某个 key 只能调指定模型）
支持IP 白名单（仅指定 IP 可用，防泄漏）
key 一旦丢失立即在控制台禁用并新建

模型列表

调用 GET /v1/models 获取你当前可用的所有模型。完整清单和定价见 Models 页和 Pricing 页。

GET/v1/models

错误码

HTTP	code	含义	建议
`400`	invalid_request	参数错误	检查 model / messages 字段
`401`	invalid_api_key	key 无效或被禁用	到个人中心查 key 状态
`402`	insufficient_balance	余额不足	充值后重试
`403`	content_policy_violation	触发内容审核	修改 prompt
`404`	model_not_found	模型不存在或未授权	检查模型名拼写
`429`	rate_limit_exceeded	触发限流	降低并发或升档
`500`	internal_error	平台内部错误	自动重试 3 次
`503`	model_unavailable	模型服务暂时不可用	系统会自动切换备用线路

Chat Completions

POST/v1/chat/completions

参数

参数	类型	说明
model required	string	如 gpt-5, claude-opus-4-7, gemini-2.5-pro
messages required	array	对话历史。role: system / user / assistant
stream	boolean	是否 SSE 流式（默认 false）
temperature	number	0–2，越高越随机（默认 1）
max_tokens	integer	最大输出 token
tools	array	function calling 定义

Images

生图（文生图）

POST/v1/images/generations

result = client.images.generate(
    model="nano-banana",
    prompt="a cute orange cat in a spacesuit on the moon",
    size="1024x1024",
    n=4,
)
for img in result.data:
    print(img.url)

curl https://api.novaxml.com/v1/images/generations \
  -H "Authorization: Bearer sk-nova-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana",
    "prompt": "a cute orange cat in a spacesuit on the moon",
    "size": "1024x1024",
    "n": 4
  }'

改图（图生图 / edit）

POST/v1/images/edits

支持 Nano Banana / GPT-Image-2 / 豆包 Seedream 等所有标注 edit 能力的模型。上传一张参考图 + prompt，输出修改后的版本。

with open("product.png", "rb") as f:
    result = client.images.edit(
        model="nano-banana",
        image=f,
        prompt="place on marble surface, natural lighting",
        n=3,
    )

Videos

视频接口接入中。当前网站已上线的是图片生成与下载流程；视频生成 API 还没有接入生产后端，下面是计划中的接口形态，正式开放前不会扣费。

POST/v1/videos/generations

GET/v1/videos/{job_id}

# 1. 提交任务
job = client.videos.create(
    model="kling-v3",
    prompt="slow rotation, product showcase, soft lighting",
    duration=6,
)

# 2. 轮询
while job.status != "completed":
    time.sleep(3)
    job = client.videos.retrieve(job.id)

print(job.output_url)  # mp4 直链

Audio

支持 STT（语音转文字）和 TTS（文字转语音）。

POST/v1/audio/transcriptions (Whisper)

POST/v1/audio/speech (TTS-HD, ElevenLabs, CosyVoice)

Embeddings

POST/v1/embeddings

支持 OpenAI text-embedding-3、BGE、M3E 等。

Streaming

设置 stream: true 启用 SSE 流式响应——打字机效果，首字延迟降低 80%。

stream = client.chat.completions.create(
    model="gpt-5",
    messages=[{"role": "user", "content": "Tell a story"}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Function Calling

所有标注 tools 能力的模型（GPT-5、Claude、Gemini、Qwen Max）均支持，行为与 OpenAI 完全一致。

Vision

带 vision 能力的模型可接收图片输入。在 messages 中传 image_url：

resp = client.chat.completions.create(
    model="gpt-5",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "What's in this image?"},
            {"type": "image_url", "image_url": {"url": "https://..."}},
        ],
    }],
)

Webhooks

异步事件（充值成功、视频生成完成、余额低）可推送到你指定的 URL。在个人中心 → API 设置配置 Webhook URL 和事件类型。

事件格式（带 HMAC 签名校验）：

{
  "event": "video.completed",
  "created_at": 1717420800,
  "data": {
    "id": "vid_abc123",
    "status": "completed",
    "output_url": "https://cdn.novaxml.com/...",
    "duration": 6
  }
}

限流

体验档：5 RPM（请求每分钟）
入门档：20 RPM
标准档：60 RPM
企业档：240 RPM 起，可议价提升
触发限流返回 429 + Retry-After 响应头

Python SDK

因为完全兼容 OpenAI 协议，直接用官方 openai 包即可。无需安装我们的独有 SDK。

pip install openai >= 1.30.0

Node.js SDK

npm install openai

cURL

任何 HTTP 工具都能调。Base URL 为 https://api.novaxml.com/v1。

需要帮助？发邮件到 [email protected] 或加帮助中心提工单。

开发者文档