YouApi - API 使用文档

基础配置

域名与端点

统一 YouApi 网关 https://token.youapi.net/

客户端配置时以这个域名为准，再根据客户端要求拼接 /v1 或 /v1beta。

OpenAI 兼容地址 https://token.youapi.net/v1

适用于 Codex CLI、Claude Code、OpenCode、Cursor 或 OpenAI Compatible 类型客户端。

Gemini 兼容地址 https://token.youapi.net/v1beta

Gemini CLI 使用该地址，并通过 GEMINI_API_KEY 传入密钥。

会员与订单页 https://www.youapi.net/

模型价格、订单中心、支持页等站点链接统一使用该域名。

域名替换已完成

文档中原先指向 API 网关的域名已统一替换为 token.youapi.net，原先指向站点页面的域名已统一替换为 www.youapi.net。

第一步

账号注册与登录

01

注册账号

打开注册页，填写邮箱、用户名和密码，按页面提示完成验证。

https://token.youapi.net/register

02

登录主站

登录后从会员中心进入充值、订阅和密钥相关页面，避免直接访问旧支付页导致登录态丢失。

https://token.youapi.net/login

03

进入会员中心

完成登录后再进入充值、订单、订阅兑换和 API 密钥页面，后续操作都会绑定到当前账号。

第二步

余额充值与购买订阅

余额充值

在充值/订阅页面选择余额商品。
确认价格和到账金额，选择支付方式并下单。
支付成功后等待订单自动处理，余额会进入会员账户。
如果订单长时间未更新，请复制订单号联系站点支持。

订阅商品

选择需要的订阅商品并完成支付。
订单处理完成后会生成兑换码。
复制兑换码到主站兑换页提交，订阅权限才会绑定到账户。

站内余额已开启

支付宝已开启

微信支付未开启

USDT(TRC20)已开启

费用与额度

额度、订阅与扣费规则

这一节用来解决“钱充了为什么还不能用”“订阅和余额到底谁生效”这类问题。实际扣费以站点价格页和订单中心为准。

余额

余额用于购买订阅或抵扣按量 API 消耗。充值到账后，先到订单中心确认订单处理状态为成功。

订阅商品通常发放兑换码，兑换后才会绑定到当前账号。只支付不兑换，权限不会自动生效。

密钥额度

密钥可设置独立额度、速率、有效期和 IP 白名单。账号有余额不代表某个密钥一定有调用权限。

订单已支付但余额未变先等待自动处理；超过几分钟仍未成功，复制订单号联系支持。

订阅买了但模型不可用检查是否复制兑换码并在 https://token.youapi.net/redeem 完成兑换。

余额充足但 API 报错检查密钥是否已分组、是否过期、是否被限额或 IP 白名单拦截。

模型列表为空通常是密钥分组没有开放模型，或客户端填错了 Base URL。

第三步

兑换订阅

订阅订单完成
  -> 复制兑换码
  -> 打开 https://token.youapi.net/redeem
  -> 粘贴并提交
  -> 订阅权限绑定到当前账号

余额商品会直接到账，订阅商品通常通过兑换码生效。购买订阅后请到订单详情查看兑换码，不要把兑换码发给他人。

第四步

创建 API 密钥

登录主站后进入 API 密钥页面。
点击创建密钥，填写便于识别的名称。
为密钥分配可用分组，未分组密钥通常无法调用模型。
按需要设置额度、速率、有效期和 IP 白名单。
保存后立即复制密钥，密钥通常只完整显示一次。

密钥安全

不要在群聊、截图、公开代码仓库或前端页面中暴露真实密钥。怀疑泄露时，立即停用旧密钥并创建新密钥。

第五步

连通测试

先用模型列表接口确认网关、密钥和权限都可用。返回模型列表说明基本配置正确。

curl "https://token.youapi.net/v1/models" \
  -H "Authorization: Bearer sk-xxxxxx"

401 / 403

优先检查密钥是否完整、是否过期、是否停用、是否已分组。

404

检查 Base URL。OpenAI 兼容客户端通常填写 /v1，Gemini CLI 使用 /v1beta。

超时

确认本机网络、代理设置和客户端是否把地址拼接成了重复路径。

快速接入

3 分钟跑通第一条请求

