API 文档

接口形态与 OpenAI Chat Completions 对齐，官方 SDK 改个 base_url 即可使用。

快速开始

1. 申请 API Key

在定价页提交申请，审核通过后邮件收到形如 sk-live-xxxxxxxx 的 Key。Key 只在发放时展示一次，请自行保存。

2. 发出第一个请求

curl https://YOUR-DOMAIN/v1/chat/completions \
  -H "Authorization: Bearer sk-live-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-vl",
    "messages": [
      {"role": "user", "content": "用一句话介绍你自己"}
    ],
    "max_tokens": 256
  }'

3. 用 OpenAI SDK

from openai import OpenAI

client = OpenAI(
    api_key="sk-live-xxxxxxxx",      # 建议从环境变量读取
    base_url="https://YOUR-DOMAIN/v1",
)

resp = client.chat.completions.create(
    model="qwen3-vl",
    messages=[{"role": "user", "content": "用一句话介绍你自己"}],
    max_tokens=256,
)
print(resp.choices[0].message.content)

鉴权

所有请求都需要在 Authorization 头里携带 Bearer Token：

Authorization: Bearer sk-live-xxxxxxxx

Key 与账号绑定，失效或被吊销后返回 401。发现 Key 泄露请立刻联系，会在后台吊销并补发新的。

端点一览

方法	路径	说明
POST	/v1/chat/completions	对话补全，支持图文与流式
GET	/v1/models	列出可用模型
GET	/api/health	健康检查，含模型与时延
GET	/v1/me	当前 Key 的套餐与剩余额度
GET	/v1/usage	用量查询，支持按日期区间

/v1/me 与 /v1/usage 属于控制台接口，形态与 OpenAI 不对应，单独说明。

模型与参数

请求体沿用 OpenAI 的字段名，常用参数如下：

参数	类型	说明
model	string	固定为 qwen3-vl
messages	array	对话历史，content 支持字符串或内容数组
max_tokens	integer	最大生成长度，默认 1024，上限 2048
temperature	number	0 到 1，默认 0.7
stream	boolean	为 true 时以 SSE 流式返回

图片输入

content 传数组时，文本用 type: "text"，图片用 type: "image_url"。图片来源有两种写法。

方式一：base64 内联

import base64, os
from openai import OpenAI

client = OpenAI(api_key=os.environ["QWEN_API_KEY"],
                base_url="https://YOUR-DOMAIN/v1")

with open("shot.png", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()

resp = client.chat.completions.create(
    model="qwen3-vl",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "这张图里有什么？"},
            {"type": "image_url",
             "image_url": {"url": f"data:image/png;base64,{b64}"}},
        ],
    }],
    max_tokens=512,
)
print(resp.choices[0].message.content)

方式二：公网图片地址

messages=[{
    "role": "user",
    "content": [
        {"type": "text", "text": "把这张图里的表格转成 JSON"},
        {"type": "image_url",
         "image_url": {"url": "https://example.com/table.png"}},
    ],
}]

用地址时服务端会去抓图，需要该地址对公网可访问。抓不到会返回 400，此时改用 base64。

流式输出

把 stream 设为 true，返回 text/event-stream：

import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["QWEN_API_KEY"],
                base_url="https://YOUR-DOMAIN/v1")

stream = client.chat.completions.create(
    model="qwen3-vl",
    messages=[{"role": "user", "content": "写一段关于视频检索的说明"}],
    stream=True,
    max_tokens=512,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Node.js 侧用法一致，把创建请求的 stream 设为 true 后遍历返回的异步迭代器即可。

错误码

状态码	含义	处理建议
400	请求格式有误	检查 messages 结构与图片格式
401	Key 无效或已吊销	确认 Key 是否写错、是否已停用
402	额度不足	补充余额或等待套餐刷新
413	请求体过大	压缩图片或裁剪文本
429	触发限流	按响应头 Retry-After 退避重试
503	模型繁忙或未就绪	稍后重试，或查看状态页

错误响应体统一为 { "error": { "message": "...", "type": "..." } }，message 可以直接展示给终端用户。

限流

套餐	每分钟请求	并发	单次上下文
Free	6	1	8192
Starter	30	2	8192
Pro	120	4	8192
Enterprise	协商	协商	协商

这是单机双卡的实际承载能力，不是随手写的数字。当前机器还要兼顾研究用途，峰值时段可能更慢，建议客户端做好重试与退避。

查询用量

curl https://YOUR-DOMAIN/v1/usage?start=2026-10-01&end=2026-10-31 \
  -H "Authorization: Bearer sk-live-xxxxxxxx"

返回该区间内的请求数、输入与输出 token、消耗额度与错误次数，可用于对账。