公约

每个能力在原生 HTTP 上遵循的共同规则：请求信封、响应元数据、传输公约与幂等。无需任何 SDK。

请求与响应信封

每个 infrai 原生 REST 调用都是向 https://api.infrai.cc/v1/… 发起带 Bearer 密钥与 JSON 体的 POST（或 GET）。原生 REST 响应使用相同的信封：

OpenAI 兼容的 AI 推理接口（例如 /v1/chat/completions 和 /v1/embeddings）会刻意保持 OpenAI 响应结构，并额外添加顶层 infrai 元数据块，而不是使用这个信封。

json

{
  "ok": true,
  "data": { /* capability-specific result */ },
  "error": null,
  "metadata": {
    "cost_usd": 0.00012,
    "latency_ms": 412,
    "vendor": "deepseek",
    "cache_hit": false,
    "request_id": "01HXY..."   // UUID v7
  }
}

结果元数据

每次调用都会返回数据及一个元数据块，让 agent 无需再请求供应商即可读取成本与延迟。

cost_usd · 本次调用的美元成本，可与账单逐条对账。
latency_ms · 端到端延迟（毫秒）。
vendor · 实际服务本次调用的上游供应商。
cache_hit · 响应是否来自缓存。
request_id · 全局唯一 id（UUID v7），用于支持与对账。

传输契约

用任意语言通过 HTTPS 直接调用 API。共同的传输规则：

认证	`Authorization: Bearer <infrai_project_key>`
请求体	规范化 JSON：键排序、无空格、结尾换行、UTF-8。
幂等头	`Idempotency-Key`
请求 id	`metadata.request_id (UUID v7)`

幂等

幂等让重试安全——在去重窗口内，同一 key 永不重复扣费、不重复创建资源。

读取（GET）调用默认幂等——无需传 key。
产生费用的调用会在服务端派生 key；推荐你主动传入。
资源创建类调用建议传入 idempotency key 以便安全重试；当前公开 API 已不再强制要求调用方必须提供。

bash

# Cost-incurring calls: send an Idempotency-Key header so retries never double-charge.
curl -X POST https://api.infrai.cc/v1/email/send \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-confirmed-123" \
  -d '{"to": "customer@x.com", "subject": "Order #123 confirmed", "html": "<p>Thanks!</p>"}'

当你在产生费用的调用中省略 key 时，服务端会确定性地派生一个：

text

idempotency_key = sha256(account_id + request_id + capability + content_hash)

默认去重窗口为 24 小时（最短 1 小时，最长 7 天）。窗口内重复请求会返回原始结果且不再扣费。