接入文档

接入须知

本平台 完全兼容 OpenAI API 格式，只需将客户端的 API 地址替换为本站地址、填入您的 API Key 即可使用。

核心配置参数

参数	值	说明
API 地址 / Base URL	`__API_BASE_URL__`	填写到客户端"API 地址"或"Base URL"字段
API Key	填写您的 sk-... 密钥	购买后获得，在用量查询页可查看
模型名称	按需选择（见定价广场）	如 `claude-sonnet-4-6`、`gpt-4o` 等

部分客户端需要在 API 地址末尾加 /v1，本文档各节均有说明，请按客户端要求填写。

获取 API Key

访问首页，选择合适的套餐并完成购买。
支付成功后，系统自动生成 API Key 并弹窗展示，请立即复制保存。
Key 同时发送至您填写的邮箱，如未收到请检查垃圾邮件文件夹。
也可前往用量查询页面，输入 Key 查看余额与调用记录。

API Key 仅显示一次，请务必妥善保存。如遗失，请联系客服重置或重新购买。

💬ChatBox

ChatBox 是桌面端 AI 客户端，支持 Windows / macOS / Linux，配置简单。

打开 ChatBox → 左下角点击设置。
AI 提供方选择 OpenAI API（或"自定义提供方"）。
填写以下参数：

字段名	填写内容
API 域名 / API Host	`__API_BASE_URL__`
API Key	您的 sk-... 密钥
模型	按需选择，如 `claude-sonnet-4-6`

点击保存，然后新建对话测试。

ChatBox 填写 API 地址时不需要加 /v1，程序会自动补全。

🤖Lobe Chat

Lobe Chat 支持 Web 自部署和官方在线版，均可自定义 API 地址。

进入 Lobe Chat → 左下角设置 → 语言模型。
找到 OpenAI 选项，打开开关。
填写以下参数：

字段名	填写内容
API Key	您的 sk-... 密钥
API 代理地址	`__API_BASE_URL__/v1`
模型列表	手动输入或从定价广场获取模型名

回到对话界面，在顶部模型选择器中选择模型，发送消息测试。

Lobe Chat 的 API 代理地址需要加 /v1。

🌐NextChat（ChatGPT-Next-Web）

NextChat 支持浏览器访问和桌面端，配置方式相同。

打开 NextChat → 右下角设置（齿轮图标）。
找到 接口地址 和 API Key 字段。
填写以下内容：

字段名	填写内容
接口地址	`__API_BASE_URL__`
API Key	您的 sk-... 密钥
自定义模型名	如 `claude-sonnet-4-6`（可选）

关闭设置，新建对话选择模型测试。

🐱OpenCat（iOS / macOS）

OpenCat 是 iOS / macOS 上的 AI 客户端，支持自定义 API 端点。

打开 OpenCat → 底部 Tab 选择设置。
点击 自定义接入点（Custom API Endpoint）。
填写以下参数：

字段名	填写内容
API 端点	`__API_BASE_URL__/v1`
API Key	您的 sk-... 密钥

保存后回到聊天界面，选择模型测试对话。

OpenCat 需在地址末尾加 /v1。

🦞Openclaw

Openclaw 是支持多模型的 AI 客户端，兼容 OpenAI API 格式，可直接接入本站。

打开 Openclaw → 进入设置。
找到 API 设置 或 自定义接入点 选项。
填写以下参数：

字段名	填写内容
API Base URL	`__API_BASE_URL__/v1`
API Key	您的 sk-... 密钥
模型	按需选择，如 `claude-sonnet-4-6`

保存配置，返回对话界面选择模型发送消息测试。

Openclaw 的 API 地址需要加 /v1。

⚡自部署 ChatGPT-Next-Web

如果您自己部署了 ChatGPT-Next-Web，可通过环境变量配置默认接入点：

OPENAI_API_KEY=sk-你的密钥
BASE_URL=__API_BASE_URL__

也可在 Docker 部署时通过 -e 参数传入，或在 Vercel 等平台的环境变量页面填写。

🌏沉浸式翻译

沉浸式翻译浏览器扩展支持配置 OpenAI 兼容接口作为翻译引擎。

打开沉浸式翻译扩展 → 设置 → 翻译服务。
翻译服务选择 OpenAI。
点击 自定义 OpenAI API 展开配置：

