SubAPI 开发者 API 接入指南

本文档面向需要从代码、SDK、桌面客户端或智能体接入 SubAPI 的开发者。最终公开 API 站点为：

https://api.onemini.top/

SubAPI 是统一 API 网关：请求先通过 API Key 鉴权、分组和平台路由，再转发到对应账号。**平台路由由 API Key 所属分组决定，不要仅凭模型名称猜测最终平台。**模型和能力以当前 Key 的实时列表及返回结果为准。

1. 地址、端口与鉴权

1.1 公网入口

公网只使用 HTTPS：

协议	建议 Base URL	典型路径
Anthropic	`https://api.onemini.top/v1`	`/messages`
OpenAI 兼容	`https://api.onemini.top/v1`	`/chat/completions`、`/responses`、`/images/*`
Gemini 原生	`https://api.onemini.top/v1beta`	`/models/*`

HTTPS 端口为 443，通常省略端口。127.0.0.1:8080、Docker 服务名和其他内网地址只属于服务器内部链路，不应填写到用户客户端。

1.2 API Key 请求头

通用网关接受：

也兼容：

Gemini 原生客户端优先使用 x-goog-api-key。查询参数 key、api_key 已弃用，不能作为公开示例的鉴权方式。

2. 模型列表与分组

2.1 OpenAI 兼容模型列表

2.2 Gemini 原生模型列表

将返回的模型 id 原样放入请求。不同分组可能返回不同模型；如果模型不在列表中，不要自行拼接厂商后缀或渠道名。

3. Claude 模型：Anthropic Messages

SubAPI 的 Claude 原生兼容入口是：

POST https://api.onemini.top/v1/messages

最小非流式请求：

流式请求将 stream 改为 true，并按 Anthropic SSE 事件解析。文本通常位于 content_block_delta 事件的 delta.text。Token 估算接口：

POST https://api.onemini.top/v1/messages/count_tokens

Claude Code 通常填写 Anthropic Base URL 为 https://api.onemini.top/v1（若客户端会自动追加 /v1，则填写 https://api.onemini.top），并使用 API Key 作为 ANTHROPIC_AUTH_TOKEN 或客户端对应的 Anthropic Key 字段。实际拼接规则以客户端版本为准，目标是最终请求 /v1/messages，不能形成 /v1/v1/messages。

4. GPT / OpenAI 模型

4.1 Chat Completions

POST https://api.onemini.top/v1/chat/completions

非流式内容通常读取 choices[0].message.content；流式内容读取 choices[0].delta.content，直到 data: [DONE]。用量通常读取 usage.prompt_tokens、usage.completion_tokens 和 usage.total_tokens。

4.2 Responses

POST https://api.onemini.top/v1/responses

input 可以是字符串，也可以是结构化消息数组。非流式响应读取 output 中的文本；使用 OpenAI SDK 时通常可以读取 response.output_text。流式请求设置 stream=true，按 Responses SSE 事件读取，并在 response.completed 后结束。当前公开文档不要把 background 当作可用的后台任务接口。

Codex CLI 适合使用 Responses；如果客户端只支持 Chat Completions，则使用 /v1/chat/completions。SubAPI 同时保留无 /v1 前缀的兼容别名，但新配置优先使用版本化路径。

5. Gemini 模型与原生接口

5.1 Gemini 原生文本

POST https://api.onemini.top/v1beta/models/{model}:generateContent

模型名位于 URL 路径，请求体内不要重复填写 model。文本通常位于 candidates[].content.parts[].text。

5.2 Gemini 原生流式

POST https://api.onemini.top/v1beta/models/{model}:streamGenerateContent?alt=sse

Gemini 原生鉴权优先用 x-goog-api-key，也兼容 Bearer 和 x-api-key。请求若返回 Google 风格的错误 JSON，应按 code、status 和 message 排查。

6. GPT 图片生成与编辑

6.1 同步图片生成

POST https://api.onemini.top/v1/images/generations

