> ## Documentation Index > Fetch the complete documentation index at: https://docs.globalai.vip/llms.txt > Use this file to discover all available pages before exploring further. # GPT Image > 用 OpenAI 官方 SDK 调用 /v1/images/generations 与 /v1/images/edits 生成、编辑图片，并把生图能力封装成 Codex、Claude Code、Hermes 通用的 Agent 技能。 Global AI 的图像接口兼容 OpenAI 格式。只要把平台地址作为 `base_url`、把 [令牌](/zh/usage/tokens) 作为 `api_key`，你现有的 OpenAI SDK 代码不用改结构就能直接跑。 ## 准备工作 访问 [globalai.vip/keys](https://globalai.vip/keys)，复制一个以 `sk-` 开头的令牌。没有就点「**创建API密钥**」新建一个，详见 [令牌管理](/zh/usage/tokens)。 令牌分 `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`，代价是单价更贵。两个分组具体能用哪些模型、各自什么价，见[模型广场](https://globalai.vip/pricing)。 生成端点 `POST /v1/images/generations`，编辑端点 `POST /v1/images/edits`。Base URL 都是 `https://globalai.vip/v1`。 用 `pip install openai` 安装官方 SDK，然后按下面的示例把 `base_url` 指向 Global AI。（用技能方式可跳过此步。） 追求速度用 `gpt-image-2.5-flare`（默认），追求质量与文字准确用 `gpt-image-2.5-sunburst`。尺寸按需要的比例与分辨率选择，见下一节。 准备工作做完后，你有两种用法：**技能方式**（装一次技能，之后用自然语言让 AI 生图）和 **HTTP 方式**（用官方 SDK 或 curl 直接调接口）。挑一种即可： 装一次技能，之后让 AI 直接帮你生图，不用写请求代码。 用官方 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**](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"`（永久生效；本技能会直接读注册表，设完立刻可用，其他工具可能要重开终端） | 不想动环境变量，也可以把密钥存进技能自己的私有配置： ```bash 保存密钥到技能私有配置 icon=terminal theme={null} 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`。想知道密钥存在哪、或想删掉它： ```bash 查看与清除配置 icon=terminal theme={null} 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 直接下指令： ```text 对 Agent 说 theme={null} 用 globalai 生成一张 2K 竖版插画，主题是星空下的水獭 ``` 或者手动执行脚本： ```bash 生成图片 icon=terminal theme={null} python3 ~/.codex/skills/globalai-image-gen/scripts/generate_image.py \ --prompt "一只戴围巾的水獭" \ --model gpt-image-2.5-sunburst --size 1152x2048 --quality high --out out.png ``` ```bash 编辑图片 icon=terminal theme={null} 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 调用 ```bash 安装 SDK icon=terminal theme={null} pip install openai ``` ### 生成图片 ```python image_gen.py icon=python theme={null} 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` 为空），图片同样拿得到，只是必须先下载、不能存链接： ```python 兼容两种响应 icon=python theme={null} 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。 ```python image_edit.py icon=python theme={null} 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，解出来写文件即可： ```json 响应（b64_json） theme={null} { "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）在消耗配额，需要逐笔对账可以看 [使用记录](/zh/usage/logs)。 4K 单张的 base64 比原图再大约三分之一，解析后不要直接打印到终端，先落盘再处理。 #### 情况二：返回 url 同一个模型、同一个密钥，响应里放图片的位置也可能是 `url` 而不是 `b64_json`——这由该尺寸与模型走的上游渠道决定，不代表你的请求写错了： ```json 响应（url） theme={null} { "created": 1789010323, "model": "gpt-image-2.5-flare", "size": "1024x1024", "quality": "low", "output_format": "png", "background": "auto", "moderation": "auto", "data": [ { "url": "https://<对象存储域名>/images/?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 ```bash 生成图片 icon=terminal theme={null} 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 ``` ```bash 解出 PNG（b64_json 与 url 都能处理） icon=terminal theme={null} 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') " ``` ```bash 编辑图片 icon=terminal theme={null} 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。 ## 常见错误 令牌不正确、已过期或已被删除，到 [令牌管理](/zh/usage/tokens) 检查令牌状态；如果提示配额用完，到 [配额与充值](/zh/billing/topup) 补充配额，或提高该令牌的配额上限。这两种情况重试都不会成功。 模型 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` 是短时间内请求过多或并发过高，按 2 秒、4 秒退避重试并降低并发。`502` 是上游服务抖动，原样重试一次通常即可成功。`503`（`model_not_found`）是当前尺寸对应的模型分组没有可用渠道，换一个尺寸重试或联系客服补充渠道。连接超时同理，重试前先把客户端超时设到 300 秒以上；超时后重试是安全的，但可能产生两次计费。 这不算错误：说明这条渠道把图片放进了预签名的 `url`，`b64_json` 与 `url` 不会同时出现，判断 `b64_json` 是否存在即可。`url` 会过期，拿到就立刻下载落盘，不要存链接。技能脚本遇到这种情况会直接报错停下，改用 SDK 或 curl 方式，并按「响应格式」一节处理。 `b64_json` 是 base64 编码的 PNG，要先 `base64.b64decode` 再写入文件；直接当文本写会得到损坏文件。用 curl 时先把响应存成 `resp.json` 再解码，别把响应直接重定向成 `.png`。