生图 API · gpt-image-2

用 OpenAI 协议生图 · 一行 curl 跑通

我们的 OpenAI 兼容生图接口已经上线,模型 gpt-image-2,协议跟 OpenAI 官方完全一致(POST /v1/images/generations)。按张计价、不按 token:¥0.05 / ¥0.10 / ¥0.20 三档,自定义按量充值最低 ¥10 起。

想离线阅读? 完整接入手册 PDF · v2

原本

https://api.openai.com

→

改成

https://api.handsfreeclub.com

只改 OPENAI_BASE_URL 一个字段,SDK / curl / Python 全协议兼容

30 秒摘要

设 OPENAI_BASE_URL=https://api.handsfreeclub.com/v1 + OPENAI_API_KEY=sk-xxxx,然后调 POST /v1/images/generations,模型填 gpt-image-2。按 quality 计价:low 1K ¥0.05、medium 2K ¥0.10(默认)、high 4K ¥0.20。返回 b64_json,自己 base64 解码存盘。只想生图不想跑 Claude Code 的:在「按量充值」分组买 ¥10 起的额度,生 100 张 2K 或 200 张 1K。

⚡ Step 0 · 推荐

一键脚本:OPENAI_* 环境变量自动写好

脚本会同时把 OPENAI_API_KEY + OPENAI_BASE_URL 写进你的 ~/.zshrc / ~/.bashrc,Python openai SDK、curl、Node SDK 全部即拿即用,不用手敲 export。没装 Node / Python 也没事——脚本顺带帮你装好 nvm + Node LTS + claude + codex 二进制(纯用户态、不要 sudo),你只想生图也直接拿来 curl 跑。不希望脚本动你系统就加 --no-install-cli。

terminal

# 默认装 Claude Code + Codex CLI,顺带写 OPENAI_* / ANTHROPIC_*
curl -fsSL https://handsfreeclub.com/install.sh | bash -s -- --key sk-你的key

脚本会:① 用 claude-haiku-4-5 探活验证 Key + 链路 ② 写 ~/.zshrc / ~/.bashrc(OPENAI_API_KEY + OPENAI_BASE_URL=https://api.handsfreeclub.com/v1 + 三个 ANTHROPIC_*,原文件自动备份) ③ Codex CLI 写 ~/.codex/config.toml + auth.json(权限 600) ④ 没 Node 自动装 nvm + LTS ⑤ 装好 claude + codex 二进制。 装完直接 echo $OPENAI_BASE_URL 验证,然后跳到 Step 2 跑 curl 测试一行出图。

或者手动配置 ↓

注册 · 选「按量充值」分组拿 Key#

没注册过的话,先注册一个账号。进 Console 创建 Key 时,选「按量充值」分组——这个分组同时支持 Claude / Codex 文本和 gpt-image-2 生图,价格按 USD 透传 + 中国区汇率,不绑套餐。

key

sk-XXXXXXXXXXXXXXXXXXXXXXXX  # 末 4 位会显示在 Console,出问题报这 4 位给客服

「只想生图」的用户路径:不买月度套餐,直接「按量充值」最低 ¥10 起,余额半年保留,生一张扣一张。¥10 → 100 张 2K / 200 张 1K,适合做素材的人。

第一次生图:curl 一行跑通#

跑通你这把 Key 的链路,只要复制下面这一行,把 sk-XXXX 改成你的 Key,粘进终端回车。大约 20 秒后会返回 base64 编码的 PNG,我们用 jq 解码存成 out.png。

纯 shell,不依赖任何 SDK。装好 curl 和 jq 就能跑(macOS / Linux 默认有,Windows 用 WSL):

terminal

curl -sS https://api.handsfreeclub.com/v1/images/generations \
  -H "Authorization: Bearer sk-XXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只戴着草帽的橘猫坐在窗台上看夕阳, 暖色调, 油画风",
    "size": "1024x1024",
    "quality": "medium",
    "n": 1
  }' \
  | jq -r '.data[0].b64_json' | base64 -d > out.png && open out.png

正常情况 15-25 秒返回,生成的 PNG 约 1-2 MB。如果超 60 秒还没动静,网关会返回 504——重试一次或者把 quality 降到 low 看看是不是 prompt 太复杂。

