鉴权

所有对外接口都用 API Key(xsk_ 前缀)鉴权。网关接受三种请求头,分别对应不同官方 SDK 的默认行为——你无需自己拼头,按下方把 SDK 的 base_url / api_key 配好即可。

三种鉴权头

请求头	取值	适用 SDK
Authorization	Bearer xsk_...	OpenAI SDK、火山 Seedance SDK、通用 HTTP 客户端
x-api-key	xsk_...	Anthropic SDK(默认头)
x-goog-api-key	xsk_...	Google Gen AI SDK(默认头)

大小写不敏感

请求头名称大小写不敏感(X-Api-Key 与 x-api-key 等价)。所有头的值都必须以 xsk_ 开头。

各 SDK 配置示例

OpenAI SDK

OpenAI SDK 默认通过 Authorization: Bearer 发送 api_key,因此只需配置 base_url 与 api_key:

Python

from openai import OpenAI

client = OpenAI(
    base_url="https://xingsuan.cloud/v1",
    api_key="xsk_...",
)

Node.js

import OpenAI from "openai"

const client = new OpenAI({
  baseURL: "https://xingsuan.cloud/v1",
  apiKey: process.env.XSK_KEY,
})

Anthropic SDK

Anthropic SDK 默认通过 x-api-key 头发送 key,并自动附带 anthropic-version。配置 base_url:

Python

from anthropic import Anthropic

client = Anthropic(
    base_url="https://xingsuan.cloud",
    api_key="xsk_...",
)

curl

curl https://xingsuan.cloud/v1/messages \
  -H "x-api-key: $XSK_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-3-5-sonnet-latest",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "你好"}]
  }'

anthropic-version(如 2023-06-01)与 anthropic-beta 等头会被原样透传到上游。

Google Gen AI SDK

Google SDK 默认通过 x-goog-api-key 头发送 key。配置 api_endpoint / 基地址:

Python

from google import genai

client = genai.Client(
    api_key="xsk_...",
    http_options=genai.types.HttpOptions(base_url="https://xingsuan.cloud"),
)

curl

curl "https://xingsuan.cloud/v1beta/models/gemini-2.0-flash:generateContent" \
  -H "x-goog-api-key: $XSK_KEY" \
  -H "content-type: application/json" \
  -d '{ "contents": [{"parts": [{"text": "你好"}]}] }'

模型访问范围

每个 API Key 可配置模型白名单:

• 未配置(null)→ 可调用所有已启用模型;
• 配置为列表 → 只能调用列表内的模型,调用其他模型返回 403 FORBIDDEN。

详见 可用模型。

IP 白名单

创建 Key 时可配置 IP 白名单(仅单个 IPv4/IPv6,暂不支持 CIDR)。配置后:

• 仅白名单内 IP 的请求被接受;
• 其余来源返回 403。

客户端真实 IP 由网关统一解析,不受客户端伪造的 X-Forwarded-For 等头影响。

鉴权失败

无效、过期或已撤销的 Key → HTTP 401 UNAUTHORIZED。各协议下的错误信封形状不同,见 错误码。