使用 API 密钥进行身份验证

CLEVI 网关通过一个 API 密钥对 OpenAI 兼容路径和 Anthropic 兼容路径进行身份验证。
客户端需要设置的值有两个：用于放置密钥的身份验证请求头和 SDK 的 base URL；允许的请求头格式和 base URL 因规范而异。
完成设置后，查询模型列表即可立即确认是否通过身份验证。
身份验证失败时返回 401；通过身份验证后未满足权限或额度条件时返回 403。

请在控制台的 API 密钥页面签发 API 密钥。您也可以在同一页面管理密钥的撤销和使用范围。

身份验证请求头

两种规范都将 API 密钥放在一个请求头中。可以使用 X-API-Key 请求头或 Authorization 请求头之一，允许的格式因规范而异。

在 OpenAI 兼容路径中使用 Authorization 请求头时，需要 Bearer 前缀。如果不带前缀直接发送密钥，网关将拒绝请求。

请求头名称不区分大小写，因此 Anthropic SDK 发送的 x-api-key 请求头也可以直接使用。如果同时指定两个请求头，将优先使用 X-API-Key 的值。

base URL

对于现有 SDK，只需将 base URL 更改为以下地址即可继续使用。两个地址的区别在于是否包含 /v1，请根据规范直接指定相应地址。

确认身份验证

设置密钥和 base URL 后查询模型列表，即可确认是否通过认证。下面的示例分别使用 curl、OpenAI SDK 和 Anthropic SDK 执行相同的查询。请将 API 密钥页面中签发的密钥填入 sk-... 的位置。

使用 curl 查询时，两种规范都要指定包括 /v1/models 在内的完整路径。第一条命令在 OpenAI 兼容路径中使用 X-API-Key 标头，第二条命令在 Anthropic 兼容路径中使用 Authorization 标头。

curl https://platform.clevi.net/api/v2/aiservice/openai/v1/models \
  -H "X-API-Key: sk-..."

curl https://platform.clevi.net/api/v2/aiservice/anthropic/v1/models \
  -H "Authorization: Bearer sk-..." \
  -H "anthropic-version: 2023-06-01"

OpenAI SDK 的 base_url 应指定为包含 /v1 的地址。

from openai import OpenAI

client = OpenAI(
    api_key="sk-...",
    base_url="https://platform.clevi.net/api/v2/aiservice/openai/v1",
)

for model in client.models.list():
    print(model.id)

Anthropic SDK 的 base_url 应指定为在 /v1 之前结束的地址。
认证时直接使用 SDK 发送的 x-api-key 标头。

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-...",
    base_url="https://platform.clevi.net/api/v2/aiservice/anthropic",
)

for model in client.models.list(limit=20).data:
    print(model.id)

无论哪个示例，只要响应为 200，即表示认证成功；响应中的 data 包含可使用此密钥调用的模型列表。如果响应为 401，请按照下一节的顺序检查原因。

认证失败

如果未提供密钥，或发送了已过期、已撤销的密钥，则返回 401。在 OpenAI 兼容路径中不提供密钥进行调用时，将返回以下正文；在 Anthropic 兼容路径中，error.type 为 authentication_error。

{
  "error": {
    "message": "API key is required.",
    "type": "invalid_request_error"
  }
}

收到 401 时，请按以下顺序检查。

1. 在 API 密钥页面确认密钥状态。如果密钥已过期或已撤销，请重新签发。
2. 确认标头名称是否为 X-API-Key 或 Authorization。
3. 如果在 OpenAI 兼容路径中使用 Authorization 标头，请确认是否包含 Bearer 前缀。

修改后，重新执行认证确认一节中的模型列表查询，确认是否返回 200。

配合使用的标头

以下标头均为可选项。为便于追踪问题，建议指定 X-Request-Id。

如果 5xx 错误反复出现，请通过帮助中心和咨询渠道，连同 X-Request-Id 一起告知我们。如果是直接指定的值，则可以立即与客户端记录进行比对。