Documentation

API 文档

这里只保留鉴权、响应、错误码与限流等通用说明。具体接口请前往接口目录,避免数百个接口把文档页拉得过长。

浏览全部接口 → · 首次使用?先看使用指南 →

鉴权

公开接口无需凭证;“需凭证”接口支持登录令牌(Bearer)或 API Key,二选一。API Key 可以放在以下任一位置:

API Key

适合服务端调用。密钥只在创建时展示一次,可随时轮换或撤销。

header
x-api-key: oak_xxxxxxxx_yyyy

访问令牌

适合用户态调用。有效期 15 分钟,通过刷新令牌自动续期。

header
Authorization: Bearer eyJhbGciOi...

响应结构

所有接口使用同一个信封。code = 1 表示成功;失败时 code 为唯一负数(如 -10001),具体原因看 error_code。

success.json
{
  "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 判断错误。

error.json
{
  "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 的错误码,不完全适用本表。

codeerror_codeHTTP说明
-10001VALIDATION_FAILED400请求参数校验失败,details 指明具体字段
-10002BAD_REQUEST400请求不合法(一般性错误)
-10003UNAUTHORIZED401未登录或登录态无效
-10004TOKEN_EXPIRED401访问令牌已过期,请刷新或重新登录
-10005TOKEN_INVALID401令牌无效或已被撤销
-10006FORBIDDEN403没有权限执行该操作
-10007NOT_FOUND404资源不存在
-10008CONFLICT409资源冲突或当前状态不允许该操作
-10009RATE_LIMITED429触发频率限制,请读取 retry-after 后退避重试
-10010PAYLOAD_TOO_LARGE413请求体超过大小限制
-10011MAINTENANCE503平台维护中,请稍后再试
-10012INTERNAL_ERROR500服务端内部错误,凭 requestId 排查
-10013NOT_IMPLEMENTED501功能暂未实现
-10014SERVICE_UNAVAILABLE502/503依赖服务不可用或后端暂不可达
-11001REGISTRATION_DISABLED403注册通道已关闭
-11002LOGIN_INVALID_CREDENTIALS401/400邮箱或密码错误(改密场景为 400)
-11003LOGIN_LOCKED429登录失败次数过多,暂时锁定
-11004ACCOUNT_SUSPENDED401/403账号已被封禁或暂停
-11005OAUTH_DISABLED403第三方登录未开启
-11006OAUTH_BIND_DISABLED403第三方账号绑定未开启
-11007OAUTH_REGISTER_DISABLED403第三方注册未开启
-11008OAUTH_STATE_INVALID400OAuth state 无效或已过期
-11009OAUTH_EXCHANGE_FAILED502第三方授权交换失败
-11010PASSWORD_POLICY_VIOLATION400密码不符合安全策略
-11011EMAIL_TAKEN409邮箱已被注册
-11012EMAIL_NOT_VERIFIED403邮箱尚未验证
-11013EMAIL_CODE_INVALID400邮箱验证码错误或已过期
-11014CAPTCHA_REQUIRED400需要图形验证码
-11015CAPTCHA_INVALID400图形验证码错误
-11016POW_REQUIRED400需要完成人机校验
-11017POW_INVALID400人机校验结果无效
-11018SESSION_REVOKED401会话已失效,请重新登录
-11019TWO_FACTOR_REQUIRED401需要两步验证码(预留)
-11020TWO_FACTOR_INVALID400/401两步验证码错误
-11021TWO_FACTOR_ALREADY_ENABLED409两步验证已开启
-12001API_KEY_INVALID401API Key 不存在、格式错误或无效
-12002API_KEY_REVOKED401/400API Key 已撤销(密钥轮换场景为 400)
-12003API_KEY_EXPIRED401API Key 已过期
-12004API_KEY_NOT_YET_VALID401API Key 尚未生效
-12005IP_NOT_ALLOWED403调用 IP 不在 API Key 白名单内
-12006SCOPE_INSUFFICIENT403API Key 缺少所需权限
-12007QUOTA_EXCEEDED429今日调用额度已用尽
-13001ENDPOINT_NOT_FOUND404接口不存在或已下线
-13002ENDPOINT_DISABLED403接口已禁用(预留;当前禁用通常返回 ENDPOINT_NOT_FOUND)
-13003ENDPOINT_FORBIDDEN403无权调用该接口(预留)
-14001CSRF_TOKEN_MISSING403缺少 CSRF Token
-14002CSRF_TOKEN_INVALID403CSRF Token 不匹配
-14003RISK_BLOCKED403请求被风控拦截(预留)
-14004IP_BANNED403IP 已被临时限制访问
-14005RISK_RULE_BLOCKED403命中风控规则,请求被拦截
-14006MALICIOUS_REQUEST403非法或恶意请求
-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 后重试。