Vx API 接入文档

1. 快速开始

Vx API 提供 OpenAI 兼容 API 和 Claude/API 直连风格入口。使用前请先登录后台创建 API Key。

2. API 地址

3. Codex / OpenAI 兼容配置

curl https://la-api.vxvxvx.top/v1/models \
  -H "Authorization: Bearer sk-你的密钥"

CC Switch 配置 Codex 视频

扫码观看配置视频

使用手机扫码在抖音观看 CC Switch 配置 Codex 的完整操作；也可直接点击二维码打开视频。

4. Claude 客户端配置

Claude CLI 命令行接入

先在终端设置下面两个环境变量，再运行 claude。Claude CLI 使用根地址，地址末尾不要添加 /v1。

$env:ANTHROPIC_BASE_URL="https://la-api.vxvxvx.top"
$env:ANTHROPIC_AUTH_TOKEN="sk-你的密钥"

export ANTHROPIC_BASE_URL="https://la-api.vxvxvx.top"
export ANTHROPIC_AUTH_TOKEN="sk-你的密钥"

CC Switch 配置 Claude 视频

扫码观看配置视频

使用手机扫描左侧二维码，观看 CC Switch 配置 Claude 的完整操作。电脑端可点击二维码打开大图后再扫码。

5. 调用示例（文本/对话）

curl 聊天补全

curl https://la-api.vxvxvx.top/v1/chat/completions \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "请替换为你的模型名",
    "messages": [
      {"role": "user", "content": "你好"}
    ],
    "stream": true
  }'

Python 示例

from openai import OpenAI

client = OpenAI(
    api_key="sk-你的密钥",
    base_url="https://la-api.vxvxvx.top/v1",
)

response = client.chat.completions.create(
    model="请替换为你的模型名",
    messages=[{"role": "user", "content": "你好"}],
)

print(response.choices[0].message.content)

Node.js 示例

import OpenAI from "openai";

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

const response = await client.chat.completions.create({
  model: "请替换为你的模型名",
  messages: [{ role: "user", content: "你好" }],
});

console.log(response.choices[0].message.content);

6. GPT Image 2 系列图像生成

本站当前推荐使用 gpt-image-2.5 和 gpt-image-2.5-pro 两个图像模型。两者使用同一套 JSON 接口和参数；建议先用最小请求确认接入，再按需要增加尺寸、宽高比、参考图、流式或异步参数。

接口与鉴权

所有客户请求都要携带：

Authorization: Bearer sk-你的密钥
Content-Type: application/json

两个模型怎么选

完整参数表

最小可用请求（推荐先测试这一段）

curl https://la-api.vxvxvx.top/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的密钥" \
  -d '{
    "model": "gpt-image-2.5",
    "prompt": "一只橘猫坐在阳光照亮的窗台上，写实摄影风格",
    "size": "1K",
    "aspect_ratio": "1:1",
    "quality": "auto",
    "stream": false,
    "async": false
  }'

两个模型的 cURL 示例

GPT Image 2.5（1K 方图）

curl https://la-api.vxvxvx.top/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的密钥" \
  -d '{
    "model": "gpt-image-2.5",
    "prompt": "白色背景上的红苹果，商品摄影，柔和棚拍光线",
    "size": "1K",
    "aspect_ratio": "1:1",
    "quality": "auto",
    "stream": false
  }'

GPT Image 2.5 Pro（2K 横图）

curl https://la-api.vxvxvx.top/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的密钥" \
  -d '{
    "model": "gpt-image-2.5-pro",
    "prompt": "黄昏时的未来城市电影海报，霓虹灯，广角构图，无文字",
    "size": "2K",
    "aspect_ratio": "3:2",
    "quality": "high",
    "stream": false
  }'

参考图 / 图像编辑示例

