生图 API — 图片生成与改图接入

用 ZetaAPI 调用 gpt-image-2 生成 / 编辑图片。OpenAI Images 兼容格式，含 curl / Python / Node 示例、改图 multipart、输出尺寸、计费与超时说明。

更新于 2026-07-26

ZetaAPI 的生图接口与 OpenAI Images API 完全兼容，用你现有的 API Key 即可调用 gpt-image-2 生成图片或按提示改图，无需改 SDK。想先在线试玩，去控制台的 生图 Playground；本文讲如何用代码接入。

Base URL 与认证

生图请求走生图专用域：

https://image.zetaapi.ai

所有请求携带 Authorization: Bearer sk-xxxxx（与对话接口共用同一套 API Key）。

为什么生图单独一个域：生图是非流式长请求，等待上游出图最长可达 240 秒。主域 api.zetaapi.ai 前面有 CDN，连接在约 120 秒就会被切断——你会收到一个失败，但上游那张图仍然生成了，也仍然计费。生图专用域直连源站，没有这个限制，所以请勿在主域上对生图做自动重试。

该域只服务 /v1/images/generations 与 /v1/images/edits 两个端点。其他接口——包括下文用 /v1/chat/completions 调用的 Gemini 高分辨率生图——仍然走 https://api.staging.cosmos-router.com。

若你收到过我们早前的迁移通知，里面写的是 direct.zetaapi.ai：该域名继续有效，两者完全等价。

测试域名是否可用

该域对上述两个端点之外的任何请求（包括根路径 /）都会直接断开连接——curl 报的是 Empty reply from server 或 HTTP/2 stream 1 was not closed cleanly: PROTOCOL_ERROR，而不是 404。这是有意的安全策略，不代表域名不可用。

要确认域名通不通，直接 POST 端点本身（不带 Key，也不消耗额度）：

curl -i -X POST https://image.zetaapi.ai/v1/images/generations \
  -H "Content-Type: application/json" -d '{}'

返回 401 Authorization Required 就说明 DNS、TLS 与网关一切正常，它只是在要求你带上 API Key。

端点

生成图片

参数

curl

curl https://image.zetaapi.ai/v1/images/generations \
  -H "Authorization: Bearer sk-xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a red panda coding at night, neon rim light, 16:9 cinematic banner",
    "n": 1
  }'

Python（openai SDK）

import base64
from openai import OpenAI

client = OpenAI(api_key="sk-xxxxx", base_url="https://image.zetaapi.ai/v1")

resp = client.images.generate(
    model="gpt-image-2",
    prompt="a red panda coding at night, neon rim light, 16:9 cinematic banner",
    n=1,
)

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

Node.js（openai SDK）

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

const client = new OpenAI({
  apiKey: "sk-xxxxx",
  baseURL: "https://image.zetaapi.ai/v1",
});

const resp = await client.images.generate({
  model: "gpt-image-2",
  prompt: "a red panda coding at night, neon rim light, 16:9 cinematic banner",
  n: 1,
});

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

响应

{
  "created": 1730000000,
  "data": [{ "b64_json": "iVBORw0KGgo..." }],
  "usage": { "input_tokens": 12, "output_tokens": 1024, "total_tokens": 1036 }
}

默认返回 b64_json（base64 编码的 PNG）。传 "response_format": "url" 可改为返回图片链接。

输出尺寸

用提示词控制宽高比，不要用 size 参数。

gpt-image-2 的每张图都按固定的约 157 万像素预算渲染。这个上限提不上去 —— 在提示词里写「4K」或「3840x2160」也不会得到更多像素。但形状是可控的：在提示词里描述宽高比，会被精确执行。

支持范围是 1:3 ~ 3:1。常见比例会被精确命中（如 16:9 → 1672×941）；接近边界时取最接近的可用尺寸，例如要 1:3 实测得到约 1:2.9。像素总量不变，所以任何比例价格相同。

size 参数为了让 OpenAI SDK 继续可用而被接受，但会被忽略 —— 传 size: "1024x1536" 配中性提示词，返回的仍是方图。需要精确像素尺寸时，请按最接近的比例生成后在本地缩放。

需要真正更高的分辨率？这个像素上限来自 gpt-image-2 的上游、我们改不了 —— 请改用 Gemini 3 Pro Image，最高可到 17MP。

高分辨率：Gemini 3 Pro Image

需要真实像素的场景（印刷、大幅横幅、壁纸）请用 gemini-3-pro-image-preview。分辨率可选且会被精确执行（下表为未传 aspect_ratio 时的实测尺寸；改比例后宽高会相应变化，像素总量档位不变）：

