配置API Key可用模型范围

本文档面向客户，说明如何通过 AK/SK 鉴权接口为单个 API Key 配置模型可用范围。

功能说明

• 按 API Key 维度配置模型白名单与黑名单。
• 黑名单优先级高于白名单。
• 配置为全量覆盖写入，不支持增量追加或删除单个模型。即接口参数需传完整模型范围
• 仅对非订阅版 API Key 生效；订阅版 API Key 仍按原有订阅权益逻辑判断模型权限。

鉴权方式

• 使用 AK/SK 签名鉴权。
• 请求头：
  • Authorization: Qiniu <ak>:<sign>
• 签名规则与平台其他 AK/SK 接口一致。参考：其他接口文档中的AK/SK 签名算法。

API Key 入参格式

• 接口中的 api_key 必须使用脱敏格式，且格式一致。
• 格式示例：sk-a0******e4b1e（前后保留五位，星号隐藏中间字符六位）。

生效规则

• 若 blocked_models 命中请求模型，直接不可用。
• 若 allowed_models 为空，表示不限制（默认全部可用）。
• 若 allowed_models 非空，仅允许列表内模型。
• 若 blocked_models 为空，表示不额外禁用。

设置模型范围

• 方法：POST
• 域名：https://api.qnaigc.com
• 路径：/v1/apikey/model-scope
• 说明：设置当前 API Key 的模型范围。

请求体示例：

{
  "api_key": "sk-a0******e4b1e",
  "allowed_models": [
    "gpt-4o",
    "claude-3-5-sonnet"
  ],
  "blocked_models": [
    "gpt-4o"
  ]
}

响应体示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "api_key": "sk-a0******e4b1e",
    "allowed_models": [
      "gpt-4o",
      "claude-3-5-sonnet"
    ],
    "blocked_models": [
      "gpt-4o"
    ],
    "created_at": "2026-05-21 16:58:00",
    "updated_at": "2026-05-21 16:58:00"
  }
}

查询模型范围

• 方法：GET
• 域名：https://api.qnaigc.com
• 路径：/v1/apikey/model-scope
• Query 参数：
  • api_key：脱敏 API Key

请求示例：

GET /v1/apikey/model-scope?api_key=sk-a0******e4b1e
Authorization: Qiniu <ak>:<sign>

响应体示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "api_key": "sk-a0******e4b1e",
    "allowed_models": [
      "gpt-4o",
      "claude-3-5-sonnet"
    ],
    "blocked_models": [
      "gpt-4o"
    ],
    "created_at": "2026-05-21 16:58:00",
    "updated_at": "2026-05-21 17:00:00"
  }
}

常见错误说明

错误返回结构如下：

{
  "status": false,
  "error": "ERROR_CODE"
}

错误码明细

• INVALID_MASKED_API_KEY_FORMAT

  • HTTP：200
  • 场景：api_key 脱敏格式不符合要求（示例应为 sk-a0******e4b1e）。

• API_KEY_NOT_FOUND_OR_NOT_OWNED

  • HTTP：200
  • 场景：在当前 AK 对应 uid 下，找不到该脱敏 key 对应的可用 API Key，或 key 不属于该 uid。

• MULTIPLE_MATCHED_API_KEYS

  • HTTP：409
  • 场景：同一 uid 下该脱敏 key 命中多个完整 API Key，存在歧义。

• SUBSCRIPTION_API_KEY_NOT_SUPPORTED

  • HTTP：200
  • 场景：传入订阅版 API Key（sk-plan）进行模型范围配置。

• MODEL_SCOPE_NOT_CONFIGURED

  • HTTP：200
  • 场景：查询时该 API Key 尚未配置模型范围，或该 key 不支持该能力。

• invalid models: xxx,yyy

  • HTTP：400
  • 场景：allowed_models 或 blocked_models 包含不存在的模型 ID。

• INVALID_AKSK_SIGN

  • HTTP：401
  • 场景：AK/SK 签名校验失败。

• INTERNAL_ERROR

  • HTTP：200
  • 场景：服务端内部异常（写库失败等）。

使用建议

• 若返回 MULTIPLE_MATCHED_API_KEYS，请联系平台侧确认该用户下 API Key 信息，以消除歧义后再重试。
• 若需要清空限制，可将 allowed_models 与 blocked_models 均传空数组。