01

确认 Base URL

OpenAI 兼容客户端填写 https://token.youapi.net/v1，Gemini CLI 填写 https://token.youapi.net/v1beta。

02

测试模型列表

先调用 /models。这一步能确认网关地址、密钥格式、密钥权限和分组是否正常。

03

发起正式请求

模型列表正常后，再调用 /responses 或客户端内置对话功能。

curl "https://token.youapi.net/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
    "model": "gpt-5.4",
    "input": "只用一句话说明 API 网关的作用",
    "max_output_tokens": 300
  }'

成功标准

能够返回文本内容，说明域名、密钥、模型权限和请求格式都已跑通。之后再配置 Codex、Claude Code、OpenCode 等客户端会更稳。

客户端

首次安装

已安装的用户可以跳过本节。首次配置前建议安装 Node.js LTS，Gemini CLI 建议 Node.js 20 或更高版本。

Codex CLI

npm install -g @openai/codex
codex --version

brew install --cask codex

Claude Code

curl -fsSL https://claude.ai/install.sh | bash
claude --version
claude doctor

Gemini CLI

npx @google/gemini-cli
npm install -g @google/gemini-cli
gemini --version

OpenCode

curl -fsSL https://opencode.ai/install | bash
opencode --version

客户端配置

Codex CLI

Codex 的核心配置文件放在 ~/.codex/config.toml，密钥放在 ~/.codex/auth.json。 Windows 对应目录为 %userprofile%\.codex。

Windows 快速部署插件

适合 Windows 用户一键下载部署，下载后按提示安装并重启编辑器。

下载 Windows 版本

macOS Apple 芯片 Mac ARM64

适用于 M 系列苹果芯片设备，例如 M1、M2、M3、M4 系列。

下载 ARM64 版本

macOS Intel 芯片 Mac x64

适用于 Intel 处理器的老款 Mac。若不确定芯片类型，可在“关于本机”里查看。

下载 x64 版本

macOS 安装提示

使用 macOS 系统安装快速配置插件时，无论您是苹果芯片版本还是因特尔芯片版本，由于安装包没有签名，部分用户会提示“应用已损坏”或“推出磁盘映像”等。安装后请在终端运行：

xattr -cr /Applications/Codex快速配置.app

然后重新打开 Codex 快速配置软件。如未出现上述提示，请直接打开并忽略此操作。

# ~/.codex/config.toml
model_provider = "OpenAI"
model = "gpt-5.4"
review_model = "gpt-5.4"
model_reasoning_effort = "xhigh"
disable_response_storage = true
network_access = "enabled"
windows_wsl_setup_acknowledged = true
model_context_window = 1000000
model_auto_compact_token_limit = 900000

[model_providers.OpenAI]
name = "OpenAI"
base_url = "https://token.youapi.net/v1"
wire_api = "responses"
requires_openai_auth = true

如果主要用于编程项目，可切换到 Codex 模型并缩小自动压缩阈值。

model = "gpt-5.3-codex"
review_model = "gpt-5.3-codex"
model_context_window = 272000
model_auto_compact_token_limit = 244800

{
  "OPENAI_API_KEY": "sk-xxxxxx"
}

Windows 使用提示

建议先安装 VS Code 和 Codex 插件，再写入上述配置。配置完成后重启编辑器或终端，让新配置生效。

客户端配置

Claude Code

Claude Code 可通过环境变量或设置文件连接到兼容网关。

# macOS / Linux
export ANTHROPIC_BASE_URL="https://token.youapi.net/v1"
export ANTHROPIC_AUTH_TOKEN="sk-xxxxxx"

# Windows CMD
set ANTHROPIC_BASE_URL=https://token.youapi.net/v1
set ANTHROPIC_AUTH_TOKEN=sk-xxxxxx

# PowerShell
$env:ANTHROPIC_BASE_URL="https://token.youapi.net/v1"
$env:ANTHROPIC_AUTH_TOKEN="sk-xxxxxx"

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://token.youapi.net/v1",
    "ANTHROPIC_AUTH_TOKEN": "sk-xxxxxx",
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "0"
  }
}

客户端配置

Gemini CLI

Gemini CLI 使用 /v1beta 地址，并通过 GEMINI_API_KEY 传入密钥。

