小胖丸API
EN

小胖丸API

接入文档

将常用开发工具连接到小胖丸API 端点。

01

接入前准备

1 分钟开始：登录控制台、创建 API Key、复制并保存，然后发出第一条请求。

  • 打开控制台并登录：控制台地址是 https://sub.xiaopangwan.site；它和 API Base URL 不是同一个地址。
  • 还没有账号？先在同一控制台完成注册，再回到 API Keys 页面。
  • 进入 API Keys 页面创建 API Key。创建完成后立即复制；Key 通常只完整显示一次，请保存到密码管理器或服务端环境变量。本文档不会展示真实 Key。
  • 为不同设备或客户端分别创建 Key。需要轮换时，在 API Keys 页面撤销旧 Key 并更新客户端环境变量。
  • 从模型与价格页面或 GET /v1/models 确认当前账户可见模型；示例中的 MODEL_ID 必须替换。
  • Key 只保存在密码管理器、系统密钥存储或本地环境变量中，不要粘贴到浏览器前端、截图、仓库或聊天记录。
打开控制台 / 登录注册账号打开 Key 管理页打开中文文档入口查看模型与价格跳到安全建议
02

快速开始

OpenAI 兼容接入统一使用 https://api.xiaopangwan.site/v1；控制台地址是 https://sub.xiaopangwan.site，两者用途不同。

原始 curl 请求使用完整 URL。OpenAI SDK 的 baseURL/base_url 固定写到 /v1，调用 SDK 方法时不要再次添加 /v1。

统一请求头：OpenAI 使用 Authorization: Bearer your_api_key 和 Content-Type: application/json；Claude 兼容 HTTP 使用 x-api-key、anthropic-version: 2023-06-01 和 Content-Type: application/json；Gemini HTTP 使用 x-goog-api-key 和 Content-Type: application/json。

Claude 兼容 HTTP 的请求路径固定是 /v1/messages；不要把 /v1/messages 写进 OpenAI 的 Base URL。

先请求 GET /v1/models 并确认收到 JSON 模型列表，再把返回的模型 ID 放入最小请求。OpenAI Chat Completions 返回 choices；Responses 返回 output；Claude Messages 返回 content；流式请求返回 SSE 事件。最小成功响应至少应包含对应协议的结果字段，不要只用 HTTP 200 判断业务成功。

OpenAI SDK
https://api.xiaopangwan.site/v1chat/completionshttps://api.xiaopangwan.site/v1/chat/completions
Anthropic client
https://api.xiaopangwan.site/v1/messageshttps://api.xiaopangwan.site/v1/messages
Gemini client
https://api.xiaopangwan.site/v1beta/models/MODEL_ID:generateContenthttps://api.xiaopangwan.site/v1beta/models/MODEL_ID:generateContent
最小 curl 请求bash
curl "https://api.xiaopangwan.site/v1/chat/completions" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "messages": [{"role": "user", "content": "Hello"}]
  }'
03

首次使用

按“登录 → 创建 Key → 查模型 → 最小请求”完成第一次验证。

打开控制台 https://sub.xiaopangwan.site 登录并创建 API Key；复制后妥善保存。示例只使用 your_api_key 占位值，不要把真实 Key 写入示例、仓库或聊天记录。

先请求 GET /v1/models，以当前 Key 返回的模型 ID 替换 MODEL_ID，再按所选协议发送最小请求。

收到 2xx 且响应体符合所选协议的结构，即可确认首个请求已接通。本文档验证不使用真实 API Key 发起可能计费的推理请求。

若首次请求失败，依次核对协议与端点、错误排查和安全建议。

登录用户中心核对协议与端点查看错误排查查看安全建议
04

协议与端点

下列接口和协议均已提供；具体调用结果取决于模型、渠道、上游能力及账户权限。

