项目、预算与 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