# macOS / Linux
export GOOGLE_GEMINI_BASE_URL="https://token.youapi.net/v1beta"
export GEMINI_API_KEY="sk-xxxxxx"
export GEMINI_MODEL="gemini-2.0-flash"

# Windows CMD
set GOOGLE_GEMINI_BASE_URL=https://token.youapi.net/v1beta
set GEMINI_API_KEY=sk-xxxxxx
set GEMINI_MODEL=gemini-2.0-flash

# PowerShell
$env:GOOGLE_GEMINI_BASE_URL="https://token.youapi.net/v1beta"
$env:GEMINI_API_KEY="sk-xxxxxx"
$env:GEMINI_MODEL="gemini-2.0-flash"

客户端配置

OpenCode

在项目根目录创建 opencode.json，填入兼容网关和密钥。

{
  "provider": {
    "openai": {
      "options": {
        "baseURL": "https://token.youapi.net/v1",
        "apiKey": "sk-xxxxxx"
      }
    }
  },
  "$schema": "https://opencode.ai/config.json"
}

客户端配置

OpenClaw

OpenClaw 可按本地网关模式配置。Windows 配置文件通常在 %userprofile%\.openclaw\openclaw.json，macOS/Linux 通常在 ~/.openclaw/openclaw.json。

{
  "models": {
    "mode": "merge",
    "providers": {
      "openai": {
        "baseUrl": "https://token.youapi.net/v1",
        "apiKey": "sk-xxxxxx",
        "api": "openai-responses"
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "openai/gpt-5.4" }
    }
  },
  "gateway": {
    "mode": "local",
    "port": 18789
  }
}

易错点

baseUrl 末尾不要额外加斜杠，primary 要带 provider 前缀，例如 openai/gpt-5.4。如果提示 Gateway start blocked，检查 gateway.mode 是否为 local。

openclaw status --all
openclaw doctor
openclaw models list
openclaw gateway status
openclaw logs --follow

API 调用

GPT 文本模型调用

推荐优先使用 /v1/responses。该接口适合新版 GPT 模型，输入可以是字符串，也可以是消息数组。

model模型名，例如 gpt-5.4 或 gpt-5.3-codex

input用户输入，支持字符串或消息数组

temperature采样温度，常用范围 0-2

top_p核采样，常用范围 0-1

max_output_tokens限制最大输出 token 数

curl "https://token.youapi.net/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
    "model": "gpt-5.4",
    "input": [
      { "role": "system", "content": "你是一个简洁的中文助手" },
      { "role": "user", "content": "用三句话解释幂等性" }
    ],
    "temperature": 0.7,
    "top_p": 1,
    "max_output_tokens": 1200
  }'

仍使用 Chat Completions 的客户端，可以改用 https://token.youapi.net/v1/chat/completions，核心字段是 messages、temperature、top_p 和 max_tokens。

开发接入

SDK 示例

下面示例适合后端服务、脚本任务或内部工具。真实密钥请放在环境变量里，不要写进前端页面或公开仓库。

Node.js

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.YOUAPI_API_KEY,
  baseURL: "https://token.youapi.net/v1"
});

const response = await client.responses.create({
  model: "gpt-5.4",
  input: "给我一个 API 鉴权失败的排查清单",
  max_output_tokens: 800
});

console.log(response.output_text);

Python

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["YOUAPI_API_KEY"],
    base_url="https://token.youapi.net/v1",
)

response = client.responses.create(
    model="gpt-5.4",
    input="用三条要点说明如何保护 API 密钥",
    max_output_tokens=800,
)

print(response.output_text)

前端不要直连

浏览器前端代码会暴露密钥。需要给网页使用时，建议由自己的后端保存密钥并转发请求。

开发接入

返回结构示例

返回字段会随模型和接口变化，接入时不要只依赖单个固定字段。业务侧至少要处理成功、空输出和错误三种情况。

模型列表

{
  "object": "list",
  "data": [
    {
      "id": "gpt-5.4",
      "object": "model",
      "owned_by": "youapi"
    }
  ]
}

Responses 成功

{
  "id": "resp_xxxxx",
  "object": "response",
  "status": "completed",
  "model": "gpt-5.4",
  "output_text": "API 网关用于统一转发、鉴权和管理模型请求。"
}