curl https://la-api.vxvxvx.top/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的密钥" \
  -d '{
    "model": "gpt-image-2.5-pro",
    "prompt": "保留产品外形，把背景改成浅灰色摄影棚，并增加柔和阴影",
    "images": [
      "https://example.com/public/product-front.png",
      "https://example.com/public/style-reference.png"
    ],
    "size": "2K",
    "aspect_ratio": "1:1",
    "quality": "high",
    "stream": false
  }'

本地参考图（-ref 模型）

本地文件与 URL 数组是两种不同的输入方式。使用本地参考图时不要把文件放进 JSON，也不要把请求发到 /v1/images/edits；应使用 multipart/form-data、POST /v1/images/generations，并为每张图片重复使用字段 images。本站游乐场已为图像模型做好该兼容转换。

curl https://la-api.vxvxvx.top/v1/images/generations \
  -H "Authorization: Bearer sk-你的密钥" \
  -F "model=gpt-image-2.5" \
  -F "prompt=保留主体外形，把背景改成浅灰色摄影棚，并增加柔和阴影" \
  -F "size=1K" \
  -F "aspect_ratio=1:1" \
  -F "quality=auto" \
  -F "images=@./reference.png"

# 第二张参考图继续使用同名字段：
# -F "images=@./style-reference.png"

Python 示例（requests）

import requests

url = "https://la-api.vxvxvx.top/v1/images/generations"
headers = {
    "Authorization": "Bearer sk-你的密钥",
    "Content-Type": "application/json",
}
payload = {
    "model": "gpt-image-2.5-pro",
    "prompt": "一只戴着蓝色围巾的柴犬，雪地，写实摄影",
    "size": "2K",
    "aspect_ratio": "3:2",
    "quality": "high",
    "stream": False,
    "async": False,
}

response = requests.post(url, headers=headers, json=payload, timeout=300)
response.raise_for_status()
result = response.json()
print(result)
print(result["data"][0]["url"])

JavaScript / Node.js 示例

const response = await fetch("https://la-api.vxvxvx.top/v1/images/generations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk-你的密钥",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "gpt-image-2.5-pro",
    prompt: "现代建筑室内设计，落地窗，自然光，杂志摄影",
    size: "2K",
    aspect_ratio: "3:2",
    quality: "high",
    stream: false,
    async: false
  })
});

if (!response.ok) {
  throw new Error(`${response.status}: ${await response.text()}`);
}
const result = await response.json();
console.log(result.data[0].url);

同步 JSON 响应

当 stream: false 且 async: false 时，成功后一次性返回 JSON。实际响应可能包含更多字段，客户程序应忽略不认识的附加字段。

{
  "created": 1784825309,
  "progress": 100,
  "status": "succeeded",
  "data": [
    {
      "url": "https://example.com/generated.png",
      "revised_prompt": "模型优化后的提示词（如有）"
    }
  ],
  "error": "",
  "failure_reason": ""
}

SSE 流式返回

需要实时接收时显式传 "stream": true。响应类型为 text/event-stream，客户端要逐行处理 event: / data:，直到收到 data: [DONE]。如果你的 SDK 只会解析普通 JSON，请使用 stream: false。

异步任务、状态查询和 webhook

长时间任务建议使用异步方式，提交后立即获得任务 ID，再轮询状态，避免客户端保持两分钟左右的同步连接。通用 SDK 推荐标准路径 /v1/images/generations 加 "async": true；ComfyUI 自定义节点可使用兼容路径 /v1/images/generations/async。

curl https://la-api.vxvxvx.top/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的密钥" \
  -d '{
    "model": "gpt-image-2.5-pro",
    "prompt": "未来城市的电影海报，黄昏，霓虹灯，无文字",
    "size": "2K",
    "aspect_ratio": "2:3",
    "quality": "high",
    "stream": false,
    "async": true,
    "webhook": "https://your-domain.example/api/image-finished",
    "metadata": {
      "order_id": "A123",
      "client_trace_id": "trace-001"
    }
  }'

