API 接入文档

快速开始

只需三步，即可开始使用 zeroHub。

注册账号

访问 https://zerohub.zhyy.ltd/ 注册并登录您的账号。
获取 API Key

进入控制台，在「API 密钥」页面生成您的专属密钥。密钥格式为 sk-img-xxxxxxx，请妥善保管。

发起第一个请求

使用下方的 cURL 命令快速测试：

cURL

curl -X POST https://zerohub.zhyy.ltd/v1/images/generations \
  -H "Authorization: Bearer sk-img-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只在夕阳下奔跑的小猫"
  }'

提交任务

POST 生成请求

→

获取 Task ID

返回任务编号

→

轮询状态

GET 查询任务

→

获取图片

返回图片 URL

认证方式

所有 API 请求需在 HTTP 请求头中携带 Authorization 字段，使用 Bearer Token 方式进行身份验证。

HTTP Header

Authorization: Bearer sk-img-your-api-key-here

安全提示：请勿在客户端代码（如前端 JavaScript）中直接暴露 API Key。建议将密钥存储在服务端环境变量中，通过后端代理调用 API。

API Key 的特征：

以 sk-img- 为前缀
在控制台中创建和管理
支持创建多个密钥，方便不同项目使用
可随时吊销已泄露的密钥

生成图片

提交图片生成任务。该接口采用异步模式，提交后立即返回任务 ID，您需要通过「查询任务状态」接口获取生成结果。

POST /v1/images/generations

请求参数

参数	类型	必填	说明
`model`	string	是	模型名称，当前支持 `gpt-image-2`
`prompt`	string	是	图片描述文本，建议使用英文获得更好效果
`images`	array<string>	否	参考图片 URL 列表，用于图生图模式
`size`	string	否	输出宽高比。支持：`1:1` `3:2` `2:3` `4:3` `3:4` `5:4` `4:5` `16:9` `9:16` `21:9` `9:21`，默认 `1:1`
`quality`	enum<string>	否	输出质量。支持：`auto` `low` `medium` `high`，默认 `auto`。`low` 对应 1K，`medium` 对应 2K，`high` 对应 4K，所有宽高比均可使用。

请求示例

JSON

{
  "model": "gpt-image-2",
  "prompt": "a beautiful sunset over the ocean",
  "size": "16:9",
  "quality": "medium",
  "images": ["https://example.com/reference.jpg"]
}

响应示例

JSON — 200 OK

{
  "created": 1714700000,
  "data": [
    {
      "url": null,
      "revised_prompt": "任务已提交: task_abc123def456"
    }
  ]
}

异步生成：返回的 revised_prompt 字段中包含任务 ID（格式如 task_xxx）。请提取该 ID 并使用「查询任务状态」接口获取最终图片。

查询任务状态

根据任务 ID 查询图片生成进度及结果。建议在首次查询后间隔 3-5 秒轮询，直到任务完成。

GET /v1/images/query/{task_id}

路径参数

参数	类型	说明
`task_id`	string	任务 ID，从生成接口返回值中提取

任务状态

状态	含义	说明
pending	处理中	图片正在生成，请稍后重试
success	成功	图片已生成完成，`images` 数组中包含 URL
failed	失败	生成失败，费用已自动退还

响应示例 — 成功

JSON — 成功

{
  "task_id": "task_abc123def456",
  "status": "success",
  "created": 1714700000,
  "images": [
    "https://cdn.zhyy.ltd/images/result_001.png"
  ]
}

响应示例 — 处理中

JSON — 处理中

{
  "task_id": "task_abc123def456",
  "status": "pending",
  "created": 1714700000,
  "images": []
}

查询余额

查看当前账户余额及调用配额信息。

GET /v1/user/balance

响应参数

字段	类型	说明
`balance`	number	当前账户余额（元）
`cost_per_call`	number	每次调用费用（元）
`remaining_calls`	integer	剩余可用调用次数

响应示例

JSON

{
  "balance": 49.50,
  "cost_per_call": 0.50,
  "remaining_calls": 99
}

错误码

API 使用标准 HTTP 状态码表示请求结果。当请求失败时，响应体中会包含详细的错误信息。

错误响应格式

JSON

{
  "error": {
    "code": 401,
    "message": "Invalid API key",
    "type": "authentication_error"
  }
}

错误码列表

状态码	错误类型	说明	处理建议
`401`	认证失败	API Key 无效或已过期	检查 Authorization 头是否正确，确认密钥未被吊销
`402`	余额不足	账户余额不足以完成本次请求	前往控制台充值后再试
`429`	请求过频	超出速率限制	降低请求频率，建议添加重试间隔（指数退避）
`502`	上游错误	上游 AI 服务暂时不可用	稍后重试，若持续出现请联系技术支持

