Core API — 用量报告与积分余额

Core API 以 JSON 返回您账户的 API 用量和积分余额，数据与仪表盘一致，可用于自建报表、仪表盘和告警。它使用您现有的 API key；所有端点均为 GET，调用免费且不计入用量，响应不含任何个人信息。

Base URL： https://iapp.co.th/api/core/v1
请求头： apikey: YOUR_API_KEY（也可用 x-api-key）。您的 key 在 API Key Management 中。

curl "https://iapp.co.th/api/core/v1/credits" \
  -H "apikey: YOUR_API_KEY"

{
  "success": true,
  "data": {
    "balance": 1234.56,
    "currency": "IC",
    "validUntil": "2027-01-31T16:59:59.000Z"
  }
}

请从服务器、定时任务或 BI 工具调用，切勿在浏览器 JavaScript 中调用：key 会暴露在页面源码中，且浏览器调用已被 CORS 阻止。

端点

端点	返回
`/ping`	确认 key 可用
`/credits`	剩余积分余额（IC）
`/usage/summary`	某时段的核心指标：请求数、积分、平均延迟、成功率、调用最多的端点
`/usage/timeseries`	按小时、天、周或月统计的请求数与积分
`/usage/services`	每个服务一行：请求数、积分、延迟、错误率
`/usage/keys`	每个 API key 一行，附带 key 名称
`/usage/records`	每次调用一行，支持筛选、排序与分页