提交后保存响应中的 id，标准方式查询：

curl "https://la-api.vxvxvx.top/v1/status/任务ID" \
  -H "Authorization: Bearer sk-你的密钥"

ComfyUI 直接下载照搬

下载 ComfyUI 节点包 下载文生图工作流

1. 把节点 ZIP 解压到 ComfyUI\custom_nodes，解压后应看到 vx_image2 和 vx_image2_configurable 两个文件夹。
2. 完全关闭并重新启动 ComfyUI。
3. 把工作流 JSON 拖进 ComfyUI 页面。
4. 在“图像中转 API 配置”节点填写自己的 Key；Base URL 保持 https://la-api.vxvxvx.top/v1。
5. 选择 gpt-image-2.5 或 gpt-image-2.5-pro，填写提示词后运行。

Codex / Codex++ 使用 vx-image2 Skill

下载 vx-image2 Skill

1. 把 ZIP 解压到 $CODEX_HOME/skills；未设置 CODEX_HOME 时放到 ~/.codex/skills。
2. 重启 Codex 或 Codex++。
3. 确保 Codex 已配置本站 API Key 与 https://la-api.vxvxvx.top/v1。
4. 直接复制下面一句，替换冒号后的图片描述：

使用 vx-image2，通过 gpt-image-2.5 生成一张 1K、1:1 的图片：一只橘猫坐在阳光照亮的窗台上，写实摄影风格

免费检查鉴权和模型列表（不会生成图片）：

python scripts/generate_image2.py --check --model gpt-image-2.5

ComfyUI / 自定义客户端的兼容地址

ComfyUI 自定义节点建议把 Base URL 设置为 https://la-api.vxvxvx.top/v1。不要把完整生成地址当作 Base URL，否则节点再次拼接接口路径时会形成错误地址。

# 1. 异步提交
POST https://la-api.vxvxvx.top/v1/images/generations/async
Authorization: Bearer sk-你的密钥
Content-Type: application/json

{
  "model": "gpt-image-2.5",
  "prompt": "按 Codex 整理后的最终绘图需求",
  "size": "1K",
  "aspect_ratio": "1:1",
  "quality": "auto",
  "stream": false,
  "async": true
}

# 2. 从提交响应保存 id，然后轮询
GET https://la-api.vxvxvx.top/v1/images/tasks/任务ID
Authorization: Bearer sk-你的密钥

建议轮询间隔 2～5 秒；收到 queued 或 running 时继续等待，收到 succeeded 后保存 data[0].url 或 results[0].url。不要因单次任务仍在运行就重复发起新的付费生成。

任务状态统一为：

使用 webhook 时，回调地址必须可公网访问。收到回调后应尽快返回 HTTP 2xx，并按任务 id 做幂等处理；不要只依赖 webhook，也应保留状态查询作为补偿机制。

常见错误与排查

7. 常见问题

401 Unauthorized

通常是 API Key 错误、没有填写 Bearer 前缀、密钥被禁用或余额不足。请重新复制后台密钥。

404 Not Found

通常是 Base URL 填错。OpenAI 兼容客户端一般使用 https://la-api.vxvxvx.top/v1，不要漏掉 /v1。

429、502、524 或请求超时

可能是上游繁忙、模型排队、请求上下文过大、网络链路不稳定或客户端主动断开。大 token 任务建议降低并发、减少上下文、开启流式输出。

client_gone / context canceled / 错误的流状态

多数情况下是客户端、浏览器、代理或网络中途断开连接。长任务建议保持客户端在线，避免频繁切换 VPN 或网络。

首 token 很慢

首 token 主要受模型排队、上游线路、上下文长度、渠道质量和网络链路影响。短问题通常更容易判断线路质量，大 token 任务耗时会明显增加。

需要人工协助

请联系官方微信：vxvxvxtop，并提供使用时间、模型名称、请求 ID、报错截图和使用日志截图。