客户故事

典型用户类型及 Lite 模式集成方式 — 请求前拦截、层级预留、软告警、无需数仓的账单查询。

AI API 基础设施

TokenBridge

在每一次 LLM 调用发生之前，就知道用户还有没有额度 — 而不是月底对账时才发现亏了几万块。

李明 · 后端负责人

「我们卖 Token 包，用户余额归零后网关还在转发上游 — 上个月有用户透支跑了 $2,000 的 Opus，我们全赔。Stripe 账单 T+1 才到，根本拦不住。」

痛点

预付费 Token 转售 + 多模型差异化定价。余额在业务 DB，与真实 Token 消耗异步对账。重试导致重复扣费争议。

如何集成

1 部署 Lite（make demo）— Redis + API，无需 Flink。
2 注册时：POST /budget/{userId} 设置 max_rpm。充值后：POST /budget/{userId}/package。
3 可选：POST /budget/{userId}/webhook，在消耗达 70%/90% 时收 BUDGET_WARN（v2.7 Lite）。
4 可选（v2.8）：POST /admin/customers/{id}/apikeys/{key_id}/budget 设置按 Key 限额。
5 Hook 1（同步）：转发上游前 GET /budget/{userId}/check?estimated_cost_usd=…
6 allowed: false → 返回 HTTP 402。allowed: true → 调用 OpenAI / DeepSeek / 通义，再执行 Hook 2。
7 Hook 2（异步）：POST /ingest，带 customerId、modelId、tokens，eventId=上游 id 保证幂等。
8 用量中心：后端代理 GET /usage/customer/{id}/period|day|model/* — 勿向前端暴露 Admin Key。

关键 API

请求前拦截 GET /budget/{id}/check
软告警 POST /budget/{id}/webhook
按 Key 预算 POST /admin/customers/{id}/apikeys/{key_id}/budget
Token 包余额 GET /budget/{id}/package
调用后计量 POST /ingest
开发者看板 GET /usage/customer/{id}/period/{YYYY-MM}

ID 映射

customerId = user_{uuid}（与用户表 1:1）。eventId = 上游请求 id（如 chatcmpl-xxx）用于去重。

bash

# Hook 1 — before every upstream LLM call
curl "localhost:8000/budget/user_wang/check?estimated_cost_usd=0.03"
# → allowed: false → return HTTP 402 to developer

# Optional (v2.8): per-key API budget on customer keys
# POST /admin/customers/{id}/apikeys/{key_id}/budget

# Hook 2 — after upstream response (async OK)
curl -X POST localhost:8000/ingest \
  -H 'Content-Type: application/json' \
  -d '{"customerId":"user_wang","modelId":"gpt-4o","inputTokens":500,"outputTokens":150,"eventId":"chatcmpl-abc"}'

# Soft alerts (v2.7 Lite) — BUDGET_WARN at 70%/90% spent
curl -X POST localhost:8000/budget/user_wang/webhook \
  -d '{"webhook_url":"https://api.example.com/hooks/fluxmeter"}'

# On recharge — token package
curl -X POST localhost:8000/budget/user_wang/package \
  -d '{"tokens": 10000000}'

效果

平台透支损失归零。硬切断前可先软告警。开发者自助查日/月/模型用量。网关仅加两个 Hook — 通常 3–4 周上线。

直播 + AIGC

ClipLive

一场直播、一条剪辑流水线 — 对创作者和 MCN 透明展示 AI 成本。

陈薇 · AI 流水线 Tech Lead

「一条剪辑要调 4–6 次模型，以前只知道整场直播「大概」花了多少钱。创作者投诉「为什么这条 clip 扣我 3 块」，我们查不到。」

痛点

多步 LLM 流水线（转写 → 高光 → 文案 → 封面）。成本散落日志。套餐耗尽后任务仍能提交。

如何集成

1 定义 ID：customerId = creator_{slug}，parentSpanId = job_{hex}（每条 clip），可选 sessionId = live_{date}_{room}。
2 可选硬封顶（v2.7）：POST /budget/{creatorId}/cap，kind=span，id=job_id，max_cost_usd=…
3 可选（v2.8）：任务前 POST /budget/{creatorId}/reserve?estimated_cost_usd=…&parent_span_id=job_id。
4 入队前：GET /budget/{creatorId}/check?estimated_cost_usd=0.50&parent_span_id=job_id — 不允许则拒绝创建任务。
5 每步 LLM 调用后：异步 POST /ingest，parentSpanId = job_id，spanId = job_id:step（Lite 自 v2.6.2 聚合 span）。
6 任务成功：GET /usage/span/{job_id} → 回写 clip_jobs.cost_usd 并展示在 UI。
7 MCN 月底结算：GET /usage/customer/{creatorId}/period/{YYYY-MM}。
8 非 Token 成本（渲染、CDN）保留在业务 DB — 在自有 API 聚合展示「本条 clip 总成本」。

关键 API

任务门禁 GET /budget/{id}/check
单条 clip 封顶 POST /budget/{id}/cap
层级预留 POST /budget/{id}/reserve?parent_span_id=
逐步计量 POST /ingest（parentSpanId）
单条 clip 成本卡 GET /usage/span/{job_id}
创作者月度 GET /usage/customer/{id}/period/{YYYY-MM}

ID 映射

customerId = creator_*。parentSpanId = job_*（一条 clip）。spanId = job_*:asr|highlight|caption。sessionId = live_* 可选，用于场次汇总。

bash

# Optional hard cap per clip (v2.7)
curl -X POST localhost:8000/budget/creator_liwei/cap \
  -d '{"kind":"span","id":"job_a1b2c3","max_cost_usd":0.50}'

# Optional (v2.8): reserve holds customer + span cap pool together
curl -X POST "localhost:8000/budget/creator_liwei/reserve?estimated_cost_usd=0.50&parent_span_id=job_a1b2c3"

# Before enqueue — gate the clip job
curl "localhost:8000/budget/creator_liwei/check?estimated_cost_usd=0.50&parent_span_id=job_a1b2c3"

# Each pipeline step — same parentSpanId = job id (Lite + Full)
curl -X POST localhost:8000/ingest \
  -H 'Content-Type: application/json' \
  -d '{"customerId":"creator_liwei","modelId":"gpt-4o","parentSpanId":"job_a1b2c3","spanId":"job_a1b2c3:highlight","inputTokens":8000,"outputTokens":400}'

# After job completes — show cost in UI
curl localhost:8000/usage/span/job_a1b2c3
# → {cost_usd: 0.31, call_count: 4, total_tokens: 142000}

效果

Lite 上 100% 已完成任务可展示 task 级 cost_usd。创作者成本争议下降约 70%。ingest 全异步 — 不增加剪辑热路径延迟。

AI SaaS · 财务

MarginStack

月度董事会材料：哪些客户亏钱、何种定价动作能收窄缺口。

金莎拉 · 财务副总裁

「我们有 Stripe 收入与 Grafana Token 看板 — 但没有按客户利润率。董事会问 AI 毛利率为何降 8 个点，我们花了一周做表格。」

痛点

按量计费的 AI SaaS，套餐混杂。LLM 成本在日志里；收入在 OpenMeter。财务需要亏损预警与调价前的 what-if。

如何集成

1 部署 Lite（make demo）— 按租户 customerId 摄入 LLM 用量。
2 叠加收入：OpenMeter 连接器或每月 POST /intelligence/revenue/{customer_id}。
3 月结：GET /intelligence/unit-economics?period=YYYY-MM — 标记负利润率客户。
4 解释变化：GET /intelligence/root-cause 做驱动拆解。
5 调价前：POST /intelligence/simulate 模拟模型切换或 Token 赠送。
6 董事会导出：GET /intelligence/report?format=markdown。

关键 API

单位经济 GET /intelligence/unit-economics
根因分析 GET /intelligence/root-cause
情景模拟 POST /intelligence/simulate
董事会报表 GET /intelligence/report?format=markdown
收入叠加 POST /intelligence/revenue/{id}

ID 映射

customerId = tenant_*（与计费账户 1:1）。period = YYYY-MM UTC 自然月。

bash

效果

财务无需数仓即可获得按客户利润率与建议。工程在同一 ingest 路径保留支柱 A 拦截能力。

模式对比

维度	TokenBridge（API 网关）	ClipLive（AIGC 流水线）
核心场景	OpenAI 兼容 API 转售 Token	直播下播后异步生成短视频
关键路径	每次请求同步 /check	任务入队前 check 一次
主键	customerId = 下游开发者	customerId = 创作者
成本归因	模型 / 日 / 月汇总	parentSpanId = 一条剪辑任务
计费形态	Token 包 + RPM 限流	月度 USD 额度 / 按条
摄入模式	同步 check + 异步 ingest	每步完全异步 ingest

完整 4 周实施方案、验收清单与序列图见 GitHub： customer-stories-lite.md

快速开始 — make demo