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

基于您的 iApp 账户数据构建您自己的仪表盘。Core API 以干净的只读 JSON 形式开放您的 API 用量与积分数据（与 iApp 仪表盘显示的数字同源），可直接接入 Grafana、Google Sheets、您的管理后台、Slack 机器人或任何支持 HTTP 的工具。

同一个 API key — 与调用 AI API 的 key 相同，无需额外配置
设计上只读 — 所有端点均为 GET；即使 key 泄露，也无法通过此 API 修改您的账户
无个人信息（PII） — 响应仅包含技术遥测数据（时间戳、路径、状态码、积分、延迟），绝不包含姓名、邮箱、IP 或请求内容
按 key 报表 — 为每个应用或每个终端客户签发一个 API key，即可分别计量每个 key 的用量
免费 — 调用 Core API 不消耗积分

Base URL: https://iapp.co.th/api/core/v1

如何获取 API Key？

前往 API Key Management 查看您的 key 或申请新的 key。

端点一览

Method	Path	说明
`GET`	`/ping`	验证 API key 是否有效
`GET`	`/credits`	剩余积分余额
`GET`	`/usage/summary`	指定时间范围的用量汇总统计
`GET`	`/usage/timeseries`	按小时/天/周/月分桶的用量时间序列 — 可直接绘图
`GET`	`/usage/services`	按服务拆分（请求数、积分、延迟、错误率）
`GET`	`/usage/keys`	按 API key 拆分 — 每个 key 一行，附带 key 名称
`GET`	`/usage/records`	逐条 API 调用记录，支持筛选、排序与分页

所有端点都需要 apikey 请求头。日期参数接受 YYYY-MM-DD 或完整 ISO 8601 格式；未指定时默认统计最近 30 天。

身份验证

在 apikey 请求头中传入您的 API key（x-api-key 也可以）：

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"
  }
}

请仅在服务器端使用您的 key

请从您的后端、定时任务或 BI 工具调用 Core API — 切勿在浏览器 JavaScript 中调用。任何能查看页面源码的人都能拿到您的 API key。（我们也有意通过 CORS 阻止浏览器调用。）

积分余额

GET /credits — 您剩余的 iApp 积分（IC）。

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"
  }
}

非常适合做余额不足告警：每小时轮询一次，当 balance 低于阈值时通知自己。

用量汇总

GET /usage/summary — 一段时间的核心指标。

参数	类型	默认值	说明
`startDate`	date	30 天前	起始时间
`endDate`	date	当前	结束时间
`apiKeyId`	uuid	—	仅统计该 API key 的调用 — 取 `/usage/keys` 返回的 `keyId`

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 }
    ]
  }
}

用量时间序列

GET /usage/timeseries — 每个时间桶的请求数与积分，可直接输入图表库。

参数	类型	默认值	说明
`startDate`	date	30 天前	起始时间
`endDate`	date	当前	结束时间
`groupBy`	enum	`day`	`hour`、`day`、`week` 或 `month`
`apiKeyId`	uuid	—	仅统计该 API key 的调用 — 取 `/usage/keys` 返回的 `keyId`

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 }
    ]
  }
}

时间桶的时间戳为 UTC — 渲染时请转换为本地时区。

按服务拆分

GET /usage/services — 您调用过的每个 iApp 服务一行，附带质量指标。

参数	类型	默认值	说明
`startDate` / `endDate`	date	最近 30 天	统计区间
`sortBy`	enum	`requests`	`requests`、`credits`、`latency` 或 `errorRate`
`sortOrder`	enum	`desc`	`asc` 或 `desc`
`apiKeyId`	uuid	—	仅统计该 API key 的调用 — 取 `/usage/keys` 返回的 `keyId`

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 }
    ]
  }
}

按 API key 拆分

GET /usage/keys — 统计期内每个被使用的 API key 一行。这是转售（reseller）与多租户场景的核心端点：在 API Key Management 中为每个应用或每个终端客户创建一个 key，每一行即计量其中一个。

参数	类型	默认值	说明
`startDate` / `endDate`	date	最近 30 天	统计区间
`sortBy`	enum	`requests`	`requests`、`credits` 或 `lastUsed`
`sortOrder`	enum	`desc`	`asc` 或 `desc`

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"
      }
    ]
  }
}