所有 /usage/* 端点都接受 startDate 和 endDate（YYYY-MM-DD 或 ISO 8601；默认最近 30 天）。除 /usage/keys 外，还接受 apiKeyId，用于只统计某一个 key。

参数与响应

除通用参数外没有其他参数。

curl "https://iapp.co.th/api/core/v1/usage/summary?startDate=2026-08-01&endDate=2026-08-05" \
  -H "apikey: YOUR_API_KEY"

{
  "success": true,
  "data": {
    "period": { "startDate": "2026-08-01T00:00:00.000Z", "endDate": "2026-08-05T00:00:00.000Z" },
    "totalRequests": 18342,
    "totalCredits": 2311.75,
    "avgLatencyMs": 412,
    "successRate": 99.12,
    "topEndpoints": [
      { "endpoint": "/thai-ocr/v3.5/ocr-document", "requests": 9120, "credits": 1824.0 },
      { "endpoint": "/v3/store/data/thai-legal/search", "requests": 4210, "credits": 421.0 }
    ]
  }
}

groupBy：hour、day（默认）、week 或 month。时间桶的时间戳为 UTC，渲染时请转换为本地时区。

curl "https://iapp.co.th/api/core/v1/usage/timeseries?startDate=2026-08-01&endDate=2026-08-05&groupBy=day" \
  -H "apikey: YOUR_API_KEY"

{
  "success": true,
  "data": {
    "period": { "startDate": "2026-08-01T00:00:00.000Z", "endDate": "2026-08-05T00:00:00.000Z" },
    "groupBy": "day",
    "points": [
      { "date": "2026-08-01T00:00:00.000Z", "requests": 4102, "credits": 512.25 },
      { "date": "2026-08-02T00:00:00.000Z", "requests": 3876, "credits": 488.5 },
      { "date": "2026-08-03T00:00:00.000Z", "requests": 5211, "credits": 651.0 }
    ]
  }
}

sortBy：requests（默认）、credits、latency 或 errorRate。sortOrder：desc（默认）或 asc。

curl "https://iapp.co.th/api/core/v1/usage/services?sortBy=credits&sortOrder=desc" \
  -H "apikey: YOUR_API_KEY"

{
  "success": true,
  "data": {
    "period": { "startDate": "2026-07-06T09:30:00.000Z", "endDate": "2026-08-05T09:30:00.000Z" },
    "services": [
      { "service": "document-ocr", "requests": 9120, "credits": 1824.0, "avgLatencyMs": 890, "errorRate": 0.4 },
      { "service": "thai-legal", "requests": 4210, "credits": 421.0, "avgLatencyMs": 210, "errorRate": 0.1 }
    ]
  }
}

sortBy：requests（默认）、credits 或 lastUsed。sortOrder：desc（默认）或 asc。

curl "https://iapp.co.th/api/core/v1/usage/keys?startDate=2026-08-01" \
  -H "apikey: YOUR_API_KEY"

{
  "success": true,
  "data": {
    "period": { "startDate": "2026-08-01T00:00:00.000Z", "endDate": "2026-08-24T00:00:00.000Z" },
    "keys": [
      {
        "keyId": "0d9c7c2e-59a4-4f6b-9f1e-3f6f6f0a1b2c",
        "keyName": "customer-a-production",
        "keyPrefix": "iapp_live_ab",
        "requests": 9120,
        "credits": 1824.0,
        "errorRate": 0.4,
        "avgLatencyMs": 890,
        "lastUsedAt": "2026-08-23T14:22:31.000Z"
      },
      {
        "keyId": "b4f0a2d1-7c3e-4d5a-8e9f-1a2b3c4d5e6f",
        "keyName": "customer-b-production",
        "keyPrefix": "iapp_live_cd",
        "requests": 4210,
        "credits": 421.0,
        "errorRate": 0.1,
        "avgLatencyMs": 210,
        "lastUsedAt": "2026-08-24T08:01:12.000Z"
      }
    ]
  }
}

参数	取值
`service`	`/usage/services` 返回的 `service` 值
`method`	`GET`、`POST`、`PUT`、`DELETE`、`PATCH`
`status`	单个 HTTP 状态码，如 `402`
`statusClass`	`2xx`、`3xx`、`4xx`、`5xx`；指定 `status` 时忽略
`minCredits`	仅返回花费不少于该 IC 数的调用
`sortBy`	`timestamp`（默认）、`credits`、`latency`、`status`
`sortOrder`	`desc`（默认）、`asc`
`limit`	每页行数，1–1000，默认 `100`
`offset`	默认 `0`；`limit + offset` ≤ 10,000，需要更深时请缩小日期范围

翻页时每次将 offset 增加 limit，直到 hasMore 为 false。

# 8 月 1 日以来最贵的 50 次调用
curl "https://iapp.co.th/api/core/v1/usage/records?startDate=2026-08-01&sortBy=credits&sortOrder=desc&limit=50" \
  -H "apikey: YOUR_API_KEY"

# 某服务的失败调用（4xx），按时间正序
curl "https://iapp.co.th/api/core/v1/usage/records?service=document-ocr&statusClass=4xx&sortBy=timestamp&sortOrder=asc" \
  -H "apikey: YOUR_API_KEY"

# 单个 key 的调用
curl "https://iapp.co.th/api/core/v1/usage/records?apiKeyId=0d9c7c2e-59a4-4f6b-9f1e-3f6f6f0a1b2c&startDate=2026-08-01" \
  -H "apikey: YOUR_API_KEY"

{
  "success": true,
  "data": {
    "period": { "startDate": "2026-08-01T00:00:00.000Z", "endDate": "2026-08-05T09:30:00.000Z" },
    "records": [
      {
        "timestamp": "2026-08-04T14:22:31.000Z",
        "service": "document-ocr",
        "endpoint": "/thai-ocr/v3.5/ocr-document",
        "method": "POST",
        "status": 402,
        "credits": 0,
        "latencyMs": 18,
        "apiKeyPrefix": "iapp_liv...",
        "keyId": "0d9c7c2e-59a4-4f6b-9f1e-3f6f6f0a1b2c",
        "keyName": "customer-a-production"
      }
    ],
    "pagination": { "total": 3, "limit": 100, "offset": 0, "hasMore": false }
  }
}

curl "https://iapp.co.th/api/core/v1/ping" \
  -H "apikey: YOUR_API_KEY"

{
  "success": true,
  "data": {
    "ok": true,
    "apiKeyPrefix": "iapp_liv...",
    "timestamp": "2026-08-05T09:30:00.000Z"
  }
}

按 API key 统计

在 API Key Management 中为每个应用或每个客户创建一个 API key。/usage/keys 为每个 key 返回一行，附带 keyId，即 key 的 id 而非 key 本身；将其作为 apiKeyId 传给其他任意 /usage/* 端点，即可只统计该 key。已删除的 key 仍会出现，其 keyId、keyName、keyPrefix 为 null，以保证账户总量对得上。

示例

Python：每日成本报表
Node.js：余额不足告警

import requests

BASE = "https://iapp.co.th/api/core/v1"
HEADERS = {"apikey": "YOUR_API_KEY"}

credits = requests.get(f"{BASE}/credits", headers=HEADERS).json()["data"]
series = requests.get(
    f"{BASE}/usage/timeseries",
    headers=HEADERS,
    params={"startDate": "2026-08-01", "groupBy": "day"},
).json()["data"]

print(f"余额: {credits['balance']:.2f} IC")
for point in series["points"]:
    print(f"{point['date'][:10]}  {point['requests']:>6} 次调用  {point['credits']:>8.2f} IC")

由 cron 运行。

const BASE = "https://iapp.co.th/api/core/v1";
const THRESHOLD = 100; // IC

const res = await fetch(`${BASE}/credits`, {
  headers: { apikey: process.env.IAPP_API_KEY },
});
const { data } = await res.json();

if (data.balance < THRESHOLD) {
  await notifySlack(`iApp 积分不足：仅剩 ${data.balance} IC`);
}

使用 Postman 时，导入 collection 和 Production 环境，再设置 apikey 变量即可。

限制

每个 API key 每分钟 120 次请求，超出返回 HTTP 429。仪表盘每 30–60 秒拉取一次已足够。
调用完成后几秒内即出现在用量记录中；积分余额为实时数据。
历史数据的保留期与网页仪表盘相同。如需长期归档，请定期拉取 /usage/records 并自行保存。

数据处理

此 API 只读：无法创建 key、消费积分、修改设置或删除任何内容。响应不含姓名、邮箱、用户 ID、客户端 IP、请求头或请求与响应内容；端点路径会去除查询字符串，API key 只显示前缀，从不显示完整的 key。key 只能访问其所属账户，不属于该账户的 apiKeyId 返回 404；如果 key 泄露，请在 API Key Management 中吊销，用量历史不会丢失。

错误

HTTP	Code	含义
`400`	`VALIDATION_ERROR`	参数错误；`error.details.errors` 列出每个问题
`401`	`UNAUTHORIZED`	缺少或无效的 API key
`403`	`FORBIDDEN`	账户未激活
`404`	`NOT_FOUND`	`apiKeyId` 不是本账户的 key
`429`	`TOO_MANY_REQUESTS`	该 key 每分钟超过 120 次请求
`503`	`SERVICE_UNAVAILABLE`	后端临时故障；请退避重试

所有错误共用同一结构：

{
  "success": false,
  "error": { "code": "UNAUTHORIZED", "message": "Invalid API key." }
}

端点​

参数与响应​

按 API key 统计​

示例​

限制​

数据处理​

错误​

端点

参数与响应

按 API key 统计

示例

限制

数据处理

错误