场景
适用场景
这个接口适合用在什么地方？下面的场景可以帮你判断它是不是你要找的那个。
- 第三方应用拿到 access_token 后，先调用这个接口确认凭证有效、额度还剩多少。
- 前端页面在启动时判断用户是否已登录。
- 开发者调试自己签发的 API Key 是否配置正确。
问答
常见问题
接入时最常遇到的疑问，先看看这里能不能解答。
为什么调用这个接口也能看到额度？
每次响应都会带 meta 字段，里面是本次请求后的剩余额度（remain）、本次扣费（cost）和可能的重试等待时间（retryAfter）。
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": [
"meta",
"data"
],
"properties": {
"meta": {
"type": "object",
"required": true,
"shape": {
"type": "object",
"required": [
"remain",
"cost"
],
"properties": {
"remain": {
"type": "integer",
"required": true
},
"cost": {
"type": "integer",
"required": true
},
"retryAfter": {
"type": "integer"
}
}
}
},
"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"
}
}
}
}
}
}
}
}
}示例响应
{
"meta": {
"remain": 2000,
"cost": 1
},
"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
}
}
}401
请求未携带有效的认证信息，或提供的 API Key 已失效。
响应头
x-api-remainx-api-costRetry-After
application/jsonobject
响应结构
{
"type": "object",
"required": [
"meta",
"error"
],
"properties": {
"meta": {
"type": "object",
"required": true,
"shape": {
"type": "object",
"required": [
"remain",
"cost"
],
"properties": {
"remain": {
"type": "integer",
"required": true
},
"cost": {
"type": "integer",
"required": true
},
"retryAfter": {
"type": "integer"
}
}
}
},
"error": {
"type": "object",
"required": true,
"shape": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"required": true
},
"message": {
"type": "string",
"required": true
}
}
}
}
}
}示例响应
{
"meta": {
"remain": 159,
"cost": 1
},
"error": {
"code": "invalid_api_key",
"message": "API Key 无效或已过期。"
}
}403
账号已被封禁，或当前凭证缺少 api.auth.me.read 权限。
响应头
x-api-remainx-api-costRetry-After
application/jsonobject
响应结构
{
"type": "object",
"required": [
"meta",
"error"
],
"properties": {
"meta": {
"type": "object",
"required": true,
"shape": {
"type": "object",
"required": [
"remain",
"cost"
],
"properties": {
"remain": {
"type": "integer",
"required": true
},
"cost": {
"type": "integer",
"required": true
},
"retryAfter": {
"type": "integer"
}
}
}
},
"error": {
"type": "object",
"required": true,
"shape": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"required": true
},
"message": {
"type": "string",
"required": true
}
}
}
}
}
}示例响应
{
"meta": {
"remain": 159,
"cost": 1
},
"error": {
"code": "account_banned",
"message": "账号已被封禁。"
}
}429
额度不足或请求过于频繁。
响应头
x-api-remainx-api-costRetry-After
application/jsonobject
响应结构
{
"type": "object",
"required": [
"meta",
"error"
],
"properties": {
"meta": {
"type": "object",
"required": true,
"shape": {
"type": "object",
"required": [
"remain",
"cost"
],
"properties": {
"remain": {
"type": "integer",
"required": true
},
"cost": {
"type": "integer",
"required": true
},
"retryAfter": {
"type": "integer"
}
}
}
},
"error": {
"type": "object",
"required": true,
"shape": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"required": true
},
"message": {
"type": "string",
"required": true
}
}
}
}
}
}示例响应
{
"meta": {
"remain": 159,
"cost": 1
},
"error": {
"code": "rate_limited",
"message": "额度不足，请稍后再试。"
}
}