政策与文档核对日期：2026 年 11 月 5 日。终端示例统一使用 Bash，适用于 macOS、Linux，以及采用 Bash 的开发环境。
购买 Max、Ultra 或 Team 后，赠送的 API 额度需要先关联到一个 Claude Console 组织，才能用于自己的程序或代理。
整套流程可以按下面的顺序完成：
确认资格 → 关联 Console 组织 → 查看赠送余额 → 创建 API key → 发出小请求 → 核对组织和使用记录 → 配置 claude -p。
其中最重要的一点是：订阅账号、Console 组织、API key 和实际请求的计费路径必须对应。能收到模型回复，只能说明请求成功；确认使用了哪一个组织、哪一笔余额，还要继续核对。
一、先确认自己能领取多少，以及由谁领取
当前这项月度 API 赠送计划的额度如下：
| 套餐或席位 | 每月赠送的 API 额度 | 额度归属 |
|---|---|---|
| Max | 100 美元 | 关联的一个 Console 组织 |
| Ultra | 200 美元 | 关联的一个 Console 组织 |
| Team Standard | 每席位 20 美元 | 全队合池 |
| Team Premium | 每席位 100 美元 | 全队合池 |
| Team 全队 | 最多 500 美元 | 同一个组织余额池 |
例如，3 个 Standard 加 2 个 Premium，名义月赠额度为：
3 × 20 + 2 × 100 = 260 美元10 个 Premium 也仍然受全队每月 500 美元上限约束。
领取前需要满足两个条件：套餐活跃且状态良好；新订阅者已经在合资格套餐上满七天。通过 iOS 或 Android 购买的订阅也可以参加，但领取需要在网页端操作，无需先给 Claude Platform 添加支付卡。
还要检查两边的权限：
| 在哪里 | 领取所需身份 |
|---|---|
| Max／Ultra 订阅侧 | 订阅者本人 |
| Team 订阅侧 | Primary Owner 或 Owner |
| 接收额度的 Console 组织 | Owner、Admin 或 Billing |
这里的七天是 API credits 的领取资格门槛，不能拿来推断 Ultra 自动验证的完成时间。
二、在网页上关联 Console 组织，领取额度
Max、Ultra 的操作入口是：
Team 则由 Owner 或 Primary Owner 进入：
按以下步骤操作：
- 找到 API credits 区域。
- 点击 Link organization。
- 选择接收额度的 Claude Console 组织；如果还没有组织，可以按照页面流程创建。
- 核对组织名称和实际用途。
- 阅读相关条款，确认关联。
- 打开 Console 的 Billing 页面，检查额度是否入账。
关联前务必选对组织。当前规则是一份套餐只能关联一个 Console 组织，一个 Console 组织也只能接收一份套餐的这项赠送；关联后不能自行更换，需要联系支持处理。
Team 成员无需每人重复领取：由有权限的负责人关联组织，后续在该组织下使用 API key 的成员共同消耗这笔余额。
如果没有看到领取入口，先核对套餐、订阅时长、当前登录身份和两边的角色，再联系官方支持。
三、在哪里查看余额，应该看哪些字段
领取后，打开：
首先查看 Promotional credits，重点记录：
- 本次赠送金额；
- 当前显示的可用余额；
- 到期日期；
- 当前选中的 Console 组织。
然后分别检查购入余额和 Auto-reload 配置。
月赠额度先于购入额度消耗，未用完的部分按对应周期到期，不结转。年付套餐也按月发放。需要特别留意：自动充值根据购入余额触发，即使赠送额度还有剩余，也可能发生充值。
实际核账时，下面三类数字要分开：
| 数字 | 用来回答什么问题 |
|---|---|
| Billing 中的余额、赠送记录和到期日 | 还有多少额度、来自哪里、何时到期 |
| 请求返回的 usage | 这一请求使用了多少 token |
| Usage／Cost 报表或 CLI 的费用估算 | 消耗发生在哪里，大约或实际形成多少成本 |
usage 不能直接当成美元余额；CLI 显示的 total_cost_usd 也不能证明这笔费用已经从赠送额度中扣除。当前 Cost Analytics 的成本字段还是抵扣 credits 之前的口径，报表也可能延迟更新。
四、在正确的 workspace 中创建 API key
打开：
个人练习可以采用以下方式：
- 确认当前 Console 组织就是接收赠送额度的组织。
- 点击 Create key。
- 填写容易识别的名称，例如 monthly-credit-demo。
- 根据需要设置有效期。
- 在 Linked account 中选择自己的账号，创建 personal key。
- 选择自己已经获准访问的普通 API workspace，创建单一 workspace 范围的 key。
- 保存创建时显示的 key，并记下组织、workspace 和 key 名称。
Key 只会在创建时完整显示一次。个人开发使用 personal key 即可；共享服务或生产系统可以再根据组织管理要求采用 service account。
这里还有两个权限细节：
- 能领额度，不代表能创建 key。Billing 角色主要负责账务和用量；创建 key 需要相应的组织及 workspace 权限。
- 创建 workspace 需要组织管理员。普通成员应选择已经获准使用的 workspace，按钮不可用时让管理员核对角色和成员关系。
不要选择 Claude Code 专用 workspace 来手动创建练习用 key；官方说明该 workspace 的 key 由 Claude Code 登录流程管理。
下面的示例统一使用创建时已经选定单一 workspace 的 key。当前 API 对未限定 workspace 的 key 有额外的 workspace header 要求，不能把两种 key 的用法混在一起。
五、准备一个临时终端环境
建议先在一个单独的终端中练习，把 key 只放在当前会话里。
先启动 Bash：
bash --noprofile --norc然后执行：
set +x
umask 077
unset ANTHROPIC_API_KEY
unset ANTHROPIC_AUTH_TOKEN CLAUDE_CODE_OAUTH_TOKEN ANTHROPIC_BASE_URL
unset CLAUDE_CODE_USE_BEDROCK CLAUDE_CODE_USE_VERTEX
unset CLAUDE_CODE_USE_FOUNDRY CLAUDE_CODE_USE_ANTHROPIC_AWS
unset CLAUDE_CODE_EFFORT_LEVEL
mkdir -p "$HOME/claude-api-credit-demo"
cd "$HOME/claude-api-credit-demo"这些临时设置用于把本次练习明确指向第一方 API。公司管理的 Claude Code 仍可能受到组织网关或 provider 策略约束，出现路由不符时应联系管理员核对。
接下来，单独执行下面这一行，粘贴刚创建的 key，再按回车。输入内容不会回显：
read -r -s -p '粘贴关联组织的 API key，然后按回车：' ANTHROPIC_API_KEY输入完成后，再执行：
printf '\n'
export ANTHROPIC_API_KEY不要把真实 key 写进文章示例、脚本源码或命令历史，也不需要用 echo 把它打印出来确认。
六、用 curl 发出第一个小请求
本次连通性示例固定使用 claude-haiku-5-5，限制输出，并关闭 thinking。这里的参数组合针对该模型；切换模型时需要重新核对支持的参数。
先创建请求文件：
cat > request.json <<'JSON'
{
"model": "claude-haiku-5-5",
"max_tokens": 128,
"thinking": {
"type": "disabled"
},
"output_config": {
"effort": "low"
},
"messages": [
{
"role": "user",
"content": "只回复：API连接成功"
}
]
}
JSON然后发送请求：
curl --disable --silent --show-error \
--connect-timeout 10 --max-time 60 \
--dump-header response.headers \
--output response.json \
--write-out 'HTTP %{http_code}\n' \
--config - <<EOF
url = "https://api.anthropic.com/v1/messages"
request = "POST"
header = "Authorization: Bearer ${ANTHROPIC_API_KEY}"
header = "anthropic-version: 2026-10-21"
header = "content-type: application/json"
data-binary = "@request.json"
EOF这条命令会生成两个文件：
- response.json：响应正文，包括内容、结束原因和 token 用量；
- response.headers：响应头，用于核对请求标识及组织、workspace 等信息。
Key 通过 curl 的标准输入传入，不直接放进命令行参数。--disable 放在最前面，用于避免已有 .curlrc 改变这次小测试的行为。
当前官方 API 使用 2026-10-21 版本，支持以 Authorization: Bearer 传入 API key；单一 workspace key 可以省略 workspace 选择 header。
查看响应正文：
python3 -m json.tool response.json重点检查：
- HTTP 是否为 200。
- content 中是否出现文本内容。
- stop_reason 是正常结束，还是达到 max_tokens。
- usage 中实际报告了多少输入、输出及缓存 token。
再提取需要核对的响应头：
python3 - <<'PY'
from pathlib import Path
wanted = {
"request-id",
"anthropic-organization-id",
"anthropic-workspace-id",
}
for line in Path("response.headers").read_text(
errors="replace"
).splitlines():
name, sep, value = line.partition(":")
if sep and name.lower() in wanted:
print(name.lower() + ":", value.strip())
PY将返回的组织、workspace 标识与 Console 中的记录对应起来。请求成功、组织对应、使用记录也落在预期 workspace，才形成了完整的调用核对链条。
七、用 Python SDK 调用同一笔额度
如果准备把 API 接进自己的程序，可以使用官方 Python SDK。当前文档要求 Python 3.10 或以上。
在练习目录中建立虚拟环境：
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade anthropic创建 call_api.py：
import json
import os
import anthropic
with anthropic.Anthropic(
api_key=os.environ["ANTHROPIC_API_KEY"],
base_url="https://api.anthropic.com",
timeout=30.0,
max_retries=0,
) as client:
raw = client.messages.with_raw_response.create(
model="claude-haiku-5-5",
max_tokens=128,
thinking={"type": "disabled"},
output_config={"effort": "low"},
messages=[
{"role": "user", "content": "只回复：API连接成功"}
],
)
message = raw.parse()
for name in (
"request-id",
"anthropic-organization-id",
"anthropic-workspace-id",
):
print(name + ":", raw.headers.get(name, "(not returned)"))
print("model:", message.model)
print("stop_reason:", message.stop_reason)
for block in message.content:
if block.type == "text":
print(block.text)
print(json.dumps(message.usage.model_dump(), ensure_ascii=False))运行：
python call_api.pyraw.parse() 解析的是已经收到的响应，不会再发送一次模型请求。示例将自动重试关闭，方便首次验收时把一次执行与一次请求对应起来；后续生产系统可以再按业务需要设计重试。
八、配置 claude -p 使用这笔额度
官方明确列出了一个重要的覆盖条件：
自己运行 claude -p 或 Agent SDK，并使用关联 Console 组织的 API key，可以使用这笔月赠额度。
如果使用的是 Claude 订阅登录身份，消耗仍属于订阅计划。由 Claude Code GitHub Action、IDE 扩展或 Claude 桌面应用发起的运行，即使带有 -p，也不能套用上述覆盖条件。
因此，这一节应在自己打开的独立系统终端中操作，并继续使用前面已经配置好的 API key。
先检查版本：
claude --version本文采用 Haiku 5.5 完整模型 ID，官方要求 Claude Code v2.1.293 或以上。未安装或版本较旧时，按自己的安装方式遵循官方安装与更新说明处理。
可以先做身份来源诊断：
claude auth status当前 JSON 输出中的 authMethod 可以帮助判断身份来源，例如 api_key、claude.ai 或 third_party。
不过，api_key 只表示识别到了这种认证来源，不能单独证明 key 有效、属于正确组织，或赠送余额已经入账。
接着运行一个最小任务：
claude --bare -p '只回复：API连接成功' \
--model claude-haiku-5-5 \
--effort low \
--tools '' \
--max-turns 1 \
--max-budget-usd 0.10 \
--output-format json \
--no-session-persistence > claude-result.json这些参数分别控制什么：
| 参数 | 在本次练习中的作用 |
|---|---|
| --bare | 不读取 OAuth／系统 keychain，跳过 hooks、skills、插件、MCP 等自动发现 |
| -p | 非交互运行，输出结果后退出 |
| --model | 指定模型，避免沿用日常会话的模型选择 |
| --effort low | 请求较低推理投入 |
| --tools '' | 关闭内置工具，先只验证文本调用 |
| --max-turns 1 | 限制代理轮数 |
| --max-budget-usd 0.10 | 设置客户端估算费用阈值 |
| --output-format json | 保留便于检查的结构化结果 |
| --no-session-persistence | 不保存这次会话供后续恢复 |
--bare 仍支持显式指定的配置和云平台凭证，因此前面的环境检查仍然重要。这里没有额外传入 MCP、插件或附加目录。
另外，--max-budget-usd 依据的是客户端费用估算，不是账单绝对不会超过的硬上限；--max-turns 也不等于 token 上限。扩大任务规模前，还需要设置 Console 的消费控制。
查看结果：
python3 - <<'PY'
import json
from pathlib import Path
data = json.loads(Path("claude-result.json").read_text())
print("is_error:", data.get("is_error"))
print("result:", data.get("result"))
print("estimated_cost_usd:", data.get("total_cost_usd"))
print("usage:", data.get("usage"))
PY如果字段没有返回，就保持未知，不要自动补成零。命令退出失败时，也要查看标准错误和结果文件，不能把“解析步骤没有输出”理解为没有发生请求。
九、怎样确认消耗路径正确
完成小测试后，按下面的顺序核对：
- Key 归属正确：是在接收赠额的 Console 组织中创建的。
- Workspace 正确：创建 key 时选择了目标 workspace；API 响应提供的标识也能对应。
- 调用入口正确：第一方 API，或者符合官方条件、自己运行的 claude -p。
- 使用记录正确：Console 中对应 workspace 出现了这次使用。
- 余额记录正确：结合 Promotional credits、购入余额、入账与到期记录核账。
当组织同时存在赠送和购入余额时，平台按规则先使用赠送余额。不需要为每次请求额外添加一个“使用赠送额度”的参数。
报表可能存在更新延迟，小请求的费用也可能很低，界面暂时看不出明显变化时，不要通过连续重跑来“刷出变化”。
十、常见问题怎么排查
| 现象 | 优先检查 |
|---|---|
| 看不到 API credits 入口 | 套餐、七天资格、当前登录身份、两边角色 |
| 能领取，但 Create key 不可用 | Console 角色、workspace 成员关系及创建权限 |
| HTTP 401 | Key 是否正确、有效、已导出到当前 shell |
| HTTP 403 | Key、workspace、模型或资源访问权限 |
| HTTP 400 | 读取具体错误类型，核对请求参数、版本、workspace 及相关消费限制 |
| HTTP 402／billing_error | 组织账务、余额和支付状态 |
| HTTP 404 | 模型 ID、端点及资源是否可用 |
| HTTP 429 | 区分请求／token 速率限制和相关消费上限，查看具体错误与响应信息 |
| stop_reason 为 max_tokens | 输出达到上限；请求可能已成功，但内容未完整 |
| curl 能调用，CLI 不能 | CLI 版本、API key 环境、provider／网关路由和组织策略 |
| CLI 能运行，但赠额没有明显减少 | 是否符合覆盖条件、组织是否正确、是否有报表延迟或显示精度影响 |
Team 负责人还应给项目分配合适的 workspace 和成员权限，并设置消费提醒。Default Workspace 当前不支持单独设置 workspace 消费上限；需要项目级预算时，应由管理员建立合适的普通 API workspace。
练习完成后，可以清理当前会话中的 key，再退出这个临时 Bash：
unset ANTHROPIC_API_KEY
exit这样，本次子 shell 的临时环境设置结束，父终端原来的环境仍然保留。
完整示例可在下方下载，方便在自己的练习目录中审阅和使用。代码经过语法及离线流程校验，未使用读者账号执行真实模型请求。