图片生成成功

{
  "created": 1760000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgo..."
    }
  ]
}

错误响应

{
  "error": {
    "message": "Invalid API key or unauthorized group",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

开发接入

流式输出

长文本、代码生成和聊天场景建议启用流式输出，让用户更快看到首段内容。客户端需要按事件流逐段读取。

curl "https://token.youapi.net/v1/responses" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
    "model": "gpt-5.4",
    "input": "分步骤解释如何排查 401 错误",
    "stream": true
  }'

没有实时输出确认客户端支持 SSE 或事件流；有些命令行工具会缓冲输出。

中途断开检查本机代理、网关超时、客户端超时设置和模型输出长度。

解析失败不要按普通 JSON 一次性解析，应该按事件行或 SDK 提供的流式迭代器读取。

API 调用

gpt-image-2 图片生成

文生图接口地址为 https://token.youapi.net/v1/images/generations。

model建议使用 gpt-image-2

prompt图片提示词，必填

size1024x1024、1536x1024、1024x1536 或 auto

qualityauto、low、medium、high

backgroundauto、transparent、opaque

output_formatpng、jpeg、webp

n生成数量，建议 1-10

curl "https://token.youapi.net/v1/images/generations" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一个极简风格的蓝白配色支付产品宣传海报，中文标题，留白充足",
    "size": "1024x1024",
    "quality": "high",
    "background": "opaque",
    "output_format": "png",
    "moderation": "auto",
    "n": 1
  }'

API 调用

参考图编辑

图片编辑接口适合“保留主体并调整局部”或“基于已有图片再创作”。请求类型为 multipart/form-data。

上传要求

image 必传，支持 png、jpeg、webp。
mask 可选，建议使用带透明通道的 PNG。
使用蒙版时，蒙版尺寸最好与原图一致。
单文件上传上限按站点当前限制执行，原图和蒙版会分别校验。

参数提醒

prompt 要写清楚保留什么、替换什么、输出风格。
透明背景请使用 png 或 webp，不要使用 jpeg。
output_compression 只对 jpeg 和 webp 生效。

不带蒙版的整图参考编辑

curl "https://token.youapi.net/v1/images/edits" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -F "model=gpt-image-2" \
  -F "prompt=保留人物姿态和构图，改成电商海报风格，背景换成浅色摄影棚，提升清晰度" \
  -F "image=@source.png" \
  -F "size=1024x1024" \
  -F "quality=high" \
  -F "background=auto" \
  -F "output_format=png" \
  -F "moderation=auto"

带蒙版的局部重绘

蒙版中完全透明的区域会优先视为需要修改的区域，不透明区域更倾向于保留。

curl "https://token.youapi.net/v1/images/edits" \
  -H "Authorization: Bearer sk-xxxxxx" \
  -F "model=gpt-image-2" \
  -F "prompt=仅替换透明区域为蓝白科技风 UI 面板，其他区域保持不变" \
  -F "image=@source.png" \
  -F "mask=@mask.png" \
  -F "size=1024x1024" \
  -F "quality=high" \
  -F "background=auto" \
  -F "output_format=png" \
  -F "moderation=auto"

400

提示词为空、参数冲突，例如透明背景搭配 JPEG。

400 / 422

蒙版尺寸不一致，或蒙版没有透明通道。

413

上传文件超出网关或站点限制。

模型策略

模型选择建议

客户端可见模型由密钥分组决定。建议先通过模型列表接口确认可用模型，再在客户端中选择。

默认推荐 gpt-5.4

综合能力强，适合日常对话、分析和通用任务。

编程优先 gpt-5.3-codex

适合项目开发、代码修改和长上下文工程任务。

高频任务 gpt-5.2-codex

响应更轻快，适合频繁的小型代码任务。

轻量备用 gpt-5.3-codex-spark

适合短问答、快速解释和低成本任务。

订单中心

订单状态说明

字段说明常见值

status支付状态pending / paid / expired

recharge_status到账或发码处理状态pending / success / failed

provider支付渠道site_balance / alipay / wechat_pay / trx_usdt

支付成功但仍在处理中

