教程2026-11-18 · 智涌AI

Claude 关联计费接入教程:让客户自己付 token 费

Claude API 关联计费教程头图:左侧 Claude 关联计费大字和 5 步关联流程、测试期 50 美元上限、request_uri 10 分钟有效期数据卡,右侧终端展示带 beta 头和用户档案头的 /v1/messages 请求、billing_policy 的 bill_to 字段以及 403、402 错误的处理方式

Anthropic 在 11 月 17 日上线了 Claude API 的 Linked billing(关联计费)测试版。做 AI 应用的开发者,可以让企业客户把自己的 Claude 组织关联到你的应用,之后每个请求由你决定:这次记客户的账,还是记你自己的账。重度用户的 token 费,不必再全由你垫付。下面按官方接入指南把流程走一遍:注册应用、让客户授权、改请求头,以及几个最容易出错的地方。

前置条件:先确认客户够格

还有一条合规限制要先想清楚:这些请求跑在你的组织里,用的是你的速率限制、模型权限、数据保留和加密密钥。客户自己签的零数据保留(ZDR)、BAA、CMEK 对这部分用量不生效。官方明确说,需要 HIPAA、FERPA 或 CMEK 覆盖的客户不要接。

第一步:注册 OAuth 应用(一次性)

组织里的 Admin 打开 Console 的 OAuth apps 页,点 Create,填应用名和回调地址,在 What the app can do 里选 Bill and link to organizations。建好后复制 client ID,它是公开的,后面三步都要用。

接着在 Client authentication 页选你的身份提供方(没有就 Register a new issuer),设 Subject pattern。保存后页面会显示期望的 audience,你后端发的 client assertion 里 aud 必须一字不差。

然后按 Workload Identity Federation 指南建一个服务账号和第二条联邦规则,回到同一页把它选成应用的 operator service account。只有这个账号能发推理请求、把账记到已关联的客户头上。一个服务账号只能当一个应用的 operator。

新应用默认是测试状态,Who can link 显示 Test users only。测试期客户在批准页必须设月度上限,且最高 50 美元。

第二步:为每个客户走一遍关联

官方把这部分编成 Step 4 到 Step 8,每个客户做一次。产品里放一个「Link your Claude organization」按钮(官方有按钮样式素材),放在客户管理账单或集成的地方。

步骤谁做要点
4 建用户档案你的后端POST /v1/user_profiles,拿到 uprof_… 存进客户记录;同一个 reference_id 每调一次都会新建,别重复建
5 推送授权请求你的后端POST auth.claude.com/v1/oauth/par,scope 填 billing:attribution,带 state 和 PKCE;返回的 request_uri 10 分钟内有效
6 跳转批准页用户浏览器只带 client_id 和 request_uri
7 客户批准客户管理员选组织 → 看计费说明 → 设月度上限 → Link and authorize
8 换连接 ID你的后端核对 state,5 分钟内用 code + code_verifier 换 connection_id,token 只返回这一次

第 5 步的请求体,官方 cURL 示例是这样的(client assertion 来自你的 IdP):

curl https://auth.claude.com/v1/oauth/par \
  -H "content-type: application/json" \
  -d '{
    "response_type": "code",
    "client_id": "YOUR_CLIENT_ID",
    "redirect_uri": "https://app.example.com/claude/billing/callback",
    "scope": "billing:attribution",
    "connection_type": "organization_shared",
    "connection_auth_target": "platform",
    "user_profile_id": "uprof_01HV9Z",
    "state": "RANDOM_STATE",
    "code_challenge": "BASE64URL_SHA256_OF_VERIFIER",
    "code_challenge_method": "S256",
    "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
    "client_assertion": "YOUR_CLIENT_ASSERTION_JWT"
  }'

连接属于客户的整个组织,不属于点批准的那个人。那个人离职了,连接照样有效。

第三步:在请求上选谁付钱

对已关联的客户,每个 /v1/messages 或 /v1/chat/completions 请求都带 anthropic-user-profile-id 头。要让客户付,再加 beta 头和 billing_policy:

curl https://api.anthropic.com/v1/messages \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "anthropic-version: 2026-10-21" \
  -H "anthropic-beta: user-profiles-billing-2026-10-01" \
  -H "anthropic-user-profile-id: uprof_01HV9Z" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello, Claude"}],
    "billing_policy": {"type": "billing_policy", "bill_to": "user_profile"}
  }'

自己付有两种写法:去掉 billing_policy(这时 beta 头可省),或写 "bill_to": "self"。免费额度、轻量功能、你自己的测试和评测,都应该走这条。官方原话是只对「客户让你发的请求」记客户的账,API 替你查不了这一点。

请求标了 bill_to: "user_profile",Anthropic 要么记到客户账上,要么直接拒绝,不会悄悄改记到你头上。

反过来,成功响应里也不写这次是谁付的,所以你要自己记一笔:哪些请求发的是 user_profile。

实测:把错误表写成路由函数

接入时最费功夫的是错误处理。我在 box 上(Python 3.13.5,2026-11-18)写了个离线脚本:按官方文档拼请求头,把「Expected errors」一节逐条翻成处理动作,再喂模拟响应跑一遍。

def decide(status, error_code, seconds_since_link=999):
    if status == 403 and error_code == "user_profile_not_billable":
        if seconds_since_link <= 10:
            return "重试一次:新连接可能还没生效(10 秒内)"
        return "停止向客户计费;记录 error.message + request-id;可改 bill_to=self 自付"
    if status == 402 and error_code == "linked_organization_spend_limit_reached":
        return "提示客户:检查给本应用的 spend cap / 组织月度上限 / 余额"
    if status == 402 and error_code == "linked_organization_billing_unavailable":
        return "不重试;提示客户检查 Claude Platform 账户"
    if status == 503:
        return "退避重试,遵守 retry-after(本次未计费)"
    if status == 400 and error_code == "user_profile_required":
        return "代码 bug:缺 anthropic-user-profile-id 头"
    ...

运行输出:

$ python3 linked_billing_router.py
自付请求带 billing_policy? False | beta 头? False
200 -                                          -> ok:自己记一笔 bill_to=user_profile(响应里不写谁付的钱)
403 user_profile_not_billable                  -> 重试一次:新连接可能还没生效(10 秒内)
403 user_profile_not_billable                  -> 停止向客户计费;记录 error.message + request-id;可改 bill_to=self 自付
402 linked_organization_spend_limit_reached    -> 提示客户:检查给本应用的 spend cap / 组织月度上限 / 余额
402 linked_organization_billing_unavailable    -> 不重试;提示客户检查 Claude Platform 账户
503 -                                          -> 退避重试,遵守 retry-after(本次未计费)
400 user_profile_required                      -> 代码 bug:缺 anthropic-user-profile-id 头

在 /v1/messages 上,错误码在 error.details.error_code;/v1/chat/completions 返回 OpenAI 格式,状态码和信息一样,但没有这个错误码字段,路由只能按状态码和 message 判断。

常见坑

完成标准

这次更新的要点见站内关联计费快讯。

最后

先把产品里最费 token 的那个功能挑出来,只对它开 bill_to: "user_profile",其余请求保持自付,用测试应用跑通一个内部组织再发布。

关注公众号「智涌AI速递」

每天的 AI 快讯、实用教程和 AI项目实测,也会同步发到微信公众号。在微信里搜索「智涌AI速递」就能关注;不用微信的话,可以用 RSS 订阅本站。