字段名	填写内容
API URL	`__API_BASE_URL__/v1/chat/completions`
API Key	您的 sk-... 密钥
模型	`gpt-4o-mini`（翻译推荐，性价比高）
每次请求最大 Token	`1000`（默认即可）

保存后打开任意网页，点击扩展图标测试翻译效果。

沉浸式翻译需要填写完整的 /v1/chat/completions 地址。

🍎Bob（macOS 翻译工具）

Bob 是 macOS 上的划词翻译工具，支持 OpenAI 翻译插件。

确保已安装 Bob 及 OpenAI 翻译插件（在 Bob 插件市场搜索"OpenAI"）。
打开 Bob → 偏好设置 → 服务 → 选中 OpenAI 翻译。
点击右侧配置，填写：

字段名	填写内容
API Key	您的 sk-... 密钥
API URL	`__API_BASE_URL__/v1`
模型	`gpt-4o-mini`（推荐）

保存配置，选中任意文字触发翻译测试。

🔌API 直接调用

本平台接口格式与 OpenAI 完全兼容，直接替换 Base URL 即可。

接口地址

__API_BASE_URL__/v1

cURL 示例

curl __API_BASE_URL__/v1/chat/completions \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [{"role":"user","content":"你好"}]
  }'

🎬视频生成 API

视频生成是异步任务：先创建任务，再用返回的本地任务 ID 查询状态，完成后下载内容。三个接口都必须使用同一个 API Key。

鉴权与端点

Authorization: Bearer sk-你的密钥

方法	路径	用途
`POST`	`/v1/videos`	创建视频任务并预留额度
`GET`	`/v1/videos/{id}`	查询本地任务状态
`GET`	`/v1/videos/{id}/content`	流式下载已完成的视频

当前可用视频模型

模型	计费方式	价格
正在加载...

创建请求字段

字段	类型	必填	说明
`model`	string	是	使用上方当前启用的视频模型名
`prompt`	string	是	视频内容、镜头、动作与风格描述
`duration`	integer	否	视频秒数，默认 8；必须为正整数
`seconds`	integer	否	`duration` 的别名；两者同时出现时必须相等
`gen_type`	string	否	`text-to-video`、`image-to-video`、`first-last-frame` 或 `video-to-video`
`resolution`	string	否	如 `720p`、`1080p`或 `4K`，以当前模型实际支持为准
`aspect_ratio`	string	否	如 `16:9` 或 `9:16`
`negative_prompt`	string	否	不希望出现的内容
`image_urls`	string[]	按模式	`image-to-video` 参考图，最多 9 个 HTTP/HTTPS 地址
`start_image_url`	string	按模式	`first-last-frame` 首帧图片地址
`end_image_url`	string	按模式	`first-last-frame` 尾帧图片地址
`video_urls`	string[]	按模式	`video-to-video` 参考视频，最多 3 个 HTTP/HTTPS 地址
`audio_urls`	string[]	否	最多 3 个 MP3/WAV 地址

模型可接受的时长、分辨率和素材类型由上游模型决定。本站会原样转发通过本地验证的 JSON 字段。

1. 文生视频：POST /v1/videos

curl __API_BASE_URL__/v1/videos \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-video-model",
    "prompt": "A cinematic sunrise over a futuristic city, slow aerial camera movement",
    "duration": 8,
    "gen_type": "text-to-video",
    "resolution": "1080p",
    "aspect_ratio": "16:9"
  }'

2. 图生视频

curl __API_BASE_URL__/v1/videos \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-video-model",
    "prompt": "The character turns toward the camera while the hair moves in the wind",
    "seconds": 5,
    "gen_type": "image-to-video",
    "image_urls": ["https://example.com/reference.png"],
    "aspect_ratio": "16:9"
  }'

3. 首尾帧视频

curl __API_BASE_URL__/v1/videos \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-video-model",
    "prompt": "A smooth transition from day to night",
    "duration": 8,
    "gen_type": "first-last-frame",
    "start_image_url": "https://example.com/start.png",
    "end_image_url": "https://example.com/end.png"
  }'

4. 视频转视频

curl __API_BASE_URL__/v1/videos \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-video-model",
    "prompt": "Restyle the footage as a cinematic anime scene",
    "duration": 8,
    "gen_type": "video-to-video",
    "video_urls": ["https://example.com/source.mp4"],
    "audio_urls": ["https://example.com/music.mp3"]
  }'

