GPT Image

Global AI 的图像接口兼容 OpenAI 格式。只要把平台地址作为 base_url、把令牌作为 api_key，你现有的 OpenAI SDK 代码不用改结构就能直接跑。

准备工作

准备令牌

访问 globalai.vip/keys，复制一个以 sk- 开头的令牌。没有就点「创建API密钥」新建一个，详见令牌管理。令牌分 gpt-image-2k 与 gpt-image-4k 两个分组，能出的尺寸不一样，按你要的最大尺寸来选：

分组	能出的尺寸	价格
`gpt-image-2k`	1K、2K	更低
`gpt-image-4k`	1K、2K、4K	更高

一句话：不出 4K，用 gpt-image-2k 就够；要出 4K 必须用 gpt-image-4k，代价是单价更贵。两个分组具体能用哪些模型、各自什么价，见模型广场。

确认接口地址

生成端点 POST /v1/images/generations，编辑端点 POST /v1/images/edits。Base URL 都是 https://globalai.vip/v1。

装好 SDK

用 pip install openai 安装官方 SDK，然后按下面的示例把 base_url 指向 Global AI。（用技能方式可跳过此步。）

选好模型与尺寸

追求速度用 gpt-image-2.5-flare（默认），追求质量与文字准确用 gpt-image-2.5-sunburst。尺寸按需要的比例与分辨率选择，见下一节。

准备工作做完后，你有两种用法：技能方式（装一次技能，之后用自然语言让 AI 生图）和 HTTP 方式（用官方 SDK 或 curl 直接调接口）。挑一种即可：

用 Agent 技能调用（推荐）

装一次技能，之后让 AI 直接帮你生图，不用写请求代码。

用 OpenAI SDK 调用

用官方 SDK 或 curl 直接调接口，方便集成进你自己的代码。

模型与尺寸

模型	定位	适合场景
`gpt-image-2.5-flare`	速度优先（默认）	日常配图、草稿、快速迭代
`gpt-image-2.5-sunburst`	质量优先，文字排版准确	海报、封面、含文字的图
`gpt-image-2`	上一代主流模型	兼容旧代码

尺寸按像素数分三组：

分组	尺寸
1K	`1024x1024`
2K	`1536x1024`、`1024x1536`、`1792x1024`、`1024x1792`、`2048x2048`、`2048x1152`、`1152x2048`，以及像素数 ≤ 2560×1440 的其他合法尺寸
4K	`3840x2160`、`2160x3840`，以及像素数 > 2560×1440 的其他合法尺寸

「其他合法尺寸」需要同时满足这几条，超出范围会直接报错：

宽和高都是 16 的倍数
最长边不超过 3840
长短边比不超过 3:1
总像素数在 655,360 ~ 8,294,400 之间

默认回退：size 为空、auto 或格式非法时，按 2K 处理。分组决定计费与路由，实际输出尺寸由模型决定；响应里的 size 字段只是回显你请求的值，要拿真实尺寸请读 width / height 或直接看图片文件本身。

常用尺寸的实测耗时与体积：

尺寸	分组	比例	单张耗时	单张体积
`1024x1024`	1K	1:1	约 30-40 秒	约 2.5 MB
`1152x2048`	2K	9:16	约 45-50 秒	约 6 MB
`2160x3840`	4K	9:16	约 60-110 秒	约 13 MB
`3840x2160`	4K	16:9	约 60-110 秒	约 13 MB

尺寸与质量每升一档，耗时和配额消耗都会明显上升。建议先用 1024x1024 + low 把流程跑通，再切到目标尺寸。

用 Agent 技能调用

技能是一份 SKILL.md 加一个脚本。装一次之后，直接对 AI 说「用 globalai 生成一张 2K 竖版插画」就能生图，不用自己写请求代码。Codex、Claude Code、Hermes 都能用。

下载

https://static.globalai.vip/skill/globalai-image-gen-skill.zip

放到哪个文件夹

把解压得到的 globalai-image-gen/ 整个目录放进对应位置：

工具	放到哪
Codex	`~/.codex/skills/`（Windows：`%USERPROFILE%\.codex\skills`）
Claude Code	`~/.claude/skills/`（Windows：`%USERPROFILE%\.claude\skills`）
Hermes Agent	`~/.hermes/skills/creative/`（Windows：`%USERPROFILE%\.hermes\skills\creative`）

放好后重启一次客户端，技能才会被加载。

配置密钥

技能只需要一个密钥 GLOBALAI_API_KEY，按你的平台设置环境变量即可：

平台	设置方法
Linux	`echo 'export GLOBALAI_API_KEY=sk-xxxxxxxx' >> ~/.bashrc && source ~/.bashrc`
macOS	`echo 'export GLOBALAI_API_KEY=sk-xxxxxxxx' >> ~/.zshrc && source ~/.zshrc`
Windows (PowerShell)	`setx GLOBALAI_API_KEY "sk-xxxxxxxx"`（永久生效；本技能会直接读注册表，设完立刻可用，其他工具可能要重开终端）

