场景
适用场景
这个接口适合用在什么地方？下面的场景可以帮你判断它是不是你要找的那个。
- 第三方应用拿到 access_token 后，先调用这个接口确认凭证有效、额度还剩多少。
- 前端页面在启动时判断用户是否已登录。
- 开发者调试自己签发的 API Key 是否配置正确。
问答
常见问题
接入时最常遇到的疑问，先看看这里能不能解答。
为什么调用这个接口也能看到额度？
额度信息通过 x-api-remain、x-api-cost 和可选的 Retry-After 响应头返回，不放在 JSON 响应体里。
issuer 字段表示什么？
它说明这份凭证是怎么来的：webapp 表示网页登录会话，api 表示站内签发的 API Key，oauth 表示通过 OAuth 授权拿到的 access_token。
扣费
扣费规则
每次请求按固定额度扣费，不随返回条数变化。
固定 1 点额度/次
实际扣费以响应头 x-api-cost 为准。
请求说明
参数
准备就绪
当前接口没有额外请求参数
响应说明
状态码与响应格式
200
当前鉴权会话信息。
响应头
x-api-remainx-api-costRetry-After
application/jsonobject
响应结构
{
"type": "object",
"required": [
"ok",
"data",
"error"
],
"properties": {
"ok": {
"type": "true",
"required": true,
"enum": [
true
]
},
"data": {
"type": "object",
"required": true,
"shape": {
"type": "object",
"properties": {
"user": {
"type": "object",
"shape": {
"type": "object",
"required": [
"userId"
],
"properties": {
"userId": {
"type": "string",
"required": true
}
}
}
},
"apiKey": {
"type": "object",
"shape": {
"type": "object",
"required": [
"revokeId",
"issuer",
"maskedApiKey",
"activeFrom",
"expiresAt",
"dailyTokenLimit",
"scopes"
],
"properties": {
"revokeId": {
"type": "string",
"required": true
},
"issuer": {
"type": "unspecified | webapp | api | oauth",
"required": true,
"enum": [
"unspecified",
"webapp",
"api",
"oauth"
]
},
"maskedApiKey": {
"type": "string",
"required": true
},
"activeFrom": {
"type": "integer",
"required": true
},
"expiresAt": {
"type": "integer",
"required": true
},
"dailyTokenLimit": {
"type": "integer",
"required": true
},
"scopes": {
"type": "array<string>",
"required": true,
"shape": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
},
"quota": {
"type": "object",
"shape": {
"type": "object",
"required": [
"tokenLimit",
"remain",
"refillAmount",
"refillIntervalSeconds"
],
"properties": {
"tokenLimit": {
"type": "integer",
"required": true
},
"remain": {
"type": "integer",
"required": true
},
"refillAmount": {
"type": "integer",
"required": true
},
"refillIntervalSeconds": {
"type": "integer",
"required": true
},
"nextRefillAt": {
"type": "integer"
}
}
}
}
}
}
},
"error": {
"type": "",
"required": true,
"enum": [
""
]
}
}
}示例响应
{
"ok": true,
"data": {
"user": {
"userId": "demo-user"
},
"apiKey": {
"revokeId": "ocrh_revoke_9f4f1c8c4d5a4f43",
"issuer": "webapp",
"maskedApiKey": "ocrh_u_abc***xyz",
"activeFrom": 1786636800,
"expiresAt": 1789228800,
"dailyTokenLimit": 2000,
"scopes": [
"api.auth.me.read",
"api.records.daily.read"
]
},
"quota": {
"tokenLimit": 2000,
"remain": 1999,
"refillAmount": 10,
"refillIntervalSeconds": 300,
"nextRefillAt": 1786637100
}
},
"error": ""
}401
请求未携带有效的认证信息，或提供的 API Key 已失效。
响应头
x-api-remainx-api-costRetry-After
application/jsonobject
响应结构
{
"type": "object",
"required": [
"ok",
"data",
"error"
],
"properties": {
"ok": {
"type": "false",
"required": true,
"enum": [
false
]
},
"data": {
"type": "string",
"required": true
},
"error": {
"type": "string",
"required": true
}
}
}示例响应
{
"ok": false,
"data": "API Key 无效或已过期",
"error": "invalid_api_key"
}403
账号已被封禁。；当前凭证缺少调用该接口所需的 scope。；当前身份的额度上限低于接口最低调用成本。
响应头
x-api-remainx-api-costRetry-After
application/jsonobject
响应结构
{
"type": "object",
"required": [
"ok",
"data",
"error"
],
"properties": {
"ok": {
"type": "false",
"required": true,
"enum": [
false
]
},
"data": {
"type": "string",
"required": true
},
"error": {
"type": "string",
"required": true
}
}
}账号已被封禁。
{
"ok": false,
"data": "账号已被封禁",
"error": "account_banned"
}当前凭证缺少调用该接口所需的 scope。
{
"ok": false,
"data": "当前 API Key 缺乏访问该接口的权限",
"error": "forbidden_scope"
}当前身份的额度上限低于接口最低调用成本。
{
"ok": false,
"data": "当前身份额度上限不足，无法调用该接口",
"error": "cost_exceeds_quota_limit"
}406
Accept 请求头不支持 JSON 响应。
响应头
x-api-remainx-api-costRetry-After
application/jsonobject
响应结构
{
"type": "object",
"required": [
"ok",
"data",
"error"
],
"properties": {
"ok": {
"type": "false",
"required": true,
"enum": [
false
]
},
"data": {
"type": "string",
"required": true
},
"error": {
"type": "string",
"required": true
}
}
}示例响应
{
"ok": false,
"data": "Accept 不支持 application/json 或 application/x-protobuf",
"error": "not_acceptable"
}429
额度不足或请求过于频繁，建议等 Retry-After 提示的时间后再试。
响应头
x-api-remainx-api-costRetry-After
application/jsonobject
响应结构
{
"type": "object",
"required": [
"ok",
"data",
"error"
],
"properties": {
"ok": {
"type": "false",
"required": true,
"enum": [
false
]
},
"data": {
"type": "string",
"required": true
},
"error": {
"type": "string",
"required": true
}
}
}示例响应
{
"ok": false,
"data": "额度不足，请稍后再试",
"error": "quota_exceeded"
}500
服务内部错误或响应编码失败。
响应头
x-api-remainx-api-costRetry-After
application/jsonobject
响应结构
{
"type": "object",
"required": [
"ok",
"data",
"error"
],
"properties": {
"ok": {
"type": "false",
"required": true,
"enum": [
false
]
},
"data": {
"type": "string",
"required": true
},
"error": {
"type": "string",
"required": true
}
}
}示例响应
{
"ok": false,
"data": "服务内部错误，请稍后再试",
"error": "internal_error"
}