# 通用约定

> 鉴权方式、请求头、统一返回结构与错误码、流式输出、限流与计费口径。
> 分组：模型接入
> 更新时间：2026-10-12
> 原文：https://www.chenra.com/docs/model-conventions

## 鉴权

所有请求都要在请求头带上 API Key：

Authorization: Bearer sk-你的密钥

- 缺少或无效 → 401

- 密钥绑定的订阅已失效 / 已过期 → 403（去控制台续费即可恢复）

- 密钥只能调它所属产品的接口，跨产品使用同样按 401 处理

## 请求与响应

- 请求体一律 application/json；语音识别还支持 multipart/form-data 上传文件

- 响应体是 JSON；流式响应的 Content-Type 为 text/event-stream

- 时间字段是 Unix 秒级时间戳

## 错误结构

出错时返回 OpenAI 兼容的错误体，并带上对应的 HTTP 状态码：

{
 "error": {
 "message": "模型「xxx」不存在或未启用，可用清单见 GET /api/relay/v1/models",
 "type": "model_not_found",
 "code": null
 }
}

HTTP
type
含义

400
invalid_request_error
参数缺失或非法（缺 model / messages 等）

401
invalid_request_error
未带 Key，或 Key 无效 / 已删除

403
invalid_request_error
密钥绑定的订阅已失效

404
model_not_found
模型不存在或未启用

402
invalid_request_error
额度与余额都不足，无法计费

429
rate_limit_exceeded
超过这把密钥的每分钟请求上限

502
upstream_error
上游厂商报错（消息里带上游原文）

## 限流

每把 API Key 有一个「每分钟请求上限」（默认不限，由平台按会员设置）。
超出时返回 429，稍后重试即可。

## 流式输出

在请求体里加 "stream": true 即按 SSE 返回（data: {...} 行，以 data: [DONE] 结束）。
计费所需的用量由网关在流末尾自动补齐，客户端不用处理。

## 计费口径

按**实际用量**计费：Token（对话 / 向量 / 重排）、字符数（语音合成）、秒数（语音识别）、张数（文生图）。
优先扣产品额度（资源包），额度用尽后扣账户余额。每一把密钥的用量在控制台「API Key 管理」页逐把可查。