不想动环境变量，也可以把密钥存进技能自己的私有配置：

保存密钥到技能私有配置

python3 ~/.codex/skills/globalai-image-gen/scripts/generate_image.py --save-api-key "sk-xxxxxxxx"

密钥的读取优先级是：--api-key 参数 > 环境变量（GLOBALAI_API_KEY、GLOBALAI_IMAGE_API_KEY）> 技能私有配置文件。私有配置只属于这个技能，不会读写 OPENAI_API_KEY。想知道密钥存在哪、或想删掉它：

查看与清除配置

python3 ~/.codex/skills/globalai-image-gen/scripts/generate_image.py --show-config-path
python3 ~/.codex/skills/globalai-image-gen/scripts/generate_image.py --clear-api-key

使用

对 Agent 直接下指令：

对 Agent 说

用 globalai 生成一张 2K 竖版插画，主题是星空下的水獭

或者手动执行脚本：

生成图片

python3 ~/.codex/skills/globalai-image-gen/scripts/generate_image.py \
  --prompt "一只戴围巾的水獭" \
  --model gpt-image-2.5-sunburst --size 1152x2048 --quality high --out out.png

编辑图片

python3 ~/.codex/skills/globalai-image-gen/scripts/generate_image.py --mode edit \
  --image input.png \
  --prompt "把背景改成雪山日落" \
  --size 1024x1024 --quality high --out edited.png

常用参数：

参数	说明
`--model`	默认 `gpt-image-2.5-flare`；可传 `gpt-image-2.5-sunburst` 或 `gpt-image-2`
`--size`	默认 `1024x1024`，可传 `auto` 或上表中的合法尺寸
`--quality`	默认 `low`；正式出图建议显式传 `high` 及以上
`--out` / `--output`	输出文件路径，两个名字等价
`--mode edit`	走编辑接口，配合 `--image`（可重复）与可选的 `--mask`
`--list-models`	列出当前密钥可用的模型，不确定模型 ID 时先跑这个
`--output-format`	默认 `png`，可传 `jpeg` / `webp`
`--n`	出图张数，默认 1；当前模型每次只出 1 张，要多张请多次调用

快捷操作 --save-api-key / --show-config-path / --clear-api-key 用于管理密钥；--api-key 与 --base-url 可以临时覆盖默认值。脚本只依赖 Python 标准库，不装 openai 包也能跑。

上面脚本路径以 Codex 为例；用其他工具时，把 ~/.codex/skills/ 换成上表里对应工具的实际位置即可。Windows 上把 python3 换成 python，路径换成 %USERPROFILE%\.codex\skills\ 这类形式。

技能脚本取图只走 b64_json：拿到 base64 就落盘，发现响应里只有 url 时直接报错停下，不会去依赖一个会过期的临时链接。如果你的尺寸与模型组合偏偏只回 url，改用下面的 SDK 或 curl 方式，并按「响应格式」一节把图片下载下来再交付。

用 OpenAI SDK 调用

安装 SDK

pip install openai

生成图片

image_gen.py

from openai import OpenAI
import base64

client = OpenAI(
    api_key="sk-xxxxxxxx",
    base_url="https://globalai.vip/v1",
)

resp = client.images.generate(
    model="gpt-image-2.5-sunburst",
    prompt="一只戴围巾的水獭，扁平插画风",
    size="1152x2048",
    quality="high",
    extra_body={"response_format": "b64_json"},
)

item = resp.data[0]
img = base64.b64decode(item.b64_json)

open("out.png", "wb").write(img)
print(f"已保存 {len(img) / 1e6:.2f} MB")

一定要带 response_format: "b64_json"。不传的时候，网关可能把图片放在预签名的 url 里返回，b64_json 会是空的；那个链接会过期，存下来也打不开。SDK 只对已知参数做校验，response_format 用 extra_body 传即可。

如果渠道仍然只回 url（item.b64_json 为空），图片同样拿得到，只是必须先下载、不能存链接：

兼容两种响应

import base64
import urllib.request

item = resp.data[0]

if item.b64_json:
    img = base64.b64decode(item.b64_json)
else:
    with urllib.request.urlopen(item.url, timeout=300) as r:
        img = r.read()

open("out.png", "wb").write(img)

编辑图片

编辑接口 POST /v1/images/edits 接收一张原图，按提示词修改。传 mask 可以指定只改哪一块：mask 图里透明的区域会被重绘，不透明的区域保持不动。原图与 mask 都支持 PNG、JPEG、WebP。

image_edit.py

from openai import OpenAI
import base64