创建响应

请保存 id 或 task_id；这是本站任务 ID，后续查询和下载都使用它。未完成时 video_url 为空字符串。

{
  "id": "video_0123456789abcdef",
  "task_id": "video_0123456789abcdef",
  "object": "video",
  "model": "your-video-model",
  "status": "queued",
  "progress": 0,
  "created_at": 1785200000,
  "video_url": ""
}

5. 查询状态：GET /v1/videos/{id}

curl __API_BASE_URL__/v1/videos/video_0123456789abcdef \
  -H "Authorization: Bearer sk-你的密钥"

状态	含义	客户端处理
`queued`	已接收，等待上游处理	继续轮询
`in_progress`	正在生成，`progress` 可能更新	继续轮询
`completed`	生成成功，`video_url` 指向本站下载接口	下载或播放
`failed`	生成失败，预留额度释放	读取 `error` 并结束
`cancelled`	任务已取消，预留额度释放	结束轮询

{
  "id": "video_0123456789abcdef",
  "task_id": "video_0123456789abcdef",
  "object": "video",
  "model": "your-video-model",
  "status": "completed",
  "progress": 1,
  "created_at": 1785200000,
  "video_url": "__API_BASE_URL__/v1/videos/video_0123456789abcdef/content"
}

{
  "id": "video_0123456789abcdef",
  "task_id": "video_0123456789abcdef",
  "status": "failed",
  "progress": 0.42,
  "video_url": "",
  "error": "upstream generation failed"
}

6. 下载内容：GET /v1/videos/{id}/content

curl __API_BASE_URL__/v1/videos/video_0123456789abcdef/content \
  -H "Authorization: Bearer sk-你的密钥" \
  --output video.mp4

curl __API_BASE_URL__/v1/videos/video_0123456789abcdef/content \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Range: bytes=1048576-2097151" \
  --output video.part

下载接口支持 HTTP Range 和断点续传。范围请求通常返回 206 Partial Content，并保留 Content-Range、Accept-Ranges、Content-Length、ETag 和 Last-Modified。

只能查询和下载当前 API Key 拥有的任务。其他 Key、不存在的 ID 以及未完成的内容请求统一返回 404。

计费规则

模式	费用	结算
`video_second`	请求秒数 × 每秒单价	创建时预留，成功后扣除
`video_count`	每条成功视频的固定价格	创建时预留，成功后扣除

创建失败、最终 failed 或 cancelled 都会释放预留额度；状态查询和内容下载不重复计费。

错误处理

HTTP	常见原因	处理建议
`400`	JSON 无效、`model` 缺失、`duration` 与 `seconds` 冲突，或模型未配置视频计费	根据 `error.message` 修正请求
`401`	API Key 缺失、无效或已停用	更换有效 Key
`402`	可用额度不足以预留本次费用	充值或降低时长
`404`	模型/任务不存在、Key 无权访问，或任务未完成就请求内容	检查模型、任务 ID 和原 API Key
`503`	`No active video channels`	稍后重试或联系管理员
上游状态	上游拒绝创建请求	会返回脱敏后的兼容错误结构；不会暴露内部渠道地址和密钥

🖼️图片生成 API

图片模型同时支持 OpenAI 风格图片接口和 Gemini 原生 Banana 协议。建议使用下方动态模型表中的准确名称。

当前可用图片模型

模型	1K	2K	4K	参考图上限
正在加载...

鉴权与端点总览

OpenAI 风格接口使用 Authorization: Bearer sk-...。Gemini 原生接口可使用 URL 查询参数 ?key=sk-...、请求头 x-goog-api-key: sk-... 或 Bearer 请求头。

方法	路径	用途
`POST`	`/v1/images/generations`	OpenAI 风格文生图
`POST`	`/v1/images/edits`	OpenAI 风格图生图/图片编辑
`GET`	`/v1beta/models`	Gemini 兼容模型列表
`POST`	`/v1beta/models/{model}:generateContent`	Gemini 原生非流式生图
`POST`	`/v1beta/models/{model}:streamGenerateContent`	Gemini 原生 SSE 流式响应

OpenAI 文生图请求字段