装好官方 openai SDK(pip install openai),环境变量已设的话(Step 0 一键脚本会写好)直接跑:

image_gen.py

from openai import OpenAI
import base64

client = OpenAI()  # 自动读 OPENAI_API_KEY + OPENAI_BASE_URL

resp = client.images.generate(
    model="gpt-image-2",
    prompt="一只戴着草帽的橘猫坐在窗台上看夕阳, 暖色调, 油画风",
    size="1024x1024",
    quality="medium",  # low / medium / high
    n=1,
)

with open("out.png", "wb") as f:
    f.write(base64.b64decode(resp.data[0].b64_json))
print("saved out.png, revised_prompt =", resp.data[0].revised_prompt)

返回字段里 revised_prompt 是 gpt-image-2 改写后的最终 prompt(模型会做安全/具象化改写),想原样不改写就在 prompt 里写"完全按我的描述,不要改写"。

装好官方 openai SDK(npm i openai),Node 18+:

image_gen.mjs

import OpenAI from "openai";
import { writeFileSync } from "fs";

const client = new OpenAI();  // 读 OPENAI_API_KEY + OPENAI_BASE_URL

const resp = await client.images.generate({
  model: "gpt-image-2",
  prompt: "一只戴着草帽的橘猫坐在窗台上看夕阳, 暖色调, 油画风",
  size: "1024x1024",
  quality: "medium",
  n: 1,
});

writeFileSync("out.png", Buffer.from(resp.data[0].b64_json, "base64"));
console.log("saved out.png");

Node 端没有 OPENAI_BASE_URL 自动读取,要么手动在 new OpenAI({ baseURL: "https://api.handsfreeclub.com/v1" }) 里写死,要么用 dotenv 读出来传进去。

核对扣费 · 看 Console 数字跳#

跑完 Step 2 那条 curl,马上去余额查询页输 Key,你会看到 used 增加 ¥0.10(2K 一张的价)。这一步是确认计费走通了。

余额查询返回示例

{
  "key_tail": "...62b4e",
  "group": "按量充值-base",
  "quota": "¥10.00",
  "used": "¥0.10",        // ← 跑了一次 2K 后跳的
  "remaining": "¥9.60"
}

没跳数 / 跳得不对 → 立刻报给客服(末 4 位 + 时间戳),我们能在日志里翻到那条请求的实际计费过程。计费透明是我们认死的底线。

三档价格 · 1K / 2K / 4K#

gpt-image-2 按 quality 字段定价,对应 1K / 2K / 4K 三档。不传 quality 默认走 2K。

quality	实际渲染分辨率	单价 / 张	典型耗时
low	`1K`	¥0.05	~10 秒
medium 默认	`2K`	¥0.10	~20 秒
high	`4K`	¥0.20	~30 秒

¥10 充值能跑多少张?——200 张 1K、100 张 2K、50 张 4K。混合用按实际单价扣减,不四舍五入。

不知道选哪档?按用途挑:

缩略图 / 草图 / 批量预览

1K ¥0.05

出图快、便宜。批量探索 prompt、做 mood board、社交媒体配图缩略图就够了。能省 50%。

日常用图 / 公众号配图

2K ¥0.10

默认档。大多数场景的甜点:文章配图、PPT 插图、自媒体素材,清晰度够、成本可控。

海报 / 印刷 / 商品图

4K ¥0.20

细节最丰富、文字渲染最稳。要打印、要做封面 / 海报 / 广告物料的时候用,贵一倍但少返工。

支持的 size:1024x1024(方)、1024x1536(竖)、1536x1024(横)。size 只控制画面比例,1K / 2K / 4K 用 quality 选择。

常见错误速查#

401

认证失败

检查 OPENAI_API_KEY 末 4 位是否跟 Console 显示一致。常见坑:复制时漏了 sk- 前缀,或者 Bearer 后面没空格。

404 path

地址漏了 /v1

必须是 https://api.handsfreeclub.com/v1/images/generations。Python SDK 自动加 /v1,curl 要手动写全。

400 invalid size

size 不在白名单

只支持 1024x1024 / 1024x1536 / 1536x1024。这些是方图 / 竖图 / 横图的比例选择;清晰度档位用 quality 里的 1K / 2K / 4K。

400 content policy

