API 使用文档

客户只需要一个平台 API Key。文本、图片和视频都走同一个中转站 Base URL。

接入参数

所有 OpenAI 兼容客户端都使用 /v1 结尾的 Base URL。

https://your-domain.example/v1

认证方式

Authorization: Bearer sk-...

公开模型

文本 0 个 / 图片 0 个 / 视频 0 个

模型规则

只调用模型广场里已开放的模型

快速开始

注册并登录前台

充值或让管理员加点

在 API Key 页面创建令牌

复制 Base URL 和 sk- Key 到客户端

接口路径

Etsy 工具和其他客户端都应该按下面的能力选择接口。

能力	方法	路径	使用场景	模型范围
Chat Completions	POST	/v1/chat/completions	普通文本、视觉理解、多轮对话、兼容 OpenAI Chat 的客户端	TEXT，协议包含 openai-chat 的模型
Responses	POST	/v1/responses	Responses 协议模型、部分新模型或需要 input 数组格式的客户端	TEXT，协议包含 openai-responses 的模型
Image Generation	POST	/v1/images/generations	纯文生图，没有参考图时使用	IMAGE，支持图片生成的模型
Image Edits	POST	/v1/images/edits	上传一张或多张参考图后改图、融合背景、商品场景图	IMAGE，支持图片编辑的模型
Videos	POST	/v1/videos	创建视频任务，成功后继续轮询任务状态	VIDEO，已测试通过并开放的视频模型
Video Detail	GET	/v1/videos/{id}	查询视频任务状态，直到 succeeded/completed	创建视频任务返回的任务 ID
Video Content	GET	/v1/videos/{id}/content	视频成功后下载结果内容	创建视频任务返回的任务 ID

文本调用

普通 OpenAI SDK、Chat 客户端和大多数 Agent 工具使用这个接口。

curl /chat/completions

curl https://your-domain.example/v1/chat/completions \
  -H "Authorization: Bearer sk-your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      { "role": "user", "content": "用一句话介绍这个 API" }
    ]
  }'

文生图

没有参考图时使用 JSON 请求。

curl /images/generations

curl https://your-domain.example/v1/images/generations \
  -H "Authorization: Bearer sk-your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-1-mini",
    "prompt": "A clean product photo of a cream cardigan on a hanger",
    "size": "1024x1024",
    "n": 1
  }'

图片编辑 / 多图融合

有参考图时使用 multipart/form-data，多张图重复传 image 字段。

curl /images/edits

curl https://your-domain.example/v1/images/edits \
  -H "Authorization: Bearer sk-your-token" \
  -F "model=gpt-image-1-mini" \
  -F "prompt=把商品融合到简约室内背景中，保持商品细节真实" \
  -F "image=@product-front.png" \
  -F "image=@product-side.png" \
  -F "size=1024x1024"

视频任务

视频是异步任务：先创建，再轮询 /v1/videos/{id}，成功后下载 /content。

curl /videos

curl https://your-domain.example/v1/videos \
  -H "Authorization: Bearer sk-your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "video-pro-fast",
    "prompt": "A product video with slow camera movement and soft light",
    "duration": 5,
    "metadata": { "ratio": "16:9" }
  }'

Node.js 示例

OpenAI SDK

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.TOKENHUB_API_KEY,
  baseURL: "https://your-domain.example/v1"
});

const result = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello" }]
});

Python 示例

OpenAI SDK

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-token",
    base_url="https://your-domain.example/v1"
)

result = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}]
)

常见错误

先按这里排查，再联系管理员看 New API 渠道日志。

401 / API Key 无效

确认 Key 完整复制、没有空格，使用 Authorization: Bearer sk-xxx。刷新页面后前台不会再次显示完整 Key。

404 / model not found

确认模型已经在管理后台测试通过并开放，且请求里的 model 名称和模型广场完全一致。

503 / 无可用渠道

通常是模型分组、渠道分组或上游渠道不可用。需要管理员检查 New API 渠道和 TokenHub 模型配置。

524 / 上游超时

上游图片或视频服务响应慢，不代表 Key 错误。建议切换模型、降低并发或稍后重试。

余额不足

客户余额或上游渠道余额不足都会导致失败。先检查 TokenHub 余额，再检查 New API 上游渠道余额。

图片编辑失败

只传 model、prompt、image、n、size；多图使用重复 image 字段，不要传 image[] 或 response_format。