字段	类型	必填	说明
`model`	string	是	当前启用的图片模型名
`prompt`	string	是	完整提示词
`n`	integer	否	生成张数，默认 1；可用范围取决于模型
`size`	string	否	`auto`、`1k`、`2k`、`4k` 或 `2318x3320` 这类宽高
`aspect_ratio`	string	否	目标比例；显式传入时优先于由 `size` 推断
`output_resolution`	string	否	`1K`、`2K` 或 `4K`，用于指定输出档位
`quality`	string	否	`auto` 或模型支持的质量档
`response_format`	string	否	`url` 或 `b64_json`
`output_format`	string	否	`png`、`jpeg` 或 `webp`
`output_compression`	integer	否	JPEG/WebP 压缩质量；PNG 请求中会被移除

可重试的请求应传入稳定的 Idempotency-Key 请求头，避免网络重试时重复生成。

1. OpenAI 文生图：POST /v1/images/generations

curl __API_BASE_URL__/v1/images/generations \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: image-order-001" \
  -d '{
    "model": "your-image-model",
    "prompt": "A detailed anime city at night, cinematic lighting",
    "n": 1,
    "size": "2752x1536",
    "aspect_ratio": "16:9",
    "output_resolution": "2K",
    "quality": "auto",
    "response_format": "url",
    "output_format": "png"
  }'

OpenAI URL 响应

{
  "created": 1785200000,
  "data": [{
    "url": "https://example.com/generated/image.png",
    "revised_prompt": "A detailed anime city at night, cinematic lighting"
  }],
  "usage": {
    "input_tokens": 24,
    "output_tokens": 16384,
    "total_tokens": 16408
  }
}

将 response_format 设为 b64_json 时，data[0] 中返回 b64_json 而不是 url。这适合客户端无法直接访问图片 URL 的场景。

2. multipart 图片编辑：POST /v1/images/edits

curl __API_BASE_URL__/v1/images/edits \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Idempotency-Key: image-edit-001" \
  -F "model=your-image-model" \
  -F "prompt=Keep the characters and replace the background with a modern studio" \
  -F "image=@reference-1.png" \
  -F "image=@reference-2.jpg" \
  -F "mask=@mask.png" \
  -F "input_fidelity=high" \
  -F "size=2k" \
  -F "aspect_ratio=4:3" \
  -F "response_format=url"

编辑字段与参考图限制

字段	格式	说明
`image`	重复 multipart 文件	1～16 张参考图，实际上限以动态模型表为准
`images`	JSON string[]	可传 HTTP(S) URL 或 `data:image/...;base64,...`；不要传 `{"image_url": ...}` 对象
`mask`	文件或 URL	可选遮罩图
`input_fidelity`	string	如 `high`；不支持的模型会自动移除该字段

单次请求总大小上限为 48 MiB，最多 16 张参考图。图片内容不能为空，声明的 MIME 类型必须与实际文件类型匹配；支持的常见格式为 PNG、JPEG 和 WebP。

3. JSON URL / Data URL 图生图

curl __API_BASE_URL__/v1/images/edits \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-image-model",
    "prompt": "Turn the subject into a watercolor illustration",
    "images": [
      "https://example.com/reference.png",
      "data:image/jpeg;base64,<BASE64>"
    ],
    "size": "auto",
    "aspect_ratio": "auto",
    "output_resolution": "2K",
    "response_format": "url"
  }'

aspect_ratio: "auto" 会让图生图尽量沿用参考图构图；文生图未指定比例时默认为 1:1。传入自定义宽高时，服务会选择最接近的模型官方比例和档位。

Gemini 原生 Banana 协议

原生协议从 contents[].parts[] 收集文本和参考图。只有文本时走文生图；出现 inlineData 或 fileData 图片时自动走图生图。

4. Gemini 模型列表：GET /v1beta/models

curl "__API_BASE_URL__/v1beta/models?key=sk-你的密钥"

Gemini 原生字段

字段	说明
`systemInstruction.parts[].text`	可选系统提示词，会与用户文本合并
`contents[].parts[].text`	必须至少有一个非空文本提示词
`inlineData.mimeType`	必须为 `image/*`
`inlineData.data`	纯 Base64 图片数据，单张最大 50MB；不要包含 Data URL 前缀
`fileData.fileUri`	HTTP(S) 图片 URL 或完整 `data:image/...` URL
`generationConfig.responseModalities`	如传入，必须包含 `IMAGE`
`generationConfig.imageConfig.aspectRatio`	比例或 `auto`
`generationConfig.imageConfig.imageSize`	`1K`、`2K` 或 `4K`；默认 1K

