API 文档
这里只保留鉴权、响应、错误码与限流等通用说明。具体接口请前往接口目录,避免数百个接口把文档页拉得过长。
鉴权
公开接口无需凭证;“需凭证”接口支持登录令牌(Bearer)或 API Key,二选一。API Key 可以放在以下任一位置:
API Key
适合服务端调用。密钥只在创建时展示一次,可随时轮换或撤销。
x-api-key: oak_xxxxxxxx_yyyy访问令牌
适合用户态调用。有效期 15 分钟,通过刷新令牌自动续期。
Authorization: Bearer eyJhbGciOi...x-api-key 头最安全,推荐服务端使用; Cookie: oiapi_api_key=oak_... 适合同源页面调试; ?api_key=oak_... 仅建议本地临时调试,可能被访问日志、浏览器历史或 Referer 记录。 也支持 Authorization: ApiKey oak_...。
响应结构
所有接口使用同一个信封。code = 1 表示成功;失败时 code 为唯一负数(如 -10001),具体原因看 error_code。
{
"code": 1,
"message": "ok",
"data": {
"characters": 14,
"words": 2
},
"meta": {
"requestId": "0586d82e-38b4-47ef-8697-b788f8c34390",
"timestamp": "2026-11-11T19: 11: 32.008Z",
"reqTimestamp": 1794245766182,
"durationMs": 1
}
} 业务字段只有 code / message / data 和错误时的 error_code / details; 成功时 data 恒为对象:列表在 data.items,标量在 data.value; meta.timestamp 是响应生成时间,meta.reqTimestamp 是请求进入服务端的时间, meta.requestId 用于排查问题,接口附加信息也统一放在 meta。
错误处理
HTTP 状态码表示错误大类;信封里的 code 是唯一负数, error_code 是稳定的可读字符串,message 可直接展示给用户。 客户端请按 error_code(或数字 code)分支处理, 不要再用 code === 0 判断错误。
{
"code": -10001,
"message": "请求参数校验失败",
"data": null,
"error_code": "VALIDATION_FAILED",
"details": [
{
"path": "/text",
"message": "缺少必填参数:text",
"code": "required"
},
{
"path": "/count",
"message": "不能大于 100",
"code": "maximum"
}
],
"meta": {
"requestId": "0586d82e-38b4-47ef-8697-b788f8c34390",
"timestamp": "2026-11-11T19: 11: 32.008Z",
"reqTimestamp": 1794245766182,
"method": "POST",
"path": "/v1/text/stats",
"statusCode": 400,
"timezone": "UTC"
}
} 失败响应同样在 meta 里附带 requestId、请求方法/路径、状态码与 UTC 时间, 所有字段都是排障用的,不影响业务逻辑。
details:字段级错误
参数校验失败时 details 是数组,每项包含 path / message / code:
| 字段 | 说明 | 示例 |
|---|---|---|
| path | 出错字段的 JSON Pointer;嵌套字段形如 /user/name,缺失字段也会给出。 | /text |
| message | 已本地化为中文、可直接展示的错误说明。 | 缺少必填参数:text |
| code | 校验关键字,便于程序判断:required / type / minLength / maxLength / pattern / format / enum / minimum / maximum 等。 | required |
排查信息:requestId / path / status / 时间
meta.requestId:本次请求的唯一 ID,同时也写入响应头x-request-id。报障时请优先提供它。meta.path:失败请求的路径(不含 query,避免敏感参数进入日志)。meta.statusCode:实际 HTTP 状态码,与响应状态一致。meta.timestamp:错误发生时间(ISO 8601,UTC);meta.reqTimestamp:请求进入服务端的毫秒时间戳;meta.timezone固定为UTC。- 把
requestId + path + timestamp一起发给平台,可以快速关联调用日志与错误日志; 管理员也可直接打开 /admin/logs?requestId=你的ID 查询调用记录(需管理员登录)。浏览器调试时也可在响应头里读到同一个 requestId。
错误码
数字 code 按模块分段:-100xx 通用、 -110xx 认证与账号、-120xx API Key 与额度、 -130xx 接口状态、-140xx 安全与风控。 未登记的错误码统一为 -19999(error_code 仍返回原始字符串)。 本表适用于 /v1/*、/v1/gateway/* 与内部指标接口; 旧兼容入口 /api/<ename> 可能沿用旧 Provider 的错误码,不完全适用本表。
| code | error_code | HTTP | 说明 |
|---|---|---|---|
| -10001 | VALIDATION_FAILED | 400 | 请求参数校验失败,details 指明具体字段 |
| -10002 | BAD_REQUEST | 400 | 请求不合法(一般性错误) |
| -10003 | UNAUTHORIZED | 401 | 未登录或登录态无效 |
| -10004 | TOKEN_EXPIRED | 401 | 访问令牌已过期,请刷新或重新登录 |
| -10005 | TOKEN_INVALID | 401 | 令牌无效或已被撤销 |
| -10006 | FORBIDDEN | 403 | 没有权限执行该操作 |
| -10007 | NOT_FOUND | 404 | 资源不存在 |
| -10008 | CONFLICT | 409 | 资源冲突或当前状态不允许该操作 |
| -10009 | RATE_LIMITED | 429 | 触发频率限制,请读取 retry-after 后退避重试 |
| -10010 | PAYLOAD_TOO_LARGE | 413 | 请求体超过大小限制 |
| -10011 | MAINTENANCE | 503 | 平台维护中,请稍后再试 |
| -10012 | INTERNAL_ERROR | 500 | 服务端内部错误,凭 requestId 排查 |
| -10013 | NOT_IMPLEMENTED | 501 | 功能暂未实现 |
| -10014 | SERVICE_UNAVAILABLE | 502/503 | 依赖服务不可用或后端暂不可达 |
| -11001 | REGISTRATION_DISABLED | 403 | 注册通道已关闭 |
| -11002 | LOGIN_INVALID_CREDENTIALS | 401/400 | 邮箱或密码错误(改密场景为 400) |
| -11003 | LOGIN_LOCKED | 429 | 登录失败次数过多,暂时锁定 |
| -11004 | ACCOUNT_SUSPENDED | 401/403 | 账号已被封禁或暂停 |
| -11005 | OAUTH_DISABLED | 403 | 第三方登录未开启 |
| -11006 | OAUTH_BIND_DISABLED | 403 | 第三方账号绑定未开启 |
| -11007 | OAUTH_REGISTER_DISABLED | 403 | 第三方注册未开启 |
| -11008 | OAUTH_STATE_INVALID | 400 | OAuth state 无效或已过期 |
| -11009 | OAUTH_EXCHANGE_FAILED | 502 | 第三方授权交换失败 |
| -11010 | PASSWORD_POLICY_VIOLATION | 400 | 密码不符合安全策略 |
| -11011 | EMAIL_TAKEN | 409 | 邮箱已被注册 |
| -11012 | EMAIL_NOT_VERIFIED | 403 | 邮箱尚未验证 |
| -11013 | EMAIL_CODE_INVALID | 400 | 邮箱验证码错误或已过期 |
| -11014 | CAPTCHA_REQUIRED | 400 | 需要图形验证码 |
| -11015 | CAPTCHA_INVALID | 400 | 图形验证码错误 |
| -11016 | POW_REQUIRED | 400 | 需要完成人机校验 |
| -11017 | POW_INVALID | 400 | 人机校验结果无效 |
| -11018 | SESSION_REVOKED | 401 | 会话已失效,请重新登录 |
| -11019 | TWO_FACTOR_REQUIRED | 401 | 需要两步验证码(预留) |
| -11020 | TWO_FACTOR_INVALID | 400/401 | 两步验证码错误 |
| -11021 | TWO_FACTOR_ALREADY_ENABLED | 409 | 两步验证已开启 |
| -12001 | API_KEY_INVALID | 401 | API Key 不存在、格式错误或无效 |
| -12002 | API_KEY_REVOKED | 401/400 | API Key 已撤销(密钥轮换场景为 400) |
| -12003 | API_KEY_EXPIRED | 401 | API Key 已过期 |
| -12004 | API_KEY_NOT_YET_VALID | 401 | API Key 尚未生效 |
| -12005 | IP_NOT_ALLOWED | 403 | 调用 IP 不在 API Key 白名单内 |
| -12006 | SCOPE_INSUFFICIENT | 403 | API Key 缺少所需权限 |
| -12007 | QUOTA_EXCEEDED | 429 | 今日调用额度已用尽 |
| -13001 | ENDPOINT_NOT_FOUND | 404 | 接口不存在或已下线 |
| -13002 | ENDPOINT_DISABLED | 403 | 接口已禁用(预留;当前禁用通常返回 ENDPOINT_NOT_FOUND) |
| -13003 | ENDPOINT_FORBIDDEN | 403 | 无权调用该接口(预留) |
| -14001 | CSRF_TOKEN_MISSING | 403 | 缺少 CSRF Token |
| -14002 | CSRF_TOKEN_INVALID | 403 | CSRF Token 不匹配 |
| -14003 | RISK_BLOCKED | 403 | 请求被风控拦截(预留) |
| -14004 | IP_BANNED | 403 | IP 已被临时限制访问 |
| -14005 | RISK_RULE_BLOCKED | 403 | 命中风控规则,请求被拦截 |
| -14006 | MALICIOUS_REQUEST | 403 | 非法或恶意请求 |
| -19999 | (原始字符串) | — | 未登记错误码的兜底数字,error_code 保留原始值 |
“HTTP”列是典型值,极少数场景可能不同(例如 ACCOUNT_SUSPENDED 续期时为 401、调用接口时为 403)。 请优先按 error_code / 数字 code 判断,不要只看 HTTP 状态码。
限流与额度
公开接口默认不限调用次数,只有显式配置了限流/额度或需要 API Key 的接口才受限。响应头会返回当前剩余量: x-ratelimit-limit、x-ratelimit-remaining、 x-quota-remaining。触发限制时请读取 retry-after 后重试。
meta.requestId 与平台支持对齐问题。