client = OpenAI(
    api_key="sk-xxxxxxxx",
    base_url="https://globalai.vip/v1",
)

resp = client.images.edit(
    model="gpt-image-2.5-flare",
    image=open("input.png", "rb"),
    prompt="把背景改成雪山日落",
    size="1024x1024",
    quality="high",
    extra_body={"response_format": "b64_json"},
)

item = resp.data[0]
img = base64.b64decode(item.b64_json)

open("edited.png", "wb").write(img)

mask 需要和原图尺寸一致。如果你只想改一小块，把 mask 做成同尺寸、目标区域透明、其余不透明的 PNG。传多张原图时，image 参数可以重复传多次。

请求参数

生成接口：

参数	必填	说明
`model`	是	`gpt-image-2.5-flare` / `gpt-image-2.5-sunburst` / `gpt-image-2`
`prompt`	是	提示词，中英文均可
`size`	否	见「模型与尺寸」的尺寸分组；留空或 `auto` 按 2K 处理
`quality`	否	`auto` / `low` / `medium` / `high` / `xhigh` / `max`，其中 `xhigh` 与 `max` 仅 2.5 系列支持
`response_format`	否	传 `b64_json` 才会稳定拿到 base64 图片；不传可能只返回 `url`
`output_format`	否	`png`（默认）/ `jpeg` / `webp`
`n`	否	出图张数，当前取 1；要多张请并发发起多次请求
`background`	否	背景处理，响应会回显；透明背景需配合 `output_format` 为 `png` 或 `webp`，且并非所有模型都支持
`moderation`	否	内容审核档位，响应会回显，默认 `auto`

编辑接口：

参数	必填	说明
`model`	是	同生成接口
`image`	是	待编辑的图片，PNG / JPEG / WebP；可重复传多张
`prompt`	是	描述想怎么改
`mask`	否	指定编辑区域，透明处重绘，尺寸需与原图一致
`size`	否	输出尺寸，规则同生成接口
`quality`	否	同生成接口
`response_format`	否	同生成接口，建议固定传 `b64_json`

响应格式

图片可能以两种形式回到你手里，取决于这次请求走了哪条上游渠道。先看 b64_json，没有再看 url。

情况一：返回 b64_json（推荐）

请求里带上 response_format: "b64_json"，响应就直接返回 base64 编码的 PNG，解出来写文件即可：

响应（b64_json）

{
  "created": 1789010323,
  "model": "gpt-image-2.5-flare",
  "size": "1152x2048",              // 回显请求值
  "quality": "high",                // 回显请求值
  "output_format": "png",
  "background": "auto",
  "moderation": "auto",
  "data": [
    {
      "b64_json": "iVBORw0KGgo...",   // base64 编码的 PNG
      "width": 1152,                  // 实际输出宽（部分渠道返回）
      "height": 2048,                 // 实际输出高（部分渠道返回）
      "revised_prompt": "..."         // 模型改写后的提示词（部分渠道返回）
    }
  ],
  "usage": {
    "input_tokens": 14,
    "output_tokens": 974,
    "total_tokens": 988
  }
}

revised_prompt 是模型实际使用的提示词，效果和预期不一致时可以对比它排查是不是提示词被改写了。usage 里主要是 output_tokens（图像 token）在消耗配额，需要逐笔对账可以看使用记录。

4K 单张的 base64 比原图再大约三分之一，解析后不要直接打印到终端，先落盘再处理。

情况二：返回 url

同一个模型、同一个密钥，响应里放图片的位置也可能是 url 而不是 b64_json——这由该尺寸与模型走的上游渠道决定，不代表你的请求写错了：

响应（url）

{
  "created": 1789010323,
  "model": "gpt-image-2.5-flare",
  "size": "1024x1024",
  "quality": "low",
  "output_format": "png",
  "background": "auto",
  "moderation": "auto",
  "data": [
    {
      "url": "https://<对象存储域名>/images/<id>?X-Amz-Algorithm=...&X-Amz-Expires=..."
    }
  ],
  "usage": { "input_tokens": 14, "output_tokens": 974, "total_tokens": 988 }
}

这种 url 是预签名链接：带着临时凭证、会过期，过期后无法再取图。所以：

拿到之后立刻下载并落盘，不要把链接存进数据库，也不要把它当结果交给最终用户。
不要在流程里”先输出链接、稍后再下载”——中间只要过了有效期，图片就取不回来了。
一个响应里不会同时出现两者，判断 b64_json 是否存在即可分流。

url 只是取图的入口，不是图片本体。用”保存链接”代替”保存文件”，最后只会得到一堆打不开的结果。

并发与重试