重试策略建议：对于 429 和 502 错误，建议使用指数退避（Exponential Backoff）策略进行重试。首次等待 1 秒，第二次 2 秒，第三次 4 秒，依此类推，最多重试 3-5 次。

完整示例

以下提供 Python、cURL、JavaScript 三种语言的完整调用示例，包含任务提交和状态轮询。

Python

import requests
import time

BASE_URL = "https://zerohub.zhyy.ltd"
API_KEY  = "sk-img-your-api-key"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type":  "application/json",
}

# ── 1. 提交生成任务 ──
payload = {
    "model":  "gpt-image-2",
    "prompt": "一只穿着宇航服的柴犬在月球上散步，科幻风格",
}

resp = requests.post(
    f"{BASE_URL}/v1/images/generations",
    headers=headers,
    json=payload,
)
data = resp.json()

# 提取 task_id
task_info = data["data"][0]["revised_prompt"]
task_id  = task_info.split(": ")[1]
print(f"✓ 任务已提交: {task_id}")

# ── 2. 轮询任务状态 ──
while True:
    time.sleep(5)
    query_resp = requests.get(
        f"{BASE_URL}/v1/images/query/{task_id}",
        headers=headers,
    )
    result = query_resp.json()

    if result["status"] == "success":
        print(f"✓ 图片已生成: {result['images']}")
        break
    elif result["status"] == "failed":
        print("✗ 生成失败，费用已退还")
        break
    else:
        print("⏳ 生成中，请稍候...")

cURL

Bash

# ── 提交生成任务 ──
RESPONSE=$(curl -s -X POST \
  "https://zerohub.zhyy.ltd/v1/images/generations" \
  -H "Authorization: Bearer sk-img-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a beautiful sunset over the ocean",
  }')

echo "提交响应: $RESPONSE"

# ── 从响应中提取 task_id ──
TASK_ID=$(echo "$RESPONSE" | grep -oP 'task_\w+')
echo "任务 ID: $TASK_ID"

# ── 查询任务状态 ──
curl -s \
  "https://zerohub.zhyy.ltd/v1/images/query/$TASK_ID" \
  -H "Authorization: Bearer sk-img-your-api-key" | python3 -m json.tool

# ── 查询余额 ──
curl -s \
  "https://zerohub.zhyy.ltd/v1/user/balance" \
  -H "Authorization: Bearer sk-img-your-api-key" | python3 -m json.tool

JavaScript (Fetch)

JavaScript

const BASE_URL = "https://zerohub.zhyy.ltd";
const API_KEY  = "sk-img-your-api-key";

const headers = {
  "Authorization": `Bearer ${API_KEY}`,
  "Content-Type":  "application/json",
};

// ── 1. 提交生成任务 ──
async function generateImage(prompt) {
  const resp = await fetch(`${BASE_URL}/v1/images/generations`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      model:  "gpt-image-2",
      prompt,
      n: 1,
    }),
  });
  const data = await resp.json();
  return data.data[0].revised_prompt.split(": ")[1];
}

// ── 2. 轮询任务状态 ──
async function waitForResult(taskId) {
  while (true) {
    await new Promise(r => setTimeout(r, 5000));
    const resp = await fetch(
      `${BASE_URL}/v1/images/query/${taskId}`,
      { headers }
    );
    const result = await resp.json();

    if (result.status === "success") return result.images;
    if (result.status === "failed") throw new Error("生成失败");
    console.log("⏳ 生成中...");
  }
}

// ── 使用 ──
(async () => {
  const taskId = await generateImage("赛博朋克风格的东京街头");
  console.log(`✓ 任务已提交: ${taskId}`);
  const images = await waitForResult(taskId);
  console.log(`✓ 图片链接: ${images}`);
})();

计费说明

采用按次计费模式，价格透明，无隐藏费用。

单次调用

¥0.50 / 次

每次提交图片生成任务扣费一次，无论生成结果如何。

文生图模式
图生图模式
高质量 AI 模型
异步任务处理

退款机制

100% 退还

当图片生成失败时，系统将自动退还该次调用的全部费用。

失败自动退款
实时余额更新
透明消费记录
无最低消费

计费时机：费用在任务提交时扣除，而非在生成完成时。若生成失败，费用将自动退还至您的账户余额。您可随时在控制台查看详细的消费记录。

AI 图片生成 API 文档

快速开始

注册账号

获取 API Key

发起第一个请求

认证方式

生成图片

请求参数

请求示例

响应示例

查询任务状态

路径参数

任务状态

响应示例 — 成功

响应示例 — 处理中

查询余额

响应参数

响应示例

错误码

错误响应格式

错误码列表

完整示例

Python

cURL

JavaScript (Fetch)

计费说明