客户接入 · AI 可直接读取

# 星火AI API 自助接入文档

创建本站 API Key，配置 OpenAI 兼容地址，查询当前密钥可用模型，再用 cURL、Python、Node.js 或 Claude Code 完成最小验证。

星火AI 智能网关 · 更新于 2026-11-07

本页同时面向客户和 AI 编程助手。你可以把本页的 [Markdown 地址](https://ai.wfpromax.xyz/guides/ai-integration.md)直接发给 AI，让它按文中的真实地址和示例改造服务端项目。**本文不包含真实密钥**；API Key 需要你在本站账户中创建，并只保存在自己的安全配置中。

## 接入信息：地址与认证

| 配置项 | 应填写的值 |
| --- | --- |
| 平台网站 | [https://ai.wfpromax.xyz/](https://ai.wfpromax.xyz/) |
| OpenAI SDK 的 Base URL | `https://ai.wfpromax.xyz/v1` |
| 查询模型 | `GET https://ai.wfpromax.xyz/v1/models` |
| 对话接口 | `POST https://ai.wfpromax.xyz/v1/chat/completions` |
| Responses 接口 | `POST https://ai.wfpromax.xyz/v1/responses` |
| Claude Code 的 Base URL | `https://ai.wfpromax.xyz`（根地址，不加 `/v1`） |
| 图片生成接口 | `POST https://ai.wfpromax.xyz/v1/images/generations` |
| API 认证请求头 | `Authorization: Bearer <本站API_Key>` |

首次接入应用优先使用 Chat Completions。Responses 和 Claude Messages 能否使用取决于密钥分组及模型权限。SDK 已自动拼接接口路径时，只填 Base URL，不要重复写成 `/v1/v1`。认证也支持 `x-api-key: <本站API_Key>`，通用 OpenAI 兼容客户端优先使用 Bearer 方式；不要把密钥放进 URL 查询参数。

## 第一步：创建并复制本站 API Key

1. 打开[注册页面](https://ai.wfpromax.xyz/register)或[登录本站](https://ai.wfpromax.xyz/login)。没有可用额度时，先按页面说明充值或兑换。
2. 进入[API Keys 控制台](https://ai.wfpromax.xyz/keys)，点击“创建密钥”，选择包含目标模型的分组，然后创建并复制密钥。
3. 把密钥放在服务端环境变量或可信的密码管理工具中。这里的密钥是本站签发的 API Key，不是登录密码、网页 Cookie、兑换码，也不是 OpenAI 或 Anthropic 官方密钥。

macOS / Linux 终端示例（请只在自己的终端替换占位符，不要把真实值提交到仓库）：

```
export XINGHUO_API_KEY='替换为本站_API_Key'
export XINGHUO_BASE_URL='https://ai.wfpromax.xyz/v1'
```

Windows PowerShell 使用 `$env:XINGHUO_API_KEY = "替换为本站_API_Key"` 和 `$env:XINGHUO_BASE_URL = "https://ai.wfpromax.xyz/v1"`。长期项目应使用服务端 `.env`、密钥管理服务或部署平台的私密环境变量，并确保密钥文件不会被提交。

如果创建密钥时看到“附加分组”，可以把有权限的标准分组绑定到同一个 Key。每次请求填写一个模型 ID。相同 ID 出现在多个分组时，按主分组和附加分组的顺序匹配可用模型，用量按实际命中的分组计费。订阅分组需单独绑定。

## 第二步：查询这个密钥真正可用的模型

公开目录用于了解服务，实际权限以你的密钥返回结果为准。执行：

```
curl --fail-with-body --max-time 30 \
  "$XINGHUO_BASE_URL/models" \
  -H "Authorization: Bearer $XINGHUO_API_KEY"
```

从响应的 `data` 数组中复制一个准确的 `id`，不要猜测或沿用其他平台的模型名。例如将选中的 ID 设置为：

```
export XINGHUO_MODEL='替换为上一步返回的模型ID'
```

## 第三步：发送第一条最小对话请求

下面使用短输入并限制输出，验证时仍可能产生少量费用：

```
curl --fail-with-body --max-time 60 \
  "$XINGHUO_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $XINGHUO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{
    \"model\": \"$XINGHUO_MODEL\",
    \"messages\": [{\"role\": \"user\", \"content\": \"只回复：接入成功\"}],
    \"max_tokens\": 32,
    \"stream\": false
  }"
```

成功时，HTTP 状态为 200，JSON 的 `choices[0].message.content` 包含预期回答，并可在[用量查询页面](https://ai.wfpromax.xyz/key-usage)核对本次请求。不要只检查 HTTP 200；还要确认回答、模型和用量记录符合预期。

### 验证图片生成

从模型列表选择支持图片生成的 ID，再验证生成一张图片。实际尺寸、可用参数和每张售价以模型所在分组为准。

```
export XINGHUO_IMAGE_MODEL='替换为有权限的图片模型ID'
curl --fail-with-body --max-time 120 \
  "$XINGHUO_BASE_URL/images/generations" \
  -H "Authorization: Bearer $XINGHUO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"model\":\"$XINGHUO_IMAGE_MODEL\",\"prompt\":\"一杯热茶的简洁插画\",\"n\":1}"
```

## 在现有项目中填写密钥和地址

### Python（OpenAI SDK）

项目需要安装 OpenAI Python SDK 时可执行 `python -m pip install openai`。复用前面设置的三个环境变量：

```
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["XINGHUO_API_KEY"],
    base_url=os.environ["XINGHUO_BASE_URL"],
)

response = client.chat.completions.create(
    model=os.environ["XINGHUO_MODEL"],
    messages=[{"role": "user", "content": "只回复：接入成功"}],
    max_tokens=32,
    stream=False,
)
print(response.choices[0].message.content)
```

### Node.js（OpenAI SDK）

项目需要安装 OpenAI Node.js SDK 时可执行 `npm install openai`。以下是 ESM 示例：

```
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.XINGHUO_API_KEY,
  baseURL: process.env.XINGHUO_BASE_URL,
});

const response = await client.chat.completions.create({
  model: process.env.XINGHUO_MODEL,
  messages: [{ role: "user", content: "只回复：接入成功" }],
  max_tokens: 32,
  stream: false,
});
console.log(response.choices[0]?.message.content);
```

已有 OpenAI SDK 的项目通常只需把 `apiKey` 改为本站密钥、把 `baseURL` / `base_url` 改为 `https://ai.wfpromax.xyz/v1`，再使用当前密钥有权访问的模型 ID。其余业务代码可保持不变。

### Claude Code

仅当密钥分组允许 Claude Messages 时使用。Base URL 填根地址，密钥放在 `ANTHROPIC_AUTH_TOKEN`：

```
export ANTHROPIC_BASE_URL='https://ai.wfpromax.xyz'
export ANTHROPIC_AUTH_TOKEN="$XINGHUO_API_KEY"
claude --model "$XINGHUO_MODEL"
```

如需写入个人 `~/.claude/settings.json`，应把这两个值合并进现有 `env`，不要覆盖文件中的其他设置。启动后用 `/status` 核对实际地址和认证来源；完整说明见 [Claude Code 配置指南](https://ai.wfpromax.xyz/guides/claude-code.html)。

## 给 AI 编程助手的执行规则

1. 先检查项目已有的 SDK、依赖和配置风格，只修改接入所需的配置与服务端调用，不因示例盲目更换框架。
2. Base URL 和接口路径严格使用本文值。密钥只从用户提供的私密环境变量读取；没有密钥时，引导用户到 [API Keys 控制台](https://ai.wfpromax.xyz/keys)创建，不要编造密钥，也不要把占位符当作真实密钥请求。
3. 先调用 `GET /v1/models`，再选择返回的准确模型 ID。目标模型不可用时，向用户说明权限问题，不要自行改名绕过限制。
4. 真实密钥不得写进浏览器端 JavaScript、公开仓库、日志、截图或回复内容。纯前端项目应通过客户自己的服务端代理调用。
5. 先用本文的最小请求验证，再接入正式业务。验证后报告 HTTP 状态、实际模型、回答是否完整及用量核对结果；不要无限自动重试或未经确认发起大批量付费请求。

## 常见错误怎么处理

| 状态 | 优先检查 | 处理方式 |
| --- | --- | --- |
| 401 | 密钥缺失、复制错误或已失效 | 核对 Bearer 请求头和密钥来源，不要反复尝试无效密钥。 |
| 403 | 余额、分组、IP 或权限限制 | 读取错误代码，核对账户额度、密钥分组和访问策略。 |
| 404 | 路径或模型 ID 错误 | 检查是否重复拼接 `/v1`，并重新查询可用模型。 |
| 429 | 额度、频率或并发限制 | 读取错误说明并降低并发；存在 `Retry-After` 时按其等待。 |
| 502 / 503 | 临时网络或服务故障 | 限制重试次数；持续失败时记录时间、路径、模型和请求 ID。 |

更多排查见 [API 错误指南](https://ai.wfpromax.xyz/guides/api-errors.html)。提交问题时只提供脱敏请求和错误信息，不要附带完整密钥。

## 接入完成标准

- `GET /v1/models` 能返回当前密钥允许的模型，并且项目使用其中一个准确 ID。
- 最小 Chat Completions 请求返回预期内容，代码没有硬编码或公开真实密钥。
- 本站用量记录与实际请求一致；流式输出、工具调用和长上下文等业务能力已分别验证。

## 准备好密钥，开始接入

先创建本站 API Key，再把本页 Markdown 链接交给你的 AI 编程助手。

 [创建 API Key](https://ai.wfpromax.xyz/keys) [查看模型与价格](https://ai.wfpromax.xyz/available-channels?entry=guide_ai-integration) [打开 AI 可读 Markdown →](https://ai.wfpromax.xyz/guides/ai-integration.md)

## 继续阅读

[OpenAI 兼容 API 接入教程](https://ai.wfpromax.xyz/guides/openai-compatible-api.html)[Claude Code 中转配置](https://ai.wfpromax.xyz/guides/claude-code.html)[AI API 调用验证指南](https://ai.wfpromax.xyz/guides/api-verification.html)[API 错误排查](https://ai.wfpromax.xyz/guides/api-errors.html)[Token 计费说明](https://ai.wfpromax.xyz/guides/token-billing.html)

<!-- public-api-endpoints:start -->

## API 接入地址 / API endpoints

- 默认 / Default — `https://ai.wfpromax.xyz`
- 8xh.pro — `https://8xh.pro`

- OpenAI-compatible Base URL — `https://ai.wfpromax.xyz/v1`
- Claude Code Base URL — `https://ai.wfpromax.xyz`

<!-- public-api-endpoints:end -->