跳转到内容
NoviaHub 文档

OpenAI 兼容

Chat Completions

用 OpenAI Chat Completions 格式调用 NoviaHub 上的模型：地址、请求头、请求参数、响应、流式输出和示例代码。

与 OpenAI 的 Create chat completion 接口兼容，是最通用的调用方式：几乎所有模型都可以用它调用（模型的端点标签里有 Chat 即可，见协议转换兼容性）。

POST https://noviahub.com/v1/chat/completions

请求头

Section titled “请求头”
请求头 必填 说明
Authorization 是 Bearer <你的 API 密钥>
Content-Type 是 application/json

请求参数

Section titled “请求参数”

下表列出 NoviaHub 能识别并转发的主要参数。某个参数最终是否生效，取决于你调用的模型本身支持不支持；模型不支持的参数可能被忽略，也可能导致上游报错。

参数 类型 必填 说明
model string 是 模型 ID，例如 deepseek-v4-flash。可用 ID 见模型&价格。
messages array 是 对话消息列表，结构见下文。
stream boolean 否 true 时以流式（SSE）返回，见流式输出。
stream_options object 否 流式选项。include_usage：是否在最后返回用量，NoviaHub 默认为 true。
max_tokens integer 否 最多生成多少 token。
max_completion_tokens integer 否 最多生成多少 token（含思考部分），OpenAI 较新的写法。
temperature number 否 采样温度，越高越随机。
top_p number 否 核采样。
top_k integer 否 Top-K 采样（部分模型支持）。
stop string / array 否 遇到这些字符串时停止生成。
n integer 否 一次生成几个候选回复。
frequency_penalty number 否 频率惩罚。
presence_penalty number 否 存在惩罚。
seed number 否 随机种子。
response_format object 否 输出格式，如 {"type": "json_object"}，或 {"type": "json_schema", "json_schema": {...}}。
tools array 否 可供模型调用的工具（函数），每项形如 {"type": "function", "function": {"name", "description", "parameters", "strict"}}。
tool_choice string / object 否 控制是否以及调用哪个工具。
parallel_tool_calls boolean 否 是否允许一次调用多个工具。
reasoning_effort string 否 思考强度（推理模型支持），如 low、medium、high。
logprobs boolean 否 是否返回每个 token 的概率。
top_logprobs integer 否 每个位置返回几个候选 token 的概率。
web_search_options object 否 联网搜索选项（支持的模型）：search_context_size、user_location。
prompt_cache_key string 否 提示缓存的键（支持的模型）。
user、metadata — 否 用户标识和附加信息，原样转发。

除上表外，NoviaHub 还能识别并转发这些字段：modalities、audio、prediction、logit_bias、store、prompt_cache_retention、verbosity、reasoning、extra_body，以及部分模型厂商自己的扩展字段（如 enable_thinking、thinking_budget、chat_template_kwargs、thinking）。

messages 的结构

Section titled “messages 的结构”

每条消息是一个对象：

字段 说明
role 角色：system、developer、user、assistant、tool。
content 文本字符串；或一个数组，用于混合文字、图片等内容，见下方。
name 可选，发言者名称。
tool_calls assistant 消息中模型发起的工具调用。
tool_call_id tool 消息中，对应哪一次工具调用。

content 写成数组时，每一项的 type 可以是 text（配合 text 字段）、image_url（配合 image_url: {"url": "...", "detail": "..."}）、input_audio、file 或 video_url。模型是否能看图、听音频，请看它在模型&价格页面上的「输入类型」。

示例代码

Section titled “示例代码”
终端窗口
curl https://noviahub.com/v1/chat/completions \
  -H "Authorization: Bearer $NOVIAHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {"role": "system", "content": "你是一个简洁的助手。"},
      {"role": "user", "content": "用一句话解释什么是 API。"}
    ]
  }'

响应

Section titled “响应”
字段 说明
id 本次回复的 ID。
object 固定为 chat.completion。
created 创建时间（Unix 秒）。
model 模型 ID。
choices[].message.content 模型的回答。
choices[].message.tool_calls 模型要求调用的工具（如果有）。
choices[].message.reasoning_content 部分模型会在这里返回思考内容。
choices[].finish_reason 停止原因，如 stop（正常结束）、length（达到长度上限）、tool_calls（要调用工具）。
usage.prompt_tokens 输入 token 数。
usage.completion_tokens 输出 token 数。
usage.total_tokens 合计。
示例响应（本地测试环境，内容由模拟上游生成）
{
  "id": "chatcmpl-mock123",
  "object": "chat.completion",
  "created": 1790609866,
  "model": "deepseek-v4-flash",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hello from the mock upstream." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 12, "completion_tokens": 7, "total_tokens": 19 }
}

通过协议转换调用的模型（例如用本接口调 Claude 或 Gemini 模型），usage 里还会多出一些网关内部字段，可以忽略，见协议转换兼容性。

流式输出

Section titled “流式输出”

请求里加 "stream": true，响应会以 SSE（Server-Sent Events）逐段返回。每段以 data: 开头，内容是一个 chat.completion.chunk 对象，新生成的文字在 choices[0].delta.content 里；最后一行是 data: [DONE]。

NoviaHub 默认会在 [DONE] 之前多发一段只含用量的数据（choices 为空数组，带 usage），即使你没有传 stream_options。不需要这一段时，传 "stream_options": {"include_usage": false}。

示例流式响应（本地测试环境）
data: {"id":"chatcmpl-mock123","object":"chat.completion.chunk","created":1790609866,"model":"deepseek-v4-flash","choices":[{"index":0,"delta":{"content":"Hello","role":"assistant"},"finish_reason":null}]}


data: {"id":"chatcmpl-mock123","object":"chat.completion.chunk","created":1790609866,"model":"deepseek-v4-flash","choices":[{"index":0,"delta":{"content":" from the mock upstream."},"finish_reason":null}]}


data: {"id":"chatcmpl-mock123","object":"chat.completion.chunk","created":1790609866,"model":"deepseek-v4-flash","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}


data: {"id":"chatcmpl-mock123","object":"chat.completion.chunk","created":1790609866,"model":"deepseek-v4-flash","choices":[],"usage":{"prompt_tokens":12,"completion_tokens":7,"total_tokens":19}}


data: [DONE]
终端窗口
curl https://noviahub.com/v1/chat/completions \
  -H "Authorization: Bearer $NOVIAHUB_API_KEY" \
  -H "Content-Type: application/json" \
  -N \
  -d '{
    "model": "deepseek-v4-flash",
    "stream": true,
    "messages": [{"role": "user", "content": "写一首四句的短诗。"}]
  }'

注意最后那段用量数据的 choices 是空数组，所以读取 choices[0] 前要先判断，如上面示例所示。

常见错误

Section titled “常见错误”
HTTP 状态码 原因
400 缺少 model（Model name not specified...）、缺少 messages（field messages is required）或请求体不是合法 JSON。
401 密钥无效、已禁用、已过期或额度已用完（Invalid token）。
403 密钥不允许使用这个模型、IP 不在白名单，或账户余额不足。
503 模型 ID 写错，或该模型当前没有可用线路（No available channel for model ...）。

完整说明见错误码与排查。