QVeris 模型网关

版本：2026-09-04

QVeris 模型网关提供 OpenAI 兼容的模型接口。使用你的 QVeris API Key 鉴权，调用成功后按实际用量从 QVeris Credits 结算。

接入地址

用途	地址
服务地址	`https://aigateway.qveris.ai`
OpenAI 兼容模型接口前缀	`https://aigateway.qveris.ai/v1`

模型接口以 /v1 开头，例如 https://aigateway.qveris.ai/v1/chat/completions。

前置条件

注册 QVeris 账号，并在账户 → API 密钥中创建 API Key（以 sk- 开头）。
账户可用 Credits 大于 0。调用成功后按实际用量扣费，明确失败不扣费。

查询可用模型

bash

export QVERIS_API_KEY='sk-你的密钥'

curl -sS https://aigateway.qveris.ai/v1/models \
  -H "Authorization: Bearer $QVERIS_API_KEY"

返回的 data[].id 就是调用时必须使用的公共模型 ID。请以 GET /v1/models 的运行时结果为准，不要写死供应商内部模型名。

普通对话

bash

curl -sS https://aigateway.qveris.ai/v1/chat/completions \
  -H "Authorization: Bearer $QVERIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {"role": "user", "content": "用一句话介绍你自己"}
    ],
    "max_tokens": 64
  }'

响应为标准 OpenAI Chat Completions 结构，并额外带有 qveris_billing 计费信息（见计费说明）。

如需流式输出，请求中加入 "stream": true。结算完成后，网关会在 data: [DONE] 前追加 event: qveris.billing 事件。

其他支持的模型接口

接口	用途
`POST /v1/responses`	OpenAI Responses 协议
`POST /v1/embeddings`	`GET /v1/models` 中具备 embeddings 能力的模型
`POST /v1/messages`	Anthropic 兼容客户端（`ANTHROPIC_BASE_URL` 指向 `https://aigateway.qveris.ai`）

仅当 GET /v1/models 返回的模型能力支持对应接口时才可调用。

鉴权与请求头

所有 /v1/* 请求都必须带：

http

Authorization: Bearer <QVeris API Key>

请求头	必需	说明
`Authorization`	是	QVeris API Key（`sk-` 前缀）
`Content-Type`	POST 必需	通常为 `application/json`
`X-Request-ID`	否	自定义请求 ID，最多 128 字符
`X-Qveris-Source`	否	调用来源标识，如 `playground`、`api`

每次调用请保存响应头 X-QVeris-Call-ID，它是审计、账单和排障的关联 ID。

计费说明

非流式成功响应会附加 qveris_billing：

json

{
  "qveris_billing": {
    "call_id": "d2ea8e43-dbb1-4846-ba1c-2acac1abadad",
    "credits_charged": 0.025,
    "cost_usd": 0.00005082,
    "credits_per_usd": 500,
    "usage_estimated": false,
    "pricing": {
      "mode": "expression",
      "prompt_usd_per_million_tokens": 0.22,
      "completion_usd_per_million_tokens": 0.66
    }
  }
}

要点：

当前汇率 1 USD = 500 Credits；
调用前只检查余额大于 0，成功后按实际 usage 结算，明确失败不扣费；
credits_charged 为实际扣除的 Credits，可能因最小精度与理论值略有差异；
usage_estimated=true 表示上游用量不完整，网关按保守估算结算；
最终账单以 QVeris 用量记录为准。

错误码

网关自身错误统一为：

json

{
  "error": {
    "message": "the requested model is not available",
    "type": "gateway_error",
    "code": "model_not_found"
  }
}

HTTP	`error.code`	含义	是否扣费
400	`invalid_request`	JSON 无效	否
401	`invalid_api_key`	Key 缺失、无效或已撤销	否
402	`insufficient_credits`	Credits 不足	否
404	`model_not_found`	模型 ID 不存在或未启用	否
413	`request_too_large`	请求体超限	否
422	`unsupported_model_capability`	模型不支持所调用接口	否
429	`rate_limit_exceeded`	超限流，响应带 `Retry-After`	否
503	`all_routes_unavailable`	模型路由暂不可用	否

常见问题

模型 ID 用哪个？ 用 GET /v1/models 返回的 id 字段。
返回 404？ 确认模型 ID 正确且已启用；目录每 30 秒热刷新。
返回 429？ 遵守响应头 Retry-After，降低并发。
如何排障？ 保存 X-QVeris-Call-ID 并提供给支持人员。
Key 安全？ 不要在文档、日志或工单中保存完整 Key，建议使用环境变量注入。