​
1. 创建新的 API Key

POST /v1/apikeys
创建一个新的 API Key，可选择将其分配到指定的分组，并可同时设置各类型限额。

​
鉴权方式

Authorization: Bearer <API Key>
本页接口仅允许使用账号的默认 API Key 调用。使用其他 API Key 调用会返回 403 Forbidden。

​
请求体

{
  "name": "生产环境-API-Key-001",
  "group_id": "6a06f7db38b3bf1609a9c200",
  "budget": 100.0,
  "expiry_date": "2026-12-31",
  "daily_limit": 10.0,
  "monthly_limit": 50.0,
  "input_price_limit": 5.0,
  "output_price_limit": 15.0
}
字段类型必需说明
namestring✅API Key 名称，不能为空、不能超过 128 个字符
group_idstring❌分组 ID，如果指定则将创建的 API Key 分配到该分组
budgetnumber❌总额度限额（元），0 表示无限制
expiry_datestring❌有效期截止日期，格式 YYYY-MM-DD，不传则永不过期
daily_limitnumber❌每日限额（元），0 表示无限制
monthly_limitnumber❌每月限额（元），0 表示无限制
input_price_limitnumber❌模型输入价格限额（元/M token），0 表示无限制
output_price_limitnumber❌模型输出价格限额（元/M token），0 表示无限制

​
请求示例

curl -X POST https://api.nonelinear.com/v1/apikeys \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "生产环境-API-Key-001",
    "group_id": "6a06f7db38b3bf1609a9c200",
    "budget": 100.0,
    "expiry_date": "2026-12-31",
    "daily_limit": 10.0,
    "monthly_limit": 50.0
  }'

​
成功响应 (201)

{
  "success": true,
  "message": "API Key 创建成功",
  "apikey": "sk-f23118d4b23c456d789e0123f456g789",
  "name": "生产环境-API-Key-001",
  "group_id": "6a06f7db38b3bf1609a9c200",
  "budget": 100.0,
  "expiry_date": "2026-12-31",
  "daily_limit": 10.0,
  "monthly_limit": 50.0,
  "input_price_limit": null,
  "output_price_limit": null
}
字段类型说明
successboolean是否成功
messagestring操作提示信息
apikeystring新创建的 API Key
namestringAPI Key 名称
group_idstring / null分配的分组 ID，未指定则为 null
budgetnumber / null总额度限额（元），未传则为 null
expiry_datestring / null有效期截止日期，未传则为 null
daily_limitnumber / null每日限额（元），未传则为 null
monthly_limitnumber / null每月限额（元），未传则为 null
input_price_limitnumber / null输入价格限额（元/M token），未传则为 null
output_price_limitnumber / null输出价格限额（元/M token），未传则为 null

​
错误响应

状态码说明示例
400请求参数错误缺少名称、名称过长、分组不存在、类型错误、限额为负数等
401API Key 缺失或无效-
403API Key 有效但不是默认 Key"仅允许使用默认 API Key 创建 API Key"
500服务器内部错误{"success": false, "error": "创建 API Key 失败"}

​
常见错误响应

{
  "success": false,
  "error": "API Key 名称不能为空"
}

{
  "success": false,
  "error": "API Key 名称长度不能超过 128 个字符"
}

{
  "success": false,
  "error": "参数 name 类型错误，期望 str，实际收到 int"
}

{
  "success": false,
  "error": "指定的分组不存在"
}

{
  "success": false,
  "error": "分组 ID 格式错误"
}

{
  "success": false,
  "error": "budget 不能为负数"
}

{
  "success": false,
  "error": "daily_limit 格式不正确，期望数字"
}

{
  "success": false,
  "error": "expiry_date 格式不正确，期望 YYYY-MM-DD"
}

​
参数验证规则

​
API Key 名称 (name)

  • 必需：是
  • 类型：string
  • 长度：1-128 个字符
  • 说明：用于标识和区分不同的 API Key
  • 示例：
    • ✅ "生产环境-Key-001"
    • ✅ "测试环境"
    • ❌ "" (空字符串)
    • ❌ "x" * 129 (超过 128 字符)

​
分组 ID (group_id)

  • 必需：否（可选）
  • 类型：string
  • 格式：MongoDB ObjectId 格式
  • 说明：指定 API Key 所属的分组，如不指定则创建未分组的 API Key
  • 示例：
    • ✅ "6a06f7db38b3bf1609a9c200"
    • ❌ 123 (应为字符串)
    • ❌ "invalid-id" (无效的 ObjectId 格式)
    • ❌ 引用不存在的分组

