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

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

同一个 API key — 与调用 AI API 的 key 相同，无需额外配置
设计上只读 — 所有端点均为 GET；即使 key 泄露，也无法通过此 API 修改您的账户
无个人信息（PII） — 响应仅包含技术遥测数据（时间戳、路径、状态码、积分、延迟），绝不包含姓名、邮箱、IP 或请求内容
免费 — 调用 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/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	当前	结束时间

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`

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`

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

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

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 数的调用
`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"

{
  "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..."
      }
    ],
    "pagination": { "total": 3, "limit": 100, "offset": 0, "hasMore": false }
  }
}

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

Postman Collection

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

Collection · Production 环境 · UAT 环境

导入 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 标识您的账户；不存在任何能访问其他账户数据的参数。
限流。 每个 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` 列出具体问题
`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（apiKeyPrefix）。

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

端点一览

身份验证

积分余额

用量汇总

用量时间序列

按服务拆分

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

Postman Collection

20 行代码构建仪表盘

安全与隐私设计

错误

常见问题

ChindaX

SpeechFlow

ChindaGO

端点一览​

身份验证​

积分余额​

用量汇总​

用量时间序列​

按服务拆分​

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

Postman Collection​

20 行代码构建仪表盘​

安全与隐私设计​

错误​

常见问题​

端点一览

身份验证

积分余额

用量汇总

用量时间序列

按服务拆分

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

Postman Collection

20 行代码构建仪表盘

安全与隐私设计

错误

常见问题