协议与端点明细
方法完整请求 URL认证主要参数返回
POSTOpenAI Chat Completions已提供https://api.xiaopangwan.site/v1/chat/completions/v1/chat/completions请求根地址: https://api.xiaopangwan.siteAuthorization: Bearer your_api_keymodel、messages；流式请求增加 stream: trueOpenAI 兼容 choices JSON；流式为 SSE 数据帧上下文、工具和多模态结果取决于所选模型与渠道。
POSTOpenAI Responses已提供https://api.xiaopangwan.site/v1/responses/v1/responses请求根地址: https://api.xiaopangwan.siteAuthorization: Bearer your_api_keymodel、input；按需增加 streamResponses 兼容对象或事件流Codex 自定义提供商使用此端点，Base URL 只写到 /v1。
GETOpenAI Models已提供https://api.xiaopangwan.site/v1/models/v1/models请求根地址: https://api.xiaopangwan.siteAuthorization: Bearer your_api_key无请求体当前账户可见模型列表用返回的模型 ID 替换 MODEL_ID。
POSTAnthropic Messages已提供https://api.xiaopangwan.site/v1/messages/v1/messages请求根地址: https://api.xiaopangwan.sitex-api-key 与 anthropic-versionmodel、max_tokens、messages；按需增加 streamAnthropic Messages 兼容内容块或事件流消息结构与模型协议必须匹配。
POSTAnthropic count_tokens已提供https://api.xiaopangwan.site/v1/messages/count_tokens/v1/messages/count_tokens请求根地址: https://api.xiaopangwan.sitex-api-key 与 anthropic-versionmodel、messages，可带系统或工具字段输入 token 统计对象路径必须包含 /v1。
GETGemini Models已提供https://api.xiaopangwan.site/v1beta/models/v1beta/models请求根地址: https://api.xiaopangwan.sitex-goog-api-key: your_api_key无请求体Gemini 协议模型列表Gemini 客户端使用根 Base URL。
POSTGemini generateContent已提供https://api.xiaopangwan.site/v1beta/models/MODEL_ID:generateContent/v1beta/models/MODEL_ID:generateContent请求根地址: https://api.xiaopangwan.sitex-goog-api-key: your_api_keycontents；按模型增加 generationConfig 等字段Gemini generateContent 兼容对象MODEL_ID 来自当前账户可见的 Gemini 协议模型。
POSTGemini streamGenerateContent已提供https://api.xiaopangwan.site/v1beta/models/MODEL_ID:streamGenerateContent?alt=sse/v1beta/models/MODEL_ID:streamGenerateContent?alt=sse请求根地址: https://api.xiaopangwan.sitex-goog-api-key: your_api_keycontents 与 alt=sse 查询参数SSE 事件流逐事件消费并处理结束或错误事件。
POSTImage generations已提供https://api.xiaopangwan.site/v1/images/generations/v1/images/generations请求根地址: https://api.xiaopangwan.siteAuthorization: Bearer your_api_key仅记录已验证字段：model=gpt-image-2、prompt、n、size、qualityOpenAI 图片响应结构输出规格取决于模型、渠道和账户权限。
POSTImage edits已提供https://api.xiaopangwan.site/v1/images/edits/v1/images/edits请求根地址: https://api.xiaopangwan.siteAuthorization: Bearer your_api_keymultipart：model=gpt-image-2、image、prompt、n、size、qualityOpenAI 图片编辑响应结构输入文件和其他字段以当前接口验证结果为准；本文不推断未验证值域。
05

客户端配置

每个客户端的 Base URL 规则不同。先复制占位配置，再在本机环境变量中替换 Key 与 MODEL_ID。

Codex

已提供
请求根地址
https://api.xiaopangwan.site/v1
配置字段
model_provider · base_url · env_key · wire_api = "responses"
推荐测试
设置环境变量后用短提示启动 Codex；首次调用会发出真实请求。
常见错误
不要在 base_url 后加 /responses，也不要把 Key 写进可提交的配置文件。
Codexconfig
# Set XIAOPANGWAN_API_KEY=your_api_key in your environment first.
model = "MODEL_ID"
model_provider = "xiaopangwan"

[model_providers.xiaopangwan]
name = "小胖丸API"
base_url = "https://api.xiaopangwan.site/v1"
env_key = "XIAOPANGWAN_API_KEY"
wire_api = "responses"

Node.js（OpenAI SDK）

已提供
请求根地址
https://api.xiaopangwan.site/v1
配置字段
baseURL · apiKey · model
推荐测试
先调用 client.models.list()，再使用返回的模型 ID 发起最小请求。
常见错误
baseURL 已包含 /v1，不要再拼接第二个 /v1。
Node.js（OpenAI SDK）config
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.xiaopangwan.site/v1',
  apiKey: process.env.XIAOPANGWAN_API_KEY
});

const result = await client.chat.completions.create({
  model: process.env.MODEL_ID ?? 'MODEL_ID',
  messages: [{role: 'user', content: 'Hello'}],
});

console.log(result.choices[0]?.message);

OpenAI Python SDK

已提供
请求根地址
https://api.xiaopangwan.site/v1
配置字段
base_url · api_key · model
推荐测试
先运行 client.models.list()，再测试一条短消息。
常见错误
环境变量名称可以自定，但代码读取的名称必须与系统设置一致。
OpenAI Python SDKconfig
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.xiaopangwan.site/v1",
    api_key=os.environ["XIAOPANGWAN_API_KEY"],
)

result = client.chat.completions.create(
    model=os.environ.get("MODEL_ID", "MODEL_ID"),
    messages=[{"role": "user", "content": "Hello"}],
)

print(result.choices[0].message)

curl