​
总额度限额 (budget)

  • 必需：否（可选）
  • 类型：number
  • 约束：不能为负数，0 表示无限制
  • 说明：API Key 的累计消费上限（元）

​
有效期 (expiry_date)

  • 必需：否（可选）
  • 类型：string
  • 格式：YYYY-MM-DD
  • 说明：API Key 的到期日期，不传表示永不过期
  • 示例：✅ "2026-12-31"，❌ "2026/12/31"，❌ 20261231

​
每日限额 (daily_limit)

  • 必需：否（可选）
  • 类型：number
  • 约束：不能为负数，0 表示无限制
  • 说明：API Key 单日消费上限（元）

​
每月限额 (monthly_limit)

  • 必需：否（可选）
  • 类型：number
  • 约束：不能为负数，0 表示无限制
  • 说明：API Key 单月消费上限（元）

​
输入价格限额 (input_price_limit)

  • 必需：否（可选）
  • 类型：number
  • 约束：不能为负数，0 表示无限制
  • 说明：允许调用的模型输入价格上限（元/M token），超出此价格的模型将被拒绝

​
输出价格限额 (output_price_limit)

  • 必需：否（可选）
  • 类型：number
  • 约束：不能为负数，0 表示无限制
  • 说明：允许调用的模型输出价格上限（元/M token），超出此价格的模型将被拒绝

​
应用场景

​
场景 1：创建一个未分组的 API Key

curl -X POST https://api.nonelinear.com/v1/apikeys \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "我的第一个API Key"}'
响应： 
{
  "success": true,
  "message": "API Key 创建成功",
  "apikey": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "name": "我的第一个API Key",
  "group_id": null,
  "budget": null,
  "expiry_date": null,
  "daily_limit": null,
  "monthly_limit": null,
  "input_price_limit": null,
  "output_price_limit": null
}

​
场景 2：创建 API Key 并分配到生产环境分组

curl -X POST https://api.nonelinear.com/v1/apikeys \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "生产API-002",
    "group_id": "6a06f7db38b3bf1609a9c200"
  }'
响应： 
{
  "success": true,
  "message": "API Key 创建成功",
  "apikey": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "name": "生产API-002",
  "group_id": "6a06f7db38b3bf1609a9c200",
  "budget": null,
  "expiry_date": null,
  "daily_limit": null,
  "monthly_limit": null,
  "input_price_limit": null,
  "output_price_limit": null
}

​
场景 3：创建时同时设置限额

curl -X POST https://api.nonelinear.com/v1/apikeys \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "受控API-001",
    "group_id": "6a06f7db38b3bf1609a9c200",
    "budget": 200.0,
    "expiry_date": "2026-12-31",
    "daily_limit": 20.0,
    "monthly_limit": 100.0,
    "input_price_limit": 5.0,
    "output_price_limit": 15.0
  }'
响应： 
{
  "success": true,
  "message": "API Key 创建成功",
  "apikey": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "name": "受控API-001",
  "group_id": "6a06f7db38b3bf1609a9c200",
  "budget": 200.0,
  "expiry_date": "2026-12-31",
  "daily_limit": 20.0,
  "monthly_limit": 100.0,
  "input_price_limit": 5.0,
  "output_price_limit": 15.0
}

​
Python 调用示例

import requests
import json

BASE_URL = 'https://api.nonelinear.com'

def create_apikey(
    apikey: str,
    name: str,
    group_id: str = None,
    budget: float = None,
    expiry_date: str = None,
    daily_limit: float = None,
    monthly_limit: float = None,
    input_price_limit: float = None,
    output_price_limit: float = None,
) -> dict:
    """
    创建新的 API Key

    Args:
        apikey: 默认 API Key（用于鉴权）
        name: API Key 名称
        group_id: 可选，分组 ID
        budget: 可选，总额度限额（元），0 表示无限制
        expiry_date: 可选，有效期截止日期，格式 YYYY-MM-DD
        daily_limit: 可选，每日限额（元）
        monthly_limit: 可选，每月限额（元）
        input_price_limit: 可选，输入价格限额（元/M token）
        output_price_limit: 可选，输出价格限额（元/M token）

    Returns:
        dict: 包含新创建的 API Key 信息
    """
    payload = {'name': name}
    if group_id is not None:
        payload['group_id'] = group_id
    if budget is not None:
        payload['budget'] = budget
    if expiry_date is not None:
        payload['expiry_date'] = expiry_date
    if daily_limit is not None:
        payload['daily_limit'] = daily_limit
    if monthly_limit is not None:
        payload['monthly_limit'] = monthly_limit
    if input_price_limit is not None:
        payload['input_price_limit'] = input_price_limit
    if output_price_limit is not None:
        payload['output_price_limit'] = output_price_limit

    resp = requests.post(
        f'{BASE_URL}/v1/apikeys',
        headers={
            'Authorization': f'Bearer {apikey}',
            'Content-Type': 'application/json'
        },
        json=payload
    )
    resp.raise_for_status()
    return resp.json()


