项目、预算与 API Key

使用 Management API Key 管理团队项目、预算和 API Key,并查询项目与 Key 用量

使用 Management API Key 管理团队项目、消费上限和模型 API Key,并查询项目与 Key 用量。

Management key required

本页全部接口使用所属团队的 mgmt-... 管理 Key。请先以团队 Owner 身份在控制台 Developer → Management API Keys 创建,具体步骤见 Management API Keys。

Base URL: https://api.atlascloud.ai/public/v1

请求使用管理 Key 所属的团队账户,权限覆盖该团队的全部项目及成员的模型 API Key。

数量与请求限制

资源当前限制
项目每个 Team 最多 20 个活跃项目,包含默认项目。 已归档项目不计入数量。到达上限后创建返回 409 / project_limit_exceeded。
API Key 数量当前未设置每账户或每项目的固定 Key 数量上限。 仍受权限、账户内名称唯一和请求限流约束,不代表可无限速创建。
项目名称去除两端空白后为 2–64 个 Unicode 字符;账户内唯一,已归档项目仍占用名称。
API Key 名称去除两端空白后为 1–128 个 Unicode 字符;账户内未删除的 Key 名称唯一,包含其他项目中的 Key。仅改变大小写不能避免重名。
JSON 请求体最多 64 KiB;不支持的字段会被拒绝。

计费查询参数 api_key_ids[] 最多接受 100 个过滤条件,这是单次查询限制,不是可创建的 Key 数量上限。Public API 请求限流返回 429,如有 Retry-After,请按其等待后重试。

1. 创建项目并设置初始预算

curl -X POST "https://api.atlascloud.ai/public/v1/projects" \
  -H "Authorization: Bearer $ATLASCLOUD_MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customer-123",
    "description": "Customer 123",
    "budget": {
      "monthly_limit": {"value": "100.00", "currency": "usd"},
      "usage_alert_percent": 80
    }
  }'

在后端保存响应的 id,即项目 UUID,后续示例以 PROJECT_ID 表示。项目、初始预算和创建者的项目管理员成员关系在同一事务中创建。省略 budget、传 null 或 {} 都表示不限额。可选的 description 去除两端空白后最多 50 个 Unicode 字符。

2. 替换项目预算

curl -X PUT "https://api.atlascloud.ai/public/v1/projects/$PROJECT_ID/budget" \
  -H "Authorization: Bearer $ATLASCLOUD_MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "daily_limit": {"value": "20.00", "currency": "usd"},
    "monthly_limit": {"value": "200.00", "currency": "usd"},
    "usage_alert_percent": 80
  }'

PUT 会完整替换预算

请重传所有希望保留的配置。遗漏或为 null 的金额归零:限额为零表示不限额,提醒金额为零表示关闭提醒。遗漏的 usage_alert_percent 归零。发送 {} 会清除全部项目预算限制和提醒。

字段含义
daily_limit当前 UTC 自然日消费上限
weekly_limit当前 UTC 自然周消费上限,每周一 00:00 开始
monthly_limit当前 UTC 自然月消费上限
total_limit项目累计消费上限
daily_alert、monthly_alert日/月消费提醒金额
usage_alert_percent月预算提醒百分比,0–100;大于零时必须设置正数 monthly_limit

金额使用 USD 十进制字符串,最多 8 位整数和 8 位小数。预算响应保留 8 位小数,计费报表响应保留 6 位。这些预算约束的是 Atlas 用量费用,不是你向客户售出的积分或售价。

修改预算保留已有消费,重复 PUT 不会重置消费。将上限提高到已用额度之上后,在现有预算检查刷新、其他账户/项目/成员/Key 条件均满足时,后续请求可以继续。预算不是预付费资金预留机制;并发、在途请求和延迟结算可能产生超额。已归档项目不能修改。

3. 创建绑定项目的 Key

curl -X POST "https://api.atlascloud.ai/public/v1/api-keys" \
  -H "Authorization: Bearer $ATLASCLOUD_MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"name\":\"customer-123-primary\",\"project_id\":\"$PROJECT_ID\"}"