prompt 触发安全过滤

gpt-image-2 上游有内容政策,涉及暴力 / 真人脸名人 / 露骨内容会拒。这一次不扣费,改 prompt 重试就行。

402 / quota

余额不够

跑这一张前,余额必须 ≥ 单张价格。余额半年保留,加充就续命。充值 →

504

生图超时

high 档复杂 prompt 偶尔会超 60 秒被网关切。退一档(high → medium / medium → low)或简化 prompt 重试。

502 / 503

上游或网关抖动

OpenAI 上游或我方网关临时不稳,30 秒内自动恢复。持续 5 分钟以上看 status page。

model not found

模型名拼错

必须填 gpt-image-2(不是 gpt-image-1 / dall-e-3)。我们目前只对接 gpt-image-2,其它型号不在中转范围。

排查 5 分钟还没解决?把错误码 + Key 末 4 位 + 时间戳发到 Telegram @prosper777888 或 support@handsfreeclub.com,30 分钟内有人回。

FAQ · 生图用户常问#

我只想生图,不跑 Claude Code,能直接买额度吗?

能,这是我们专门留的路径。注册时选「按量充值」分组,最低充 ¥10,余额半年保留,生一张扣一张:¥0.05 / ¥0.10 / ¥0.20。¥10 起步 → 200 张 1K / 100 张 2K / 50 张 4K,做素材完全够。

不用绑月度套餐、不用承诺最低消费。想生 100 张 2K 就充 ¥10,Console 显示余额、Key 即开即用。

支持图生图(image edit / variation)吗?

当前版本只开了 text-to-image(POST /v1/images/generations)。/v1/images/edits 和 /v1/images/variations 在路线图里,要等 gpt-image-2 上游对应能力稳定后再开,预计本季度内。

需要图生图的用户先在 Telegram @prosper777888 报个名,内测开放时优先发邀请。

返回的是 b64_json 还是 URL?

始终返回 b64_json(base64 编码的 PNG 字节流),不返回 CDN URL。原因是我们不长期托管图片——你拿到 base64 后自己解码存盘 / 上传 / 入库。

这跟 OpenAI 官方的 gpt-image-2 行为一致,SDK 端反序列化逻辑不用改。

同一把 Key 能既跑 Claude Code 又生图吗?

能,「按量充值」分组的 Key 同时支持文本(Anthropic / OpenAI 协议)和生图。文本走 token 计费、生图走按张计费,两类调用扣同一个余额池。

Console 的账单页会分开列出文本消耗和生图消耗,各自分项。

生成失败了会扣钱吗?

不会。只有 200 OK 且实际拿到图片字节才扣费。401 / 400 / content policy 拒绝 / 504 超时这些都不扣,Console 也不会出现这条记录。

有疑问随时把 Key 末 4 位 + 时间戳发客服,我们能在网关日志里翻到那条请求的实际计费过程。

能批量并发吗?(同时生 20 张)

能。我们没有人工 RPM 限制,但 OpenAI 上游对 gpt-image-2 有账号级 RPM 上限——稳态并发 ~10 没问题,再高偶尔会拿到 429,代码里加个简单 backoff retry 就行。

需要稳定 50+ 并发的(批量生成图库的场景),提前在 Telegram 报一下,我们给你走独立上游 shard。

prompt 用中文还是英文效果好?

gpt-image-2 中英文都吃,但英文 prompt 在艺术风格、镜头语言、构图描述上的细节理解稍好。中文 prompt 的优势是描述本土化场景(中式建筑、二十四节气、汉字招牌)时更准。

建议:主体描述用中文,风格 / 光影 / 镜头描述夹英文术语(cinematic lighting、wide-angle、matte painting)。

商用授权怎么处理?

跟 OpenAI gpt-image-2 上游政策一致:生成的图片你享有商用权,我们和 OpenAI 都不主张版权。但要遵守 OpenAI 内容政策(不生成真人脸名人 / 暴力 / 露骨内容)。

需要法务证明 / 商用授权说明书的企业用户,联系客服出书面文件。

跑通了?直接充值开生图

按量充值 ¥10 起,可生约 200 张 1K 或 100 张 2K,余额半年保留,不绑套餐。

注册账户 → 联系客服充值 ¥10 起