if __name__ == '__main__':
    DEFAULT_API_KEY = '<你的默认APIKey>'

    # 创建未分组的 API Key
    result1 = create_apikey(DEFAULT_API_KEY, '测试API-001')
    print("创建未分组的 API Key:")
    print(json.dumps(result1, indent=2, ensure_ascii=False))

    # 创建分组的 API Key 并设置限额
    result2 = create_apikey(
        DEFAULT_API_KEY,
        '生产API-001',
        group_id='6a06f7db38b3bf1609a9c200',
        budget=200.0,
        expiry_date='2026-12-31',
        daily_limit=20.0,
        monthly_limit=100.0,
    )
    print("\n创建带限额的 API Key:")
    print(json.dumps(result2, indent=2, ensure_ascii=False))

​
2. 设置指定 API Key 的限额

POST /v1/apikeys/<apikey_id>/budget
给指定 API Key 设置各类型限额。apikey_id 为目标 API Key 的前 10 位字符。

​
鉴权方式

Authorization: Bearer <API Key>
⚠️ 仅允许使用该账号的默认 API Key，其他 Key 将返回 403 Forbidden。

​
路径参数

参数说明
apikey_id目标 API Key 的前 10 位，例如 sk-f23118d4

​
请求体

{
  "budget": 100.0,
  "expiry_date": "2026-12-31",
  "daily_limit": 10.0,
  "monthly_limit": 50.0,
  "input_price_limit": 5.0,
  "output_price_limit": 15.0
}
字段类型必需说明
budgetnumber❌总额度限额（元），0 表示无限制
expiry_datestring❌有效期截止日期，格式 YYYY-MM-DD，不传则清除有效期
daily_limitnumber❌每日限额（元），0 表示无限制
monthly_limitnumber❌每月限额（元），0 表示无限制
input_price_limitnumber❌模型输入价格限额（元/M token），0 表示无限制
output_price_limitnumber❌模型输出价格限额（元/M token），0 表示无限制
至少需要传一项限额参数。

​
请求示例

curl -X POST https://api.nonelinear.com/v1/apikeys/sk-f23118d4/budget \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "budget": 100.0,
    "expiry_date": "2026-12-31",
    "daily_limit": 10.0,
    "monthly_limit": 50.0
  }'

​
成功响应 (200)

{
  "success": true,
  "message": "预算设置成功，限额为 100.0000 元，有效期至 2026-12-31，每日限额：10.0000元，每月限额：50.0000元",
  "budget": 100.0,
  "expiry_date": "2026-12-31",
  "daily_limit": 10.0,
  "monthly_limit": 50.0,
  "input_price_limit": null,
  "output_price_limit": null
}

​
错误响应

状态码说明
400参数错误（类型错误、负数、缺少参数、日期格式错误）
401API Key 缺失或无效
403API Key 有效但不是默认 Key
404指定的 API Key 不存在

​
常见错误响应

{"success": false, "error": "至少需要指定一项限额参数"}

{"success": false, "error": "指定的 API Key 不存在"}

{"success": false, "error": "参数 budget 类型错误，期望 int 或 float，实际收到 str"}

{"success": false, "error": "参数 daily_limit 不能为负数"}

{"success": false, "error": "参数 expiry_date 格式错误，应为 YYYY-MM-DD"}

​
最佳实践

​
1. 命名约定

  • 遵循统一的命名规范，便于后续识别和管理
  • 包含环境信息：生产-xxx、测试-xxx、开发-xxx
  • 包含用途或应用：数据分析-API、内容生成-API

​
2. 分组管理

  • 新创建的 API Key 应立即分配到相应分组
  • 同一分组的 API Key 可统一设置限额和有效期
  • 按业务线或部门创建分组，便于成本分配

​
3. 安全建议

  • 每个应用或服务使用不同的 API Key
  • 定期轮换 API Key
  • 避免在代码中硬编码 API Key，使用环境变量或密钥管理服务
  • 为不同环境使用不同的分组和 API Key

​
4. 成本控制

  • 为每个 API Key 设置合理的预算限额
  • 定期监控 API Key 的费用消耗
  • 及时清理不使用的 API Key

​
相关接口