该模型在 /v1/images/* 上不可用 —— 上游只通过 chat completions 提供。与 Images API 有两点不同：

1. 调 POST /v1/chat/completions，分辨率放在 extra_body 里传。
2. 图片是以 Markdown data-URI 的形式嵌在 choices[0].message.content 中，不是 data[0].b64_json。

curl https://api.staging.cosmos-router.com/v1/chat/completions \
  -H "Authorization: Bearer sk-xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image-preview",
    "messages": [{"role": "user", "content": "Generate an image: a red panda coding at night, neon rim light"}],
    "extra_body": {"google": {"image_config": {"image_size": "4K"}}}
  }'

import base64, re
from openai import OpenAI

client = OpenAI(api_key="sk-xxxxx", base_url="https://api.staging.cosmos-router.com/v1")

resp = client.chat.completions.create(
    model="gemini-3-pro-image-preview",
    messages=[{"role": "user", "content": "Generate an image: a red panda coding at night"}],
    # SDK 的 extra_body 会把内容合并到请求体顶层，而网关读的是顶层的
    # `extra_body` 字段，所以这里必须再套一层 —— 少套一层会静默降级回 1K。
    extra_body={"extra_body": {"google": {"image_config": {"image_size": "4K"}}}},
)

content = resp.choices[0].message.content
# content 形如："Image generated successfully.\n![image](data:image/png;base64,iVBOR...)"
m = re.search(r"base64,([A-Za-z0-9+/=]+)", content or "")
if not m:
    raise RuntimeError(f"响应里没有图片（可能被拒绝或返回了纯文本）：{content!r}")
with open("out.png", "wb") as f:
    f.write(base64.b64decode(m.group(1)))

说明：

• 按 token 计费（与对话一致）：2K 约 1,120 图片 token（≈ $0.06），4K 约 2,000（≈ $0.09）。单价见价格页。
• 同一个 image_config 里还支持 aspect_ratio（如 "16:9"）。
• 非流式，且比低分辨率的 gpt-image-2 慢：通常 20–60 秒，4K 偶尔更久。注意：这条走的是对话链路，网关首字节预算为 90 秒 —— 4K 配复杂提示词有可能触发 504，遇到时重试或降到 2K。
• 4K 的 PNG 在 base64 前约 19MB，JSON 响应约 25MB —— 请确认你的客户端和中间代理能接收这么大的响应。

在控制台里输出 4K

不写代码也可以：打开控制台 → 生图 Playground，把分辨率选成「4K（长边 ≥ 3840）」。生图和改图两个标签页都支持。

• 生成结果直接就是 4K，点右上角「下载」保存
• 该档位每次生成一张
• 需要较新版本的桌面端 Chrome 或 Edge；不支持的浏览器上这一项会置灰

这是控制台的功能。通过 API 调用 gpt-image-2 时，输出仍是上面说的约 157 万像素。

改图（edits）

改图用 multipart/form-data，上传原图（必填）+ 遮罩 mask（可选，标出要修改的区域，透明处会被重绘）：

curl https://image.zetaapi.ai/v1/images/edits \
  -H "Authorization: Bearer sk-xxxxx" \
  -F model=gpt-image-2 \
  -F 'prompt=把中心的方块改成蓝色' \
  -F image=@source.png \
  -F mask=@mask.png

• 原图 + 遮罩合计 ≤ 14MB（超出返回 413）
• 图片格式 png / jpeg
• size 与文生图一致 —— 接受但忽略，见输出尺寸

在 Codex 里生图

Codex 自带一个内置生图工具 image_gen，但它对本平台不可用 —— 这不是配置问题， 不用去找开关。

image_gen 是 hosted tool，Codex 把它硬编码限制在 ChatGPT 登录态。凡是用 API Key + 自定义 base_url 接入的会话（通过 cc-switch 等工具中转的都属于这一类），这个工具 根本不会出现在模型的工具列表里，[features] image_generation = true 对这种会话 也不生效。OpenAI 官方 issue #24465 正在跟进，目前无解。

我们提供了一个 Codex 插件来补这个洞：

codex plugin marketplace add Hermerz/zetaapi-codex-plugins
codex plugin add zeta-imagegen@zetaapi
export ZETAAPI_KEY=sk-你的Key

装完在 Codex 里直接说「画一张赛博朋克风格的城市夜景，16:9」即可，改图也支持 （「把这张图改成雪天」+ 指定本地文件）。

插件只接受 ZETAAPI_KEY，或当前启用的 model_provider 其 base_url 指向本平台时 复用它的 Key。它不会去读你其它服务商的凭据 —— 网关 Key 与 OpenAI / Anthropic 的 Key 形态无法区分，靠猜会把你真实的第三方凭据发错地方，所以归属判定基于 base_url 而不是 Key 本身。源码公开：Hermerz/zetaapi-codex-plugins

不想装插件也可以：Codex 能执行命令，把本页上面的 curl 包成一个脚本让它调即可， 效果一样。

计费、延迟与超时

• 按次计费：每次生成 / 改图都会真实扣除该 Key 的额度，具体倍率以 价格页 为准。改图会把整张原图作为输入，input token 明显更高。
• 延迟：生图通常 20–60 秒，复杂提示（多视图、超精细渲染等）或高峰期可超过 3 分钟。请把客户端超时设到 ≥ 300 秒，不要过早掐断——网关在 240 秒仍未收到上游首字节才会返回 504，早于此自行断开只会白等。改图（/v1/images/edits）另计：客户端超时通常从上传开始计时，而网关的 240 秒预算要等原图上传完才起算，请设到 ≥ 上传耗时 + 300 秒（保守取 ≥ 400 秒）。
• 生图为非流式，一次性返回完整结果。

错误码

与其它接口一致，常见：

完整错误码见 API Reference。

更多

• 在线试玩 → 控制台 生图 Playground
• 通用 API → API Reference
• 计费细节 → 价格页