这通常表示支付已经完成，但到账或发码仍在执行。请先等待 1 到 3 分钟，USDT 需要链上确认。超过 5 分钟仍未完成时，携带订单号联系站点支持。

排查

错误码与处理建议

遇到报错时，先看 HTTP 状态码，再看响应体里的 error.message。多数问题都能归到“地址、密钥、权限、额度、参数、网络”这几类。

状态码常见原因处理建议

400请求参数错误、JSON 格式错误、图片参数冲突。检查字段名、请求体格式、图片格式和参数组合。

401密钥缺失、密钥写错、Bearer 前缀不正确。重新复制密钥，确认请求头为 Authorization: Bearer sk-xxxxxx。

403密钥无权限、未分组、过期、IP 白名单不匹配。回到 API 密钥页面检查分组、有效期、额度和白名单。

404Base URL 或接口路径填错。OpenAI 兼容接口用 https://token.youapi.net/v1，Gemini CLI 用 /v1beta。

413上传图片、蒙版或请求体太大。压缩图片，减少批量数量，确认文件大小没有超过站点限制。

429速率限制、并发过高或额度不足。降低并发，稍后重试；检查密钥限速、账号余额和订阅权限。

500 / 502 / 503上游模型或网关临时异常。先重试一次；持续失败时保留请求时间、模型名、订单号或响应错误信息联系支持。

排查顺序

先测试 /v1/models，再测试最小 /v1/responses 请求。模型列表都不通时，优先查地址和密钥；模型列表正常但正式请求失败时，再查模型名、参数和额度。

排查

常见问题

为什么看不到充值或订阅入口？

请先确认已经登录主站账号，并从会员中心进入。如果菜单仍未显示，联系站点支持确认账号权限。

支付页提示未登录怎么办？

回到主站重新登录，再从会员中心进入充值/订阅页面。不要直接打开旧的支付页收藏链接。

充值后看不到余额怎么办？

进入订单中心确认 status 是否为 paid、recharge_status 是否为 success。如果支付成功但处理状态仍是 pending，先等待自动处理；超过几分钟仍未变化，复制订单号联系支持。

订阅支付后兑换码在哪里？

打开订单中心的订阅订单详情。处理完成后会出现兑换码，复制后到 https://token.youapi.net/redeem 提交。

API 返回 401 或 403 怎么排查？

检查 Base URL 是否为 https://token.youapi.net/v1，密钥是否复制完整，密钥是否过期、停用、未分组、未开放目标模型，或被 IP 白名单拦截。

客户端 404 或模型列表为空怎么办？

大概率是 Base URL 填错或密钥分组没有开放模型。OpenAI Compatible、Codex、Claude Code、OpenCode 通常填写 https://token.youapi.net/v1；Gemini CLI 填 https://token.youapi.net/v1beta。

环境变量设置了但客户端没生效怎么办？

重新打开终端或编辑器，让环境变量重新加载。Windows 下要区分 CMD 和 PowerShell 语法；写入配置文件后也建议重启客户端。

图片编辑接口上传失败怎么办？

检查请求是否为 multipart/form-data，image 是否存在，蒙版是否为带透明通道的 PNG，蒙版尺寸是否与原图一致。透明背景不要搭配 JPEG 输出。

OpenClaw 提示 Gateway start blocked 怎么办？

检查 openclaw.json 中 gateway.mode 是否为 local，并确认模型名带有 provider 前缀。

会员、订阅与 API 密钥一站式使用文档

域名与端点

账号注册与登录

注册账号

登录主站

进入会员中心

余额充值与购买订阅

余额充值

订阅商品

额度、订阅与扣费规则

兑换订阅

创建 API 密钥

连通测试

3 分钟跑通第一条请求

确认 Base URL

测试模型列表

发起正式请求

首次安装

Codex CLI

Claude Code

Gemini CLI

OpenCode

Codex CLI

Claude Code

Gemini CLI

OpenCode

OpenClaw

GPT 文本模型调用

SDK 示例

Node.js

Python

返回结构示例

模型列表

Responses 成功

图片生成成功

错误响应

流式输出

gpt-image-2 图片生成

参考图编辑

上传要求

参数提醒

不带蒙版的整图参考编辑

带蒙版的局部重绘

模型选择建议

订单状态说明

错误码与处理建议

常见问题