6.2 GPT Image 透明背景（PNG + Alpha）

如果要生成真正带透明通道的图片，不能只在 prompt 里写“transparent background”。请求体要同时传：

{
  "background": "transparent",
  "output_format": "png"
}

background 负责请求透明背景，output_format: "png" 负责保留 PNG 的 Alpha 通道。JPEG 不适合保存透明通道。下面以当前常见的 gpt-image-2 为例；最终可用模型和参数仍以 /v1/models 及实际分组能力为准。

本站最小请求：

{
  "model": "gpt-image-2",
  "prompt": "A single orange cat astronaut mascot sticker, isolated object, clean edges",
  "background": "transparent",
  "output_format": "png",
  "size": "1024x1024",
  "quality": "high",
  "n": 1
}

本站 cURL：

Windows PowerShell：

$body = @{
    model = "gpt-image-2"
    prompt = "A single orange cat astronaut mascot sticker, isolated object, clean edges"
    background = "transparent"
    output_format = "png"
    size = "1024x1024"
    quality = "high"
    n = 1
} | ConvertTo-Json

$response = Invoke-RestMethod `
    -Uri "https://api.onemini.top/v1/images/generations" `
    -Method Post `
    -Headers @{ Authorization = "Bearer $env:API_KEY" } `
    -ContentType "application/json" `
    -Body $body

$imageBytes = [Convert]::FromBase64String($response.data[0].b64_json)
[System.IO.File]::WriteAllBytes("$PWD\transparent.png", $imageBytes)

Python：

prompt 负责描述主体，API 参数负责透明度。建议在提示词里补充 isolated object、clean edges、no colored backdrop、no floor、no scene，但这些文字不能代替 background 参数。

不要只看网页预览判断透明。 下载返回的 PNG 后检查是否存在 Alpha 通道：

正常应看到 RGBA、('R', 'G', 'B', 'A')，且 Alpha 范围的最小值小于 255。如果没有 A 通道，或者 Alpha 始终是 255，说明这张图并不是真透明 PNG。

6.3 图片编辑

POST https://api.onemini.top/v1/images/edits

图片同步请求可能耗时较长。客户端建议至少设置 300 秒读取超时，并保存响应头中的 X-Request-Id 或 X-Oneapi-Request-Id（如果返回）。收到 5xx 或客户端超时时，先核对消费和服务日志，再决定是否重试，避免重复计费。

6.4 异步图片任务

源码提供异步图片任务入口，但该功能需要后台对象存储配置，且当前只对 OpenAI 和 Grok 分组开放：

POST /v1/images/generations/async
POST /v1/images/edits/async
GET  /v1/images/tasks/{task_id}

提交后保存 task_id，轮询返回 processing、completed 或 failed。任务和结果有过期时间，具体以响应字段为准。功能未启用时可能返回 404，不要把异步接口当作所有分组默认可用。

7. Gemini 图片生成

Gemini 图片不是统一的 /v1/images/generations 请求。对于支持图片输出的 Gemini 模型，使用原生 generateContent，并在请求体中请求图片模态：

图片结果通常位于 candidates[].content.parts[].inlineData.data，为 Base64；MIME 类型位于 inlineData.mimeType。是否支持图片输出、可用比例、尺寸和是否能同时返回文本，必须以 /v1beta/models 与实际模型能力为准，不能把 GPT Image 参数套用到 Gemini。

8. OpenCode 与其他智能体

8.1 OpenCode

将 OpenCode 配置为 OpenAI 兼容 Provider：

Base URL: https://api.onemini.top/v1
API Key: <API_KEY>
Model: /v1/models 返回的实际模型 ID
协议: OpenAI Chat Completions；客户端支持时可选 Responses

如果 OpenCode 版本会自动追加 /v1，Base URL 改填 https://api.onemini.top。最终应观察请求是否落到 /v1/chat/completions 或 /v1/responses，不要出现重复 /v1。

8.2 Codex CLI

优先使用 OpenAI Responses，Base URL 为 https://api.onemini.top/v1，API Key 使用站点 Key，模型使用 /v1/models 返回值。若版本只支持 Chat Completions，则切换到 /v1/chat/completions。

8.3 Claude Code

使用 Anthropic 协议，目标路径为 /v1/messages。Base URL 是否填写到 /v1 取决于 Claude Code 版本是否自动拼接版本前缀；以最终请求路径不重复为准。

8.4 Gemini CLI

使用 Gemini 原生协议时，目标 Base URL 为 https://api.onemini.top/v1beta，鉴权优先使用 x-goog-api-key。如果客户端只支持官方固定域名或不支持自定义 Gemini Base URL，则不能直接套用该配置，应改用 OpenAI 兼容入口（前提是当前分组开放该模型）。

8.5 Cline、Continue、Cherry Studio、LobeChat 等

这些客户端通常支持 OpenAI 兼容 Provider：填写 https://api.onemini.top/v1、API Key 和实时模型 ID。是否支持 Responses、图片字段或 Gemini 原生请求，取决于客户端版本；协议不匹配时不要只修改模型名。

9. 当前路由边界

/v1/messages：Anthropic 兼容入口，并可按分组平台自动转到兼容桥。

/v1/chat/completions：OpenAI Chat Completions 入口。

/v1/responses：OpenAI Responses 入口，并支持受限的可转发子路径。

/v1beta/models/*：Gemini 原生模型列表、详情、generateContent 和流式接口。

/v1/images/generations、/v1/images/edits：图片接口，当前按平台能力限制，非所有分组都开放。

视频相关路径不属于本指南的文本与图片接入范围；请以当前站点实际发布的接口文档为准。

10. 错误排查

状态码/现象	优先检查
`401`	API Key 是否放在 `Authorization`、`x-api-key` 或 `x-goog-api-key`；Key 是否有效
`403`	用户、分组、订阅或 IP 限制
`404`	Base URL 是否重复拼接 `/v1`；Gemini 是否误用 `/v1`；功能是否被平台限制或未启用
`400`	模型 ID、协议格式、必填字段和请求体结构
`429`	Key 额度、订阅额度、并发或请求频率
`503` / 模型不存在	重新请求对应模型列表，确认 Key 所属分组和实际模型 ID
图片请求超时	记录请求时间、模型、参数和 Request ID，先核对消费记录和服务日志，不要立即重复提交

11. 最小接入流程

创建 API Key
  -> 选择 https://api.onemini.top
  -> GET /v1/models 或 GET /v1beta/models
  -> 使用返回的实际模型 ID
  -> 按模型协议调用 /v1/messages、/v1/chat/completions、/v1/responses 或 /v1beta/models/*
  -> 图片请求按 OpenAI 图片或 Gemini 原生接口分别处理

计费、倍率和可用模型以站点当前分组配置为准；本文只说明 SubAPI 请求协议和路由边界。

开发者 API 接入指南

SubAPI 开发者 API 接入指南#

1. 地址、端口与鉴权#

1.1 公网入口#

1.2 API Key 请求头#

2. 模型列表与分组#

2.1 OpenAI 兼容模型列表#

2.2 Gemini 原生模型列表#

3. Claude 模型：Anthropic Messages#

4. GPT / OpenAI 模型#

4.1 Chat Completions#

4.2 Responses#

5. Gemini 模型与原生接口#

5.1 Gemini 原生文本#

5.2 Gemini 原生流式#

6. GPT 图片生成与编辑#

6.1 同步图片生成#

6.2 GPT Image 透明背景（PNG + Alpha）#

6.3 图片编辑#

6.4 异步图片任务#

7. Gemini 图片生成#

8. OpenCode 与其他智能体#

8.1 OpenCode#

8.2 Codex CLI#

8.3 Claude Code#

8.4 Gemini CLI#

8.5 Cline、Continue、Cherry Studio、LobeChat 等#

9. 当前路由边界#

10. 错误排查#

11. 最小接入流程#