可选字段 expires_at 为未来的 RFC 3339 时间;省略或传 null 表示不过期。响应包含:

  • id:ak_... 形式的稳定标识,不能用于鉴权。
  • key:apikey-... 形式的密钥明文,仅在成功创建时返回一次。
  • project_id、name、redacted、enabled、created_at、expires_at、request_id。

响应带 Cache-Control: no-store。返回的 apikey-... 是模型 API Key,不是管理 Key。该接口不额外设置 Key 自身额度,账户、项目和成员已有消费规则继续生效。

创建响应中的 id,就是后续接口 URL 中的 {api_key_id}。 例如,创建成功返回:

{
  "object": "api_key",
  "id": "ak_0123456789ABCDEFGHIJKL",
  "name": "customer-123-primary",
  "project_id": "019a6eab-7c00-7000-8000-000000000123",
  "key": "apikey-REPLACE_WITH_SECRET_RETURNED_ONCE",
  "redacted": "apikey-xxxx********xxxx",
  "enabled": true,
  "created_at": "2026-11-01T00:00:00Z",
  "expires_at": null,
  "request_id": "req_example"
}
值保存后用于
响应的 id:ak_0123456789ABCDEFGHIJKL后续 URL 的 {api_key_id},也就是示例变量 API_KEY_ID
响应的 key:apikey-...模型调用的 Authorization: Bearer 请求头
控制台创建的管理 Key:mgmt-...项目和 Key 管理接口的 Authorization: Bearer 请求头

例如,查询刚创建的 Key 的用量时,直接将返回的 id 放入 URL:

API_KEY_ID="ak_0123456789ABCDEFGHIJKL"
curl --get "https://api.atlascloud.ai/public/v1/api-keys/$API_KEY_ID/usage" \
  -H "Authorization: Bearer $ATLASCLOUD_MANAGEMENT_API_KEY" \
  --data-urlencode "from=2026-11-01T00:00:00Z" \
  --data-urlencode "to=2026-11-02T00:00:00Z"

停用、删除和设置额度时也使用同一个 API_KEY_ID。请把创建响应的 id 与项目、Key 名称一同保存;当前 Public API 不提供 Key 列表查询。

4. 查询项目列表和详情

curl --get "https://api.atlascloud.ai/public/v1/projects" \
  -H "Authorization: Bearer $ATLASCLOUD_MANAGEMENT_API_KEY" \
  --data-urlencode "status=active" \
  --data-urlencode "limit=20"

curl "https://api.atlascloud.ai/public/v1/projects/$PROJECT_ID" \
  -H "Authorization: Bearer $ATLASCLOUD_MANAGEMENT_API_KEY"

列表接口默认查询 status=active,传 status=archived 查询已归档项目。limit 默认为 100,范围为 1–100。响应包含 data、has_more、next_page 和 request_id,按项目 UUID 升序排列。has_more=true 时,将 next_page 作为下一次请求的 after 参数,并保持 status 不变。末页 next_page=null,空列表为 data=[];分页不保证并发变更期间的快照一致性。

每个项目均包含当前预算。详情接口也可查询已归档项目。不存在或属于其他团队的项目返回 404。

5. 替换 Key 额度

curl -X PUT "https://api.atlascloud.ai/public/v1/api-keys/$API_KEY_ID/allowance" \
  -H "Authorization: Bearer $ATLASCLOUD_MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "periodic",
    "period": "monthly",
    "amount": {"value": "100.00", "currency": "usd"}
  }'

额度接口完整替换 Key 自身的额度策略,type 必填:

类型含义配置要求
unlimited不设置 Key 级消费上限不传 period;amount 省略、null 或零
fixed从 Key 创建时间起累计限额amount 为正数,不传 period
periodic按 UTC 自然周期限额amount 为正数;period 为 daily、weekly 或 monthly

每周从 UTC 周一 00:00 开始。金额沿用项目预算的 USD 格式和 8 位小数精度。响应包含 object=api_key_allowance、api_key_id、type、amount、request_id;周期额度还包含 period。

更新额度不更换密钥,不改变启用状态和创建时间,也不重置已有用量。允许将额度设为低于已用量的值,限制沿用现有网关缓存刷新和结算规则。停用、过期或已归档项目下的 Key 仍可调整额度;已删除 Key 返回 404。

6. 查询项目和 Key 用量