可重试：429、500、502、503、504。
不要重试：400、401、403、余额不足——这些重试只会白等。
推荐退避：第一次失败等 2 秒，第二次失败等 4 秒，最多尝试 3 次。
客户端超时给足：4K 单张要 60-110 秒，HTTP 超时建议设到 300 秒以上，否则会把正常任务掐断。
并发建议：4K 同时发起 1-2 张比较稳；批量出图时一批跑完再起下一批，比一次性打满成功率更高。
OpenAI SDK 默认自带重试（max_retries=2），只覆盖 5xx；429 与连接错误建议自己再兜一层。

不装 SDK 时用 curl

生成图片

curl https://globalai.vip/v1/images/generations \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-sunburst",
    "prompt": "一只戴围巾的水獭，扁平插画风",
    "size": "1152x2048",
    "quality": "high",
    "response_format": "b64_json"
  }' -o resp.json

解出 PNG（b64_json 与 url 都能处理）

python3 -c "
import base64, json, urllib.request
item = json.load(open('resp.json'))['data'][0]
data = base64.b64decode(item['b64_json']) if item.get('b64_json') else urllib.request.urlopen(item['url'], timeout=300).read()
open('out.png', 'wb').write(data)
print('saved', len(data), 'bytes')
"

编辑图片

curl https://globalai.vip/v1/images/edits \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -F model=gpt-image-2.5-flare \
  -F image=@input.png \
  -F prompt="把背景改成雪山日落" \
  -F size=1024x1024 \
  -F response_format=b64_json \
  -o resp.json

编辑接口是 multipart/form-data，curl 用 -F 传文件；生成接口是 JSON，用 -d。响应里的 b64_json 是 base64 文本，解出来才是 PNG。

常见错误

401 invalid api key / 余额不足

令牌不正确、已过期或已被删除，到令牌管理检查令牌状态；如果提示配额用完，到配额与充值补充配额，或提高该令牌的配额上限。这两种情况重试都不会成功。

400：模型、尺寸或参数有问题

模型 ID 拼写错误，或当前令牌不允许该模型，用 GET https://globalai.vip/v1/models 核对。尺寸要满足「模型与尺寸」里的合法范围：宽高都是 16 的倍数、最长边 ≤ 3840、长短边比 ≤ 3:1、总像素数在 655,360 ~ 8,294,400 之间，也别把 1K、2K、4K 直接当尺寸值传。quality 用了当前模型不支持的档位，xhigh 与 max 只有 2.5 系列支持。编辑接口则要确认 image 是 PNG、JPEG 或 WebP，且传 mask 时与原图尺寸一致。请求本身有问题，重试不会成功。

429 / 502 / 503：限流与上游抖动

429 是短时间内请求过多或并发过高，按 2 秒、4 秒退避重试并降低并发。502 是上游服务抖动，原样重试一次通常即可成功。503（model_not_found）是当前尺寸对应的模型分组没有可用渠道，换一个尺寸重试或联系客服补充渠道。连接超时同理，重试前先把客户端超时设到 300 秒以上；超时后重试是安全的，但可能产生两次计费。

响应里是 url 而不是 b64_json

这不算错误：说明这条渠道把图片放进了预签名的 url，b64_json 与 url 不会同时出现，判断 b64_json 是否存在即可。url 会过期，拿到就立刻下载落盘，不要存链接。技能脚本遇到这种情况会直接报错停下，改用 SDK 或 curl 方式，并按「响应格式」一节处理。

保存的图片打不开

b64_json 是 base64 编码的 PNG，要先 base64.b64decode 再写入文件；直接当文本写会得到损坏文件。用 curl 时先把响应存成 resp.json 再解码，别把响应直接重定向成 .png。

接入准备

编程类客户端

聊天类客户端

低代码平台

图像生成

准备工作

用 Agent 技能调用（推荐）

用 OpenAI SDK 调用

模型与尺寸

用 Agent 技能调用

下载

放到哪个文件夹

配置密钥

使用

用 OpenAI SDK 调用

生成图片

编辑图片

请求参数

响应格式

情况一：返回 b64_json（推荐）

情况二：返回 url

并发与重试

不装 SDK 时用 curl

常见错误

​准备工作

用 Agent 技能调用（推荐）

用 OpenAI SDK 调用

​模型与尺寸

​用 Agent 技能调用

​下载

​放到哪个文件夹

​配置密钥

​使用

​用 OpenAI SDK 调用

​生成图片

​编辑图片

​请求参数

​响应格式

​情况一：返回 b64_json（推荐）

​情况二：返回 url

​并发与重试

​不装 SDK 时用 curl

​常见错误

准备工作

模型与尺寸

用 Agent 技能调用

下载

放到哪个文件夹

配置密钥

使用

用 OpenAI SDK 调用

生成图片

编辑图片

请求参数

响应格式

情况一：返回 b64_json（推荐）

情况二：返回 url

并发与重试

不装 SDK 时用 curl

常见错误