已提供
请求根地址
https://api.xiaopangwan.site/v1
配置字段
Authorization: Bearer · Content-Type · model
推荐测试
先请求 GET /v1/models，再把返回的模型 ID 放进最小请求。
常见错误
原始 HTTP 请求使用完整端点，不要遗漏 Bearer 后的空格。
curlconfig
curl "https://api.xiaopangwan.site/v1/chat/completions" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "messages": [{"role": "user", "content": "Hello"}]
  }'
06

代码示例

示例覆盖普通请求、Responses、Anthropic Messages、Gemini 与两种 OpenAI SDK。所有 Key 与模型均为占位值。

curl · Chat Completionsbash
curl "https://api.xiaopangwan.site/v1/chat/completions" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "messages": [{"role": "user", "content": "Hello"}]
  }'
curl · Responsesbash
curl "https://api.xiaopangwan.site/v1/responses" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "input": "Hello"
  }'
curl · 模型列表bash
curl "https://api.xiaopangwan.site/v1/models" \
  -H "Authorization: Bearer your_api_key"
Node.js · Chat Completionsjs
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.xiaopangwan.site/v1',
  apiKey: process.env.XIAOPANGWAN_API_KEY
});

const result = await client.chat.completions.create({
  model: process.env.MODEL_ID ?? 'MODEL_ID',
  messages: [{role: 'user', content: 'Hello'}],
});

console.log(result.choices[0]?.message);
Node.js · Responsesjs
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.xiaopangwan.site/v1',
  apiKey: process.env.XIAOPANGWAN_API_KEY
});

const result = await client.responses.create({
  model: process.env.MODEL_ID ?? 'MODEL_ID',
  input: 'Hello',
});

console.log(result.output_text);
Python · Chat Completionspython
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.xiaopangwan.site/v1",
    api_key=os.environ["XIAOPANGWAN_API_KEY"],
)

result = client.chat.completions.create(
    model=os.environ.get("MODEL_ID", "MODEL_ID"),
    messages=[{"role": "user", "content": "Hello"}],
)

print(result.choices[0].message)
curl · Anthropic Messagesbash
curl "https://api.xiaopangwan.site/v1/messages" \
  -H "x-api-key: your_api_key" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "max_tokens": 256,
    "messages": [{"role": "user", "content": "Hello"}]
  }'
curl · Anthropic count_tokensbash
curl "https://api.xiaopangwan.site/v1/messages/count_tokens" \
  -H "x-api-key: your_api_key" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "messages": [{"role": "user", "content": "Hello"}]
  }'
curl · Gemini generateContentbash
curl "https://api.xiaopangwan.site/v1beta/models/MODEL_ID:generateContent" \
  -H "x-goog-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [{"text": "Hello"}]}]
  }'
07

模型与价格

模型、价格与账户可见范围会随渠道和账户状态变化，因此文档不复制静态模型表、价格或倍率。

登录后以用户中心显示为准，也可以调用 GET /v1/models 获取当前 Key 可见的模型 ID。

公共模型与价格页面用于了解当前展示规则；实际可选模型、计费和余额变化以用户中心及请求结果为准。

同一模型名称可能通过不同协议或渠道提供。客户端协议、请求结构和 MODEL_ID 必须彼此匹配。

当前已上线的生图模型仅写 gpt-image-2。openai-生图专用组按图片次数/档位计费：1K $0.50、2K $1.00、4K $1.50。不要把 gpt-image-2 挂到普通 plus/pro 组。

登录后查看账户模型打开模型与价格页面查看模型列表端点
08

流式、图片与高级请求

流式和图片端点已提供；请求字段、输出规格与生成结果由所选模型、渠道、上游能力和账户权限决定。

生图统一使用 Base URL https://api.xiaopangwan.site/v1；图片生成完整 URL 是 https://api.xiaopangwan.site/v1/images/generations，图片编辑完整 URL 是 https://api.xiaopangwan.site/v1/images/edits。当前已上线模型仅为 gpt-image-2。

已验证参数仅写 prompt、n、size、quality：size 可用 1024x1024、1536x1024、1024x1536；quality 可用 auto、low、high。不要猜测 background/output_format 等未验证值域。

  • OpenAI Chat Completions 与 Responses 使用 stream: true；客户端按 SSE 事件逐块读取，并处理连接中断和最终事件。
  • Gemini 使用 streamGenerateContent 并添加 alt=sse；Anthropic Messages 在请求体中增加 stream。
  • 图片生成使用 JSON；图片编辑使用 multipart/form-data。本文只列已验证的 prompt、n、size、quality，不对 background/output_format 等字段给出值域推断。
  • 为流式请求设置连接与空闲超时；为图片上传设置合理的请求体限制，不要在网络重试中无条件重复可能计费的生成。
