API 参考

API 概览

NoviaHub 支持的接口协议、请求地址、鉴权方式、请求 ID、错误格式和不支持的接口。

NoviaHub 同时兼容三种接口协议：OpenAI、Anthropic 和 Google Gemini。你可以直接使用这三家的官方 SDK，只需把地址换成 NoviaHub，把密钥换成你在 NoviaHub 创建的 API 密钥。

接口一览

协议	接口	方法与路径
OpenAI	Chat Completions	`POST /v1/chat/completions`
OpenAI	Responses	`POST /v1/responses`
OpenAI	图片生成	`POST /v1/images/generations`
OpenAI	模型列表	`GET /v1/models`
Anthropic	Messages	`POST /v1/messages`
Anthropic	模型列表	`GET /v1/models`
Gemini	generateContent / streamGenerateContent	`POST /v1beta/models/{model}:generateContent`
Gemini	模型列表	`GET /v1beta/models`

完整地址 = https://noviahub.com + 路径，例如 https://noviahub.com/v1/chat/completions。

一个模型能用哪些接口，要看它在模型&价格页面上的端点标签，详见协议转换兼容性。

SDK 的 base URL 怎么填

各家 SDK 会自己在 base URL 后面拼接路径，所以三者的写法不一样：

SDK	base URL	说明
OpenAI 官方 SDK（Python / Node.js 等）	`https://noviahub.com/v1`	要带 `/v1`
Anthropic 官方 SDK	`https://noviahub.com`	不要带 `/v1`，SDK 会自己拼 `/v1/messages`
Google Gen AI SDK	`https://noviahub.com`	不要带 `/v1beta`，SDK 会自己拼 `/v1beta/models/...`

鉴权：把 API 密钥放在哪

每个请求都要带上 API 密钥。NoviaHub 认以下几种写法，但各写法只在特定路径上有效：

写法	在哪些路径有效
请求头 `Authorization: Bearer <密钥>`	所有接口（推荐）
请求头 `x-api-key: <密钥>`	仅路径中含 `/v1/messages` 或 `/v1/models` 的接口
请求头 `x-goog-api-key: <密钥>`	仅 `/v1/models`、`/v1beta/models`、`/v1beta/openai/models` 开头的接口
查询参数 `?key=<密钥>`	同上，仅 `/v1/models`、`/v1beta/models`、`/v1beta/openai/models` 开头的接口

几点实测过的细节：

密钥前面的 sk- 可带可不带：Bearer sk-abc... 和 Bearer abc... 都能用。
Authorization 里省略 Bearer 前缀、直接写密钥，也能用。
在不支持的路径上用 x-api-key 或 x-goog-api-key（例如对 /v1/chat/completions 使用 x-api-key），会被当成没带密钥，返回 401。
不要在密钥后面追加 -数字（如 sk-abc...-1）。普通用户这样写会返回 403「普通用户不支持指定渠道」。

请求 ID

每个响应都带有响应头 X-Oneapi-Request-Id，值是本次请求的 ID。出错时，错误信息末尾也会附上 (request id: ...)。向我们反馈问题时，请把这个 ID 一起发来，便于排查。在控制台「使用日志」里点开某条记录，也能看到它的「请求 ID」。

错误格式

出错时 HTTP 状态码不是 200，响应体是 JSON，有两种结构。

OpenAI 结构：OpenAI 和 Gemini 接口的所有错误，以及所有接口在鉴权、选择模型、限流阶段的错误（包括 /v1/messages）都用这种结构。

{
  "error": {
    "message": "field messages is required (request id: 2026...)",
    "type": "new_api_error",
    "param": "",
    "code": "invalid_request"
  }
}

Anthropic 结构：/v1/messages 在通过鉴权和选择模型之后出的错用这种结构。

{
  "error": {
    "type": "new_api_error",
    "message": "用户额度不足, 剩余额度: ＄0.000000 (request id: 2026...)"
  },
  "type": "error"
}

如果错误来自上游模型服务，NoviaHub 会原样转回上游的 HTTP 状态码和错误内容；上游给出的 Retry-After 响应头也会一起转回。
可以用请求头 Accept-Language 选择错误信息的语言。例如带上 Accept-Language: zh-CN 时，密钥无效的提示是「无效的令牌」；不带时是英文 Invalid token。但有些错误信息目前只有中文，例如余额不足、IP 不在白名单。

常见错误的含义和处理方法，见错误码与排查。

其他限制

请求体大小：网关对单个请求体的大小有上限，程序默认值为 128 MB，超出时返回 413。
流式输出空闲超时：流式请求时，如果上游连续一段时间没有输出任何数据，网关会结束这次流式响应。程序默认等待 300 秒。

以上两个数值是程序默认值，平台可能调整，以实际返回为准。

不支持的接口

以下接口 NoviaHub 目前不提供，调用会直接返回错误（本地测试环境实测）：

接口	实际返回
`POST /v1/messages/count_tokens`（Anthropic 计算 token）	404，`Invalid URL (POST /v1/messages/count_tokens)`
`POST /v1beta/models/{model}:countTokens`（Gemini 计算 token）	404，`Invalid URL (...)`
`/v1/files`、`/v1/fine-tunes`、`/v1/images/variations`	400，`Model name not specified, model name cannot be empty`
其他未列出的 `/v1/...` 路径	404，`Invalid URL (方法路径)`

另外，NoviaHub 目前没有上线向量（Embeddings）、重排（Rerank）、语音、视频类模型。调用这些接口时，会因为「没有可用渠道」返回 503。