认证与 API Key

平台使用 API Key（令牌） 做身份认证，所有接口请求都必须携带有效的 API Key。

API Key 是什么

API Key 是在控制台「令牌 / API Key」页面创建的访问凭证，形如：

sk-3f9a1b2c...（一长串随机字符）

• 每个账号可创建多个 Key，建议按应用 / 环境分别创建。
• 不同 Key 可分别设置额度上限、可用模型白名单、IP 白名单、过期时间，实现精细化管控。
• Key 可随时在控制台删除或禁用，删除后立即失效。

认证方式

OpenAI 格式（推荐）

请求头携带：

Authorization: Bearer sk-你的密钥

适用于 /v1/chat/completions、/v1/embeddings、/v1/images/*、/v1/audio/*、/v1/rerank、/v1/moderations、/v1/videos 等绝大多数端点。

其他生态的认证头

为兼容各家官方 SDK，以下请求头也会被识别为同一个 API Key：

客户端生态	请求头 / 参数	适用端点
Anthropic / Claude 系	x-api-key: sk-你的密钥（同时携带 anthropic-version 请求头）	POST /v1/messages
Google / Gemini 系	x-goog-api-key: sk-你的密钥，或查询参数 ?key=sk-你的密钥	/v1beta/models/* 及模型列表端点
Midjourney 系	mj-api-secret: sk-你的密钥	/mj/* 端点

以上方式均对应控制台里创建的同一个 API Key；同一请求只需提供其中一种。除上述端点外，其他路径请统一使用 Authorization: Bearer 头。

在常用 SDK 中配置

OpenAI 官方 SDK（Python / Node.js）

from openai import OpenAI

client = OpenAI(
    api_key="sk-你的密钥",
    base_url="https://confluia.com/v1",  # 替换为你的 API 地址
)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: "sk-你的密钥",
  baseURL: "https://confluia.com/v1",
});

Anthropic 官方 SDK

import anthropic

client = anthropic.Anthropic(
    api_key="sk-你的密钥",
    base_url="https://confluia.com",  # Claude 格式使用根地址，不要带 /v1
)

通用 HTTP（requests）

import requests

resp = requests.post(
    "https://confluia.com/v1/chat/completions",
    headers={"Authorization": "Bearer sk-你的密钥"},
    json={
        "model": "gpt-4o",
        "messages": [{"role": "user", "content": "你好"}],
    },
)
print(resp.json())

其他 OpenAI 兼容客户端

凡支持自定义 base_url / baseURL 的 OpenAI 兼容客户端（LangChain、各类 Chat 客户端、代码插件等），将 base_url 指向 https://confluia.com/v1、Key 填你的 sk- 密钥即可，详见接入指南。

认证失败的返回

认证与权限类错误的响应均为 OpenAI 风格错误结构，但状态码与 code 字段随场景不同，请以 HTTP 状态码与 message 为准：

场景	HTTP 状态码	说明
未携带 Key / Key 无效 / 已删除 / 已禁用 / 已过期 / 令牌额度耗尽	401	error.code 可能为空，按 message 判断
IP 不在令牌白名单	403	error.code 为 access_denied
账号被禁用 / 无权访问指定分组	403	按 message 判断
账号余额不足	403	error.code 为 insufficient_user_quota，充值后自动恢复

错误结构示例：

{
  "error": {
    "message": "对该令牌提供的密钥无效 (request id: 20250101-xxxx)",
    "type": "new_api_error",
    "code": ""
  }
}

异步任务接口例外

视频生成等异步任务接口（/v1/videos、/v2/video_generation 等）的错误结构与上文不同，具体见错误码与限流与视频生成。

安全最佳实践

1. Key 只放在服务端：前端 / 客户端代码中永远不要硬编码 Key，应通过自己的后端服务转发请求。
2. 泄露即处置：发现泄露立即在控制台删除该 Key 并新建。
3. 最小授权：为高风险 Key 设置额度上限、模型白名单与 IP 白名单，缩小损失面。
4. 定期轮换：对长期使用的 Key 定期更换。