工作区预算

按工作区设置消费限额并自动强制执行

工作区预算可限制某个工作区在 OpenRouter 推理上的支出。你可以在每日、每周、每月或终身等任意组合的区间上设置美元限额，一旦达到限额，OpenRouter 会自动阻止请求。

工作原理

每个工作区最多可以有四个预算，每个区间一个：

请求进入时，OpenRouter 会对照每项已配置预算检查该工作区的当前支出。如果任一预算已达到或超出，请求会返回 403 Forbidden 错误：

Workspace monthly budget of $500.00 exceeded. Contact your org admin.

错误信息会指出被超出的最宽区间，以便用户知道是哪项限额触发了拦截。

排序规则

预算限额必须随区间变窄而严格递减：

lifetime > monthly > weekly > daily

例如，如果每月预算为 $1,000，则每周预算必须小于$1,000，每日预算必须小于每周预算。不必设置全部四个区间——只需保证已设置的区间遵循此排序。

在控制台中设置预算

1. 前往工作区的 设置（Settings） 页面：https://openrouter.ai/workspaces/<slug>/settings
2. 滚动到 预算（Budgets） 部分
3. 点击 添加预算（Add budget），选择区间并输入美元金额
4. 对其他区间重复此操作
5. 点击 保存（Save）

每行预算会显示当前周期支出相对限额的进度条。如果支出已经超出限额，进度条会变红并出现警告。

预算行上方的 计入 BYOK 支出（Include BYOK spend） 开关控制 BYOK 推理支出是否计入这些限额。它作用于整个工作区，因此会同时影响所有区间。API 对应项见 计入 BYOK 支出。

通过 API 设置预算

你也可以使用组织 管理 API 密钥 以编程方式管理预算。管理密钥在账户层面运行，可以对所有工作区执行管理操作。预算端点位于 /api/v1/workspaces/{id}/budgets。

列出预算

curl https://openrouter.ai/api/v1/workspaces/{workspace_id}/budgets \
  -H "Authorization: Bearer $MANAGEMENT_KEY"

{
  "data": [
    {
      "id": "770e8400-e29b-41d4-a716-446655440000",
      "workspace_id": "880e8400-e29b-41d4-a716-446655440000",
      "limit_usd": 1000,
      "reset_interval": "monthly",
      "created_at": "2025-08-24T10:30:00Z",
      "updated_at": "2025-08-24T15:45:00Z"
    }
  ],
  "include_byok_in_budgets": false
}

include_byok_in_budgets 与 data 并列，而不是出现在每一行预算上，因为它作用于整个工作区，而不是单个区间。参见 计入 BYOK 支出。

创建或更新预算

使用带区间路径的 PUT。如果该区间的预算已存在，则会更新。

curl -X PUT https://openrouter.ai/api/v1/workspaces/{workspace_id}/budgets/monthly \
  -H "Authorization: Bearer $MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit_usd": 1000}'

有效区间：daily、weekly、monthly、lifetime。

响应会回显已创建或更新的预算，以及该工作区当前的 BYOK 设置：

{
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440000",
    "workspace_id": "880e8400-e29b-41d4-a716-446655440000",
    "limit_usd": 1000,
    "reset_interval": "monthly",
    "created_at": "2025-08-24T10:30:00Z",
    "updated_at": "2025-08-24T15:45:00Z"
  },
  "include_byok_in_budgets": false
}

服务器会校验排序规则——如果新限额会违反相对现有预算的严格递减约束，请求会返回 400 Bad Request，消息类似：

Budget limits must be strictly decreasing as scope narrows:
the monthly limit ($500) must be greater than the weekly limit ($600).

计入 BYOK 支出

默认情况下，只有 OpenRouter 积分支出会计入工作区预算。将 include_byok_in_budgets 设为 true，也会计入 BYOK 推理支出——即如果该请求未使用你自己的模型服务提供商密钥，OpenRouter 本应收取的金额：

curl -X PUT https://openrouter.ai/api/v1/workspaces/{workspace_id}/budgets/monthly \
  -H "Authorization: Bearer $MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit_usd": 1000, "include_byok_in_budgets": true}'

这与控制台预算部分中的 计入 BYOK 支出 开关是同一设置。

关于该字段需要了解两点：

• 它作用于整个工作区。 请求 URL 中的区间不会限定 BYOK 计入范围。
• 省略该字段则保持当前设置不变。 仅在打算更改时发送；显式发送 false 会关闭计入。

列表和 upsert 端点都会返回当前值，工作区资源本身（GET /api/v1/workspaces/{id}）也会返回。

删除预算

curl -X DELETE https://openrouter.ai/api/v1/workspaces/{workspace_id}/budgets/monthly \
  -H "Authorization: Bearer $MANAGEMENT_KEY"

{
  "deleted": true
}

删除不存在的预算也会返回成功（幂等）。

支出跟踪

预算强制执行使用 OpenRouter 的用量流水线，按每个区间窗口跟踪各工作区的支出。控制台中的进度条会显示相对每项已配置限额的实时支出。

默认情况下，只有 OpenRouter 积分支出会计入预算。启用 计入 BYOK 支出 后，BYOK 推理支出会加到同一总计中。

创建工作区时，每个区间的支出都从零开始。周期性预算（每日、每周、每月）会在每个周期开始时自动重置。终身预算会无限累积。

创建工作区时设置预算

企业版组织管理员也可以在创建新工作区时设置预算。工作区创建表单包含可选的 预算 部分，可在签发任何密钥之前配置限额，以及 计入 BYOK 支出 开关。

常见问题