打开生图工作台管理 API Key
OpenAI 流式请求bash
curl "https://api.xiaopangwan.site/v1/chat/completions" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -N \
  -d '{
    "model": "MODEL_ID",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": true
  }'
Gemini 流式请求bash
curl "https://api.xiaopangwan.site/v1beta/models/MODEL_ID:streamGenerateContent?alt=sse" \
  -H "x-goog-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -N \
  -d '{
    "contents": [{"parts": [{"text": "Hello"}]}]
  }'
图片生成bash
curl "https://api.xiaopangwan.site/v1/images/generations" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A calm green landscape",
    "n": 1,
    "size": "1024x1024",
    "quality": "auto"
  }'
图片编辑bash
curl "https://api.xiaopangwan.site/v1/images/edits" \
  -H "Authorization: Bearer your_api_key" \
  -F "model=gpt-image-2" \
  -F "prompt=Refine the lighting" \
  -F "image=@input.png" \
  -F "n=1" \
  -F "size=1024x1024" \
  -F "quality=auto"
09

错误排查

先记录 HTTP 状态、请求协议和最终 URL，再检查 Key、模型、账户状态和请求结构。

401

认证失败

检查 Key 是否遗漏、复制不完整，Bearer 后是否有空格，以及协议是否使用对应认证头。

403

权限或账户状态

登录用户中心检查账户状态、Key 权限和所选渠道所需权限。

404

路径或版本前缀

检查 Base URL、/v1 或 /v1beta、端点拼接，以及客户端是否自动追加第二个 /v1。

429

频率、余额或配额

查看账户余额和配额，降低并发，并按 Retry-After 或有上限的指数退避安排重试。

BALANCE

余额不足

登录控制台确认余额与扣费记录；余额不足时先充值或改用有余额的账户，再重试一次。

CHANNEL

渠道当前不可用

确认模型仍在 GET /v1/models 返回列表中；若模型存在但渠道暂时不可用，稍后重试或联系服务支持。

TIMEOUT

请求超时

检查网络、连接与读取超时设置；流式请求要设置空闲超时，不要在不确定上一次是否受理时重复提交。

5xx

服务或上游异常

保存脱敏后的请求时间与状态，不记录 Key；稍后重试，持续发生时联系服务支持。

MODEL

模型不存在

重新调用 GET /v1/models，以当前 Key 返回的模型 ID 替换 MODEL_ID。

PROTOCOL

协议与模型不匹配

确认模型面向 OpenAI、Anthropic 或 Gemini 请求结构，并使用相应端点。

STREAM

流式响应异常

确认客户端接受 SSE、没有缓冲完整响应，并正确处理 data、终止与中断事件。

IMAGE

图片参数错误

核对 Content-Type、multipart 字段、文件格式与体积，以及模型和渠道接受的参数。

10

常见问题

先检查最终 URL 和请求协议，再核对模型、认证头、权限与状态码。

  • 为什么出现 /v1/v1 或 404？OpenAI SDK 的 Base URL 只写到 /v1；确认客户端不会再追加第二个 /v1，并检查 /v1 或 /v1beta 与端点拼接。
  • MODEL_ID 从哪里来？调用 GET /v1/models，并用当前 Key 返回的模型 ID 替换 MODEL_ID；模型、渠道和账户权限会影响可见范围。文档不固定模型或价格，实际信息以用户中心和当前请求结果为准。
  • 认证头为什么不同？OpenAI 使用 Authorization: Bearer your_api_key；Anthropic 使用 x-api-key 与 anthropic-version；Gemini 使用 x-goog-api-key。
  • 流式或图片请求为什么失败？确认请求结构与模型、渠道和权限匹配；流式客户端需接受 SSE，图片请求的字段和格式以模型与渠道接受的参数为准。
  • 401、404、429 或 5xx 如何处理？分别检查认证、最终 URL、频率/余额/配额，或保存脱敏时间与状态后稍后重试；持续的 5xx 可联系服务支持。
  • Key 泄露后怎么办？立即登录用户中心撤销旧 Key，创建新 Key，并更新所有客户端和自动化任务。
11

安全与使用建议

把 API Key 当作密码处理，并让重试、并发和日志策略可控。

  • 使用环境变量、系统密钥存储或部署平台 Secret；不要把 Key 写进浏览器前端、仓库、截图或聊天记录。
  • Key 泄露后立即登录用户中心撤销旧 Key，创建新 Key，并更新所有客户端和自动化任务。
  • 日志只保留脱敏后的请求 ID、时间、模型、状态码和耗时；不要记录认证头的值。
  • 设置连接与读取超时，对 429 和可恢复 5xx 使用有上限的指数退避；对认证与参数错误不要自动重试。
  • 生成、编辑或其他可能计费的请求在重试前先确认前一次是否已被受理，避免重复提交产生额外费用。
登录用户中心管理 Key返回快速开始