curl --get "https://api.atlascloud.ai/public/v1/projects/$PROJECT_ID/usage" \
  -H "Authorization: Bearer $ATLASCLOUD_MANAGEMENT_API_KEY" \
  --data-urlencode "from=2026-11-01T00:00:00Z" \
  --data-urlencode "to=2026-11-02T00:00:00Z"

curl --get "https://api.atlascloud.ai/public/v1/api-keys/$API_KEY_ID/usage" \
  -H "Authorization: Bearer $ATLASCLOUD_MANAGEMENT_API_KEY" \
  --data-urlencode "from=2026-11-01T00:00:00Z" \
  --data-urlencode "to=2026-11-02T00:00:00Z"

from(包含)和 to(不包含)均必填,为 Unix epoch 之后的 RFC 3339 时间。范围不能为空,最多 31 天,两端必须对齐 UTC 整点。未知或重复的查询参数返回 400。

Key 用量响应示例:

{
  "object": "api_key_usage",
  "api_key_id": "ak_0123456789ABCDEFGHIJKL",
  "from": "2026-11-01T00:00:00Z",
  "to": "2026-11-02T00:00:00Z",
  "requests": 12,
  "successes": 10,
  "failures": 2,
  "amount": {"value": "1.230000", "currency": "usd"},
  "request_id": "req_example"
}

项目用量返回 object=project_usage 和 project_id,不返回 api_key_id。项目统计包含该项目全部成员及请求来源;Key 统计仅包含该 Key 的 API Key 来源。已归档项目、已停用/过期/删除的 Key 仍可查询历史用量。无记录时计数与金额均为零。

这两个接口沿用 Console 的聚合统计。requests 等于 successes + failures,计入已完成或失败的按量请求,排除在途请求和 Coding Plan 请求。amount 为已结算的美元费用,包含已收费的失败请求,保留 6 位小数。聚合和结算存在延迟,近期结果可能变化;这些数据不是即时额度计数器,也不返回 token 数、图片数或视频秒数。查询每日模型计量和费用,请使用模型 API Key 调用独立的 Billing Public API。

7. 归档项目

curl -X POST "https://api.atlascloud.ai/public/v1/projects/$PROJECT_ID/archive" \
  -H "Authorization: Bearer $ATLASCLOUD_MANAGEMENT_API_KEY"

归档不可撤销,无需请求体。归档会一并移除项目成员、失效待审批申请;失去最后一个项目的成员也会退出团队。历史用量保留。项目下的 Key 无法继续调用,但不修改其 enabled 开关;项目不能再创建 Key 或更新预算。

默认项目不能归档(400)。重复归档返回 200 和归档后的项目,没有恢复接口。

8. 停用或删除 Key

curl -X POST "https://api.atlascloud.ai/public/v1/api-keys/$API_KEY_ID/disable" \
  -H "Authorization: Bearer $ATLASCLOUD_MANAGEMENT_API_KEY"

curl -X DELETE "https://api.atlascloud.ai/public/v1/api-keys/$API_KEY_ID" \
  -H "Authorization: Bearer $ATLASCLOUD_MANAGEMENT_API_KEY"

两个接口均无需请求体,可操作本团队任意成员的模型 Key,包括已归档项目下的 Key。停用返回 200,响应包含 object=api_key、id、enabled=false 和 request_id,重复停用仍成功。删除返回 204 且无响应体,重复删除本团队已删除的 Key 同样返回 204。

删除不可撤销,历史用量保留。已删除 Key 不能再停用或调整额度。不存在或属于其他团队的 Key 返回 404。停用和删除沿用现有网关缓存刷新规则。

错误与重试

创建资源的 POST 暂不支持幂等重放。名称重复返回 409 / already_exists,用相同名称重试不能取回原 Key 明文。创建响应丢失时,先在控制台确认资源状态;无法使用的 Key 应删除后重新创建。归档、停用和删除可按上述规则重复请求;重复替换预算或额度不会重置用量。

其他错误沿用 Public API 错误结构:参数错误 400、凭据无效 401、权限不足或项目/账户无效 403、当前账户下找不到项目或 Key 404、请求体过大 413、Content-Type 不支持 415、请求限流 429。排障时保存 request_id。

Last updated on

On this page