公约

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

请求与响应信封

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

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。

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 天）。窗口内重复请求会返回原始结果且不再扣费。

BYOK（自带密钥）

注册你自己的供应商凭证，让调用通过你的密钥而非共享池分发。

bash

# Register your own vendor key; calls then dispatch through it.
curl -X POST https://api.infrai.cc/v1/byok \
  -H "Authorization: Bearer $INFRAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider": "openai", "alias": "prod-gpt4o", "credentials": {"api_key": "sk-..."}}'

凭证只写不读：API 永不返回明文密钥，只返回一个可供你辨认的短指纹。