API Key 管理

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
}

字段	类型	必需	说明
`name`	string	✅	API Key 名称，不能为空、不能超过 128 个字符
`group_id`	string	❌	分组 ID，如果指定则将创建的 API Key 分配到该分组
`budget`	number	❌	总额度限额（元），`0` 表示无限制
`expiry_date`	string	❌	有效期截止日期，格式 `YYYY-MM-DD`，不传则永不过期
`daily_limit`	number	❌	每日限额（元），`0` 表示无限制
`monthly_limit`	number	❌	每月限额（元），`0` 表示无限制
`input_price_limit`	number	❌	模型输入价格限额（元/M token），`0` 表示无限制
`output_price_limit`	number	❌	模型输出价格限额（元/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
}

字段	类型	说明
`success`	boolean	是否成功
`message`	string	操作提示信息
`apikey`	string	新创建的 API Key
`name`	string	API Key 名称
`group_id`	string / null	分配的分组 ID，未指定则为 `null`
`budget`	number / null	总额度限额（元），未传则为 `null`
`expiry_date`	string / null	有效期截止日期，未传则为 `null`
`daily_limit`	number / null	每日限额（元），未传则为 `null`
`monthly_limit`	number / null	每月限额（元），未传则为 `null`
`input_price_limit`	number / null	输入价格限额（元/M token），未传则为 `null`
`output_price_limit`	number / null	输出价格限额（元/M token），未传则为 `null`

错误响应

状态码	说明	示例
400	请求参数错误	缺少名称、名称过长、分组不存在、类型错误、限额为负数等
401	API Key 缺失或无效	-
403	API 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
}

字段	类型	必需	说明
`budget`	number	❌	总额度限额（元），`0` 表示无限制
`expiry_date`	string	❌	有效期截止日期，格式 `YYYY-MM-DD`，不传则清除有效期
`daily_limit`	number	❌	每日限额（元），`0` 表示无限制
`monthly_limit`	number	❌	每月限额（元），`0` 表示无限制
`input_price_limit`	number	❌	模型输入价格限额（元/M token），`0` 表示无限制
`output_price_limit`	number	❌	模型输出价格限额（元/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	参数错误（类型错误、负数、缺少参数、日期格式错误）
401	API Key 缺失或无效
403	API 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

平台系列

文本系列

图像系列

视频系列

1. 创建新的 API Key

鉴权方式

请求体

请求示例

成功响应 (201)

错误响应

常见错误响应

参数验证规则

API Key 名称 (name)

分组 ID (group_id)

总额度限额 (budget)

有效期 (expiry_date)

每日限额 (daily_limit)

每月限额 (monthly_limit)

输入价格限额 (input_price_limit)

输出价格限额 (output_price_limit)

应用场景

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

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

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

Python 调用示例

2. 设置指定 API Key 的限额

鉴权方式

路径参数

请求体

请求示例

成功响应 (200)

错误响应

常见错误响应

最佳实践

1. 命名约定

2. 分组管理

3. 安全建议

4. 成本控制

相关接口

​1. 创建新的 API Key

​鉴权方式

​请求体

​请求示例

​成功响应 (201)

​错误响应

​常见错误响应

​参数验证规则

​API Key 名称 (name)

​分组 ID (group_id)

​总额度限额 (budget)

​有效期 (expiry_date)

​每日限额 (daily_limit)

​每月限额 (monthly_limit)

​输入价格限额 (input_price_limit)

​输出价格限额 (output_price_limit)

​应用场景

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

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

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

​Python 调用示例

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

​鉴权方式

​路径参数

​请求体

​请求示例

​成功响应 (200)

​错误响应

​常见错误响应

​最佳实践

​1. 命名约定

​2. 分组管理

​3. 安全建议

​4. 成本控制

​相关接口

1. 创建新的 API Key

鉴权方式

请求体

请求示例

成功响应 (201)

错误响应

常见错误响应

参数验证规则

API Key 名称 (name)

分组 ID (group_id)

总额度限额 (budget)

有效期 (expiry_date)

每日限额 (daily_limit)

每月限额 (monthly_limit)

输入价格限额 (input_price_limit)

输出价格限额 (output_price_limit)

应用场景

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

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

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

Python 调用示例

2. 设置指定 API Key 的限额

鉴权方式

路径参数

请求体

请求示例

成功响应 (200)

错误响应

常见错误响应

最佳实践

1. 命名约定

2. 分组管理

3. 安全建议

4. 成本控制

相关接口