keyId 是 API Key Management 中该 key 的 id — 绝不是 key 本身。把它作为 apiKeyId 参数传给 /usage/summary、/usage/timeseries、/usage/services 或 /usage/records，即可把任意报表限定到该 key。已从账户中删除的 key 仍会出现（以保证账户总量对得上），其 keyId、keyName、keyPrefix 为 null。

调用记录 — 筛选、排序、分页

GET /usage/records — 原始调用日志，每次 API 请求一行。这是自定义报表的主力端点。

参数	类型	默认值	说明
`startDate` / `endDate`	date	最近 30 天	统计区间
`service`	string	—	仅该服务的调用（使用 `/usage/services` 返回的 `service` 值）
`method`	enum	—	`GET`、`POST`、`PUT`、`DELETE`、`PATCH`
`status`	int	—	精确 HTTP 状态码，如 `402`
`statusClass`	enum	—	`2xx`、`3xx`、`4xx` 或 `5xx`（指定 `status` 时忽略）
`minCredits`	number	—	仅花费不少于该 IC 数的调用
`apiKeyId`	uuid	—	仅该 API key 的调用 — 取 `/usage/keys` 返回的 `keyId`
`sortBy`	enum	`timestamp`	`timestamp`、`credits`、`latency` 或 `status`
`sortOrder`	enum	`desc`	`asc` 或 `desc`
`limit`	int	`100`	每页行数，1–1000
`offset`	int	`0`	分页偏移（`limit + offset` ≤ 10,000 — 需要更深时请缩小日期范围）

示例 — 本月最贵的 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 }
  }
}

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

Postman Collection

更喜欢点击而不是敲 curl？导入现成的 collection — 全部 7 个端点、可随时启用的筛选示例，以及 66 条内置断言（含 PII 泄漏检查）：

Collection · Production 环境

导入 collection 和环境文件，设置 apikey 环境变量即可使用。

20 行代码构建仪表盘

Python — 每日成本报表：

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")

Node.js — 余额不足告警（由 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`);
}

安全与隐私设计

Core API 的设计保证即使发生最坏情况 — API key 泄露 — 损害也被控制在最小范围：

只读。 只有 GET 端点。无法通过此 API 创建 key、消费积分、修改设置或删除任何内容。
无个人信息。 响应绝不包含您的姓名、邮箱、用户 ID、客户端 IP、请求头或 API 请求/响应内容。端点路径会去除查询字符串（可能包含输入数据），API key 只显示前 8 个字符。
仅您自己的数据。 key 标识您的账户；不存在任何能访问其他账户数据的参数。apiKeyId 参数只接受您自己账户中 key 的 id — 其他任何值都返回 404。
限流。 每个 API key 每分钟 120 次请求，超出返回 HTTP 429 — 仪表盘每 30–60 秒拉取一次已完全足够。

如果您的 key 泄露，请在 API Key Management 中吊销 — 用量历史不会丢失。

错误

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

所有错误共用同一结构：

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

常见问题

调用 Core API 消耗积分吗？ 不消耗 — 完全免费，也不会出现在您的用量记录中。

数据有多新？ 调用完成后几秒内即出现在用量记录中；积分余额为实时数据。

能查多久以前的数据？ 与网页仪表盘的保留期相同。如需长期归档，请定期拉取 /usage/records 并存储在您自己这边。

能用一个专门的 key 只做报表吗？ 可以 — 在 API Key Management 中创建专用 key，仅用于 Core API。每条记录都会显示发起原始调用的 key（keyId、keyName）。

能按客户或按应用出用量报表吗？ 可以 — 为每个客户或每个应用创建一个 API key，用 /usage/keys 查看按 key 拆分的汇总，再用 apiKeyId 参数把其他任意用量端点限定到单个 key。

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

端点一览

身份验证

积分余额

用量汇总

用量时间序列

按服务拆分

按 API key 拆分

调用记录 — 筛选、排序、分页

Postman Collection

20 行代码构建仪表盘

安全与隐私设计

错误

常见问题

ChindaX

SpeechFlow

ChindaGO

端点一览​

身份验证​

积分余额​

用量汇总​

用量时间序列​

按服务拆分​

按 API key 拆分​

调用记录 — 筛选、排序、分页​

Postman Collection​

20 行代码构建仪表盘​

安全与隐私设计​

错误​

常见问题​

端点一览

身份验证

积分余额

用量汇总

用量时间序列

按服务拆分

按 API key 拆分

调用记录 — 筛选、排序、分页

Postman Collection

20 行代码构建仪表盘

安全与隐私设计

错误

常见问题