5. Gemini 文生图

curl "__API_BASE_URL__/v1beta/models/your-image-model:generateContent" \
  -H "x-goog-api-key: sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{"text": "A moonlit anime city with cinematic lighting"}]
    }],
    "generationConfig": {
      "responseModalities": ["TEXT", "IMAGE"],
      "imageConfig": {"aspectRatio": "16:9", "imageSize": "4K"}
    }
  }'

6. Gemini inlineData 图生图

curl "__API_BASE_URL__/v1beta/models/your-image-model:generateContent?key=sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [
        {"inlineData": {"mimeType": "image/png", "data": "<BASE64>"}},
        {"text": "Keep the subject and repaint the scene in watercolor"}
      ]
    }],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {"aspectRatio": "auto", "imageSize": "2K"}
    }
  }'

7. Gemini fileData 远程参考图

{
  "contents": [{
    "parts": [
      {
        "fileData": {
          "mimeType": "image/jpeg",
          "fileUri": "https://example.com/reference.jpg"
        }
      },
      {"text": "Transform this photograph into an anime key visual"}
    ]
  }],
  "generationConfig": {
    "imageConfig": {"aspectRatio": "9:16", "imageSize": "2K"}
  }
}

Banana 比例和分辨率

模型类型	支持比例	档位
Banana 标准比例	`1:1`, `16:9`, `4:3`, `3:2`, `5:4`, `9:16`, `3:4`, `2:3`, `4:5`, `21:9`	1K / 2K / 4K
Banana 2 额外超宽/超高比例	`1:8`, `1:4`, `4:1`, `8:1`	1K / 2K / 4K

Gemini 响应与 Token 估算

图片以 candidates[0].content.parts[0].inlineData Base64 返回。usageMetadata 是按提示词长度、参考图数据量和输出像素估算，用于统计对齐，不是 Adobe 官方返回的精确 Token。

{
  "candidates": [{
    "content": {
      "parts": [{
        "inlineData": {"mimeType": "image/png", "data": "<BASE64>"}
      }],
      "role": "model"
    },
    "finishReason": "STOP",
    "index": 0
  }],
  "usageMetadata": {
    "promptTokenCount": 24,
    "candidatesTokenCount": 16384,
    "totalTokenCount": 16408,
    "promptTokensDetails": [{"modality": "TEXT", "tokenCount": 24}],
    "candidatesTokensDetails": [{"modality": "IMAGE", "tokenCount": 16384}]
  },
  "modelVersion": "your-image-model",
  "responseId": "resp_0123456789abcdef"
}

图片错误处理

HTTP	常见错误	原因与处理
`400`	`invalid_image` / `invalid_request_error`	图片为空、MIME 与内容不匹配、JSON 图片项不是字符串、比例或尺寸不支持
`401`	无效或已停用的 API Key	检查 Bearer、`x-goog-api-key` 或 `?key=`
`402`	额度不足	充值或选择价格更低的分辨率
`408`	`upstream_timeout`	解析/下载参考图超时，检查图片 URL 速度或改用 Data URL
`413`	请求体过大	请求超过 48 MiB，需压缩或减少参考图
`429`	并发或上游限流	遵循返回的重试时间，使用有界指数退避
`HTTP 451`	`content_policy_violation`	生成图或参考图触发内容安全限制；修改提示词、随机种子或参考图后重新请求
`503`	暂无可用渠道/账号	稍后重试
`504`	生成或读取上游响应超时	不要立即高频重试，先检查请求是否仍在处理

🐍Python 示例

使用官方 openai SDK，只需修改 base_url：

from openai import OpenAI

client = OpenAI(
    api_key="sk-你的密钥",
    base_url="__API_BASE_URL__/v1",
)

response = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "你好"}],
)
print(response.choices[0].message.content)

安装：pip install openai

🟩Node.js 示例

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-你的密钥',
  baseURL: '__API_BASE_URL__/v1',
});

const response = await client.chat.completions.create({
  model: 'claude-sonnet-4-6',
  messages: [{ role: 'user', content: '你好' }],
});
console.log(response.choices[0].message.content);

安装：npm install openai