星火AI API 自助接入文档

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

接入信息：地址与认证

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

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

1. 打开注册页面或登录本站。没有可用额度时，先按页面说明充值或兑换。
2. 进入API 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 包含预期回答，并可在用量查询页面核对本次请求。不要只检查 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 配置指南。

给 AI 编程助手的执行规则

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

常见错误怎么处理

更多排查见 API 错误指南。提交问题时只提供脱敏请求和错误信息，不要附带完整密钥。

接入完成标准

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