返回博客
GPT ImageImage GenerationMultimodalAPIOpenAI CompatibleNbility

GPT-image / 多模态生图 API 新手教程

从文本生图、参考图编辑、Base URL、b64_json 保存到错误排查，带你用 OpenAI-compatible API 搭好第一条可复用的图片生成工作流。

GPT-image / 多模态生图 API 新手教程

GPT-image / 多模态生图 API 新手教程封面

很多人第一次接触生图 API，会把它想成“发一句 prompt，返回一张图”。真正开始接到产品、公众号配图、社群机器人或自动化工作流里以后，你会很快遇到更具体的问题：图片为什么返回 base64？文本生图和参考图编辑是不是同一个接口？尺寸、质量、格式怎么选？失败时应该重试，还是提示用户换描述？

这篇文章用新手能直接照抄的方式，讲清楚 GPT-image / 多模态生图 API 的基本调用路径。示例会使用 OpenAI-compatible 的写法，并把 Nbility 放在统一 API 入口的位置：你只需要管理一个 Base URL、一个 API Key 和模型名，就能更容易地记录用量、排查错误和替换模型。

先分清三件事：看图、文生图、图生图/编辑

“多模态”这个词很容易让人混淆。做图片工作流时，建议先把需求拆成三类：

  • 看图理解：把图片作为输入，让模型描述、识别、OCR、判断风格或提取信息。OpenAI 文档把这类能力归到 Images and Vision，Chat Completions / Responses 等 API 都可能用到图片输入。
  • 文本生成图片：只给一段 prompt，让图像模型从零生成图片。OpenAI Image API 里的 images/generations 就是典型入口。
  • 参考图编辑 / 多图参考：上传一张或多张图片，再用 prompt 指定“保留人物、换背景、改风格、补画某个区域”。OpenAI 图像编辑接口支持 GPT image 模型使用 png、webp、jpg 等输入，具体大小、数量和 mask 规则要看模型文档。

新手最容易踩坑的是：你想“让模型看一张图后再生成另一张图”，这不一定等于一个普通聊天请求。实际工程里通常要明确：图片是作为视觉理解输入、作为生图参考，还是作为编辑接口里的 image 文件。

生图 API 调用路径

为什么推荐先用 Image API，而不是一开始就做复杂 Agent

OpenAI 官方文档里，图片生成可以通过 Image API，也可以在 Responses API 里作为 image generation tool 使用。简单理解：

  • Image API：适合“一次请求生成一张或几张图”的场景，接口直观，便于接入脚本、后端、自动化任务。
  • Responses API + image_generation tool：适合多轮对话式编辑，例如先生成，再让模型继续“改得更真实一点”“把背景换成办公室”。

如果你刚开始做公众号封面、文章配图、商品图草稿，建议先从 Image API 开始。等你需要“多轮编辑历史”“把上一次输出留在上下文里”“让 Agent 自己决定生成还是编辑”时，再考虑 Responses API。

准备环境变量

为了避免把密钥写进代码，先准备一个 .env：

NBILITY_API_KEY=[REDACTED]
NBILITY_BASE_URL=https://api.nbility.dev/v1
NBILITY_IMAGE_MODEL=gpt-image-2

如果你的账号里暂时没有 gpt-image-2，可以把模型名换成当前可用的 GPT image 模型。关键是三项要统一：

  • base_url 指向 OpenAI-compatible API 根路径，通常要带 /v1；
  • api_key 使用 Bearer Token；
  • model 必须是支持图片生成的模型，而不是普通聊天模型。

最小 Python 示例：文本生成图片

安装依赖：

python -m venv .venv
source .venv/bin/activate
pip install openai python-dotenv

新建 generate_image.py：

import base64
import os
from pathlib import Path

from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()

client = OpenAI(
    api_key=os.environ["NBILITY_API_KEY"],
    base_url=os.environ.get("NBILITY_BASE_URL", "https://api.nbility.dev/v1"),
)

prompt = """
A clean hero image for a technical blog post about AI image generation APIs:
a developer desk, floating image thumbnails, API request cards, black and orange color palette,
modern 3D illustration, no readable text.
"""

result = client.images.generate(
    model=os.environ.get("NBILITY_IMAGE_MODEL", "gpt-image-2"),
    prompt=prompt,
    size="1536x1024",
    quality="medium",
)

image_base64 = result.data[0].b64_json
image_bytes = base64.b64decode(image_base64)

out = Path("generated-cover.png")
out.write_bytes(image_bytes)
print(f"saved: {out.resolve()}")

运行：

python generate_image.py

如果成功，你会得到一个 generated-cover.png。很多 GPT image 模型默认返回的是 base64 图片数据，而不是永久 URL，所以代码里要自己解码并保存文件。

cURL 示例：先验证请求链路

当 Python SDK 报错不直观时，建议先用 curl 验证链路：

curl -X POST "https://api.nbility.dev/v1/images/generations"   -H "Authorization: Bearer $NBILITY_API_KEY"   -H "Content-Type: application/json"   -d '{
    "model": "gpt-image-2",
    "prompt": "A minimal orange and black illustration of an AI image API pipeline, no text",
    "size": "1024x1024",
    "quality": "medium"
  }'   | jq -r '.data[0].b64_json'   | base64 --decode > test.png

这一步能帮你快速确认四件事：Base URL 是否正确、API Key 是否有效、模型是否可用、返回字段是否是 b64_json。

参考图编辑：把图片作为输入

当你想“保留这只猫的姿势，把背景换成赛博朋克城市”时，就不是纯文本生图，而是图片编辑。OpenAI 图像编辑参考里提到，GPT image 模型的编辑接口可以接收 png、webp、jpg 输入，单张图片上限和最多图片数量要以当前模型文档为准；mask 则用于指定哪些透明区域需要被编辑。

Python 示例可以写成这样：

import base64
import os
from pathlib import Path

from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()
client = OpenAI(
    api_key=os.environ["NBILITY_API_KEY"],
    base_url=os.environ.get("NBILITY_BASE_URL", "https://api.nbility.dev/v1"),
)

result = client.images.edit(
    model=os.environ.get("NBILITY_IMAGE_MODEL", "gpt-image-2"),
    image=open("input.png", "rb"),
    prompt="Keep the main character, change the background into a cozy orange developer studio, no text.",
    size="1536x1024",
    quality="medium",
)

Path("edited.png").write_bytes(base64.b64decode(result.data[0].b64_json))

注意：不同模型对透明背景、任意尺寸、输入图数量、mask、input_fidelity 的支持并不完全一样。如果你要做稳定产品，不要只在 UI 里写一个 prompt 输入框，最好把模型支持的参数白名单写死。

参数怎么选：尺寸、质量、格式

新手可以先用这套默认值：

  • 文章封面横图：1536x1024；
  • 正方形社媒图：1024x1024；
  • 竖图海报：1024x1536；
  • 质量：先用 medium，定稿或商业图再用 high；
  • 格式：默认 png，如果要网页加载更快，再考虑 webp 或 jpeg；
  • 数量：默认 n=1，批量生成时用队列控制，不要让用户一次生成太多。

OpenAI 参考文档里也提醒，部分模型支持自定义尺寸，但有宽高能否被 16 整除、宽高比、最大分辨率等限制。为了减少失败率，业务侧最好只开放几个经过验证的尺寸按钮。

放进产品时，不要让用户等在请求里

图片生成通常比聊天慢。一个更稳的后端流程是：

  1. 用户提交 prompt；
  2. 后端创建任务，返回 task_id；
  3. worker 调用生图 API；
  4. 保存图片到对象存储或本地静态目录；
  5. 前端轮询任务状态，或通过消息机器人回传图片链接。

这样即使上游排队、超时、重试，也不会让 HTTP 请求一直挂着。Nbility 作为统一 API 入口的好处也在这里：你可以把图片生成和聊天总结的消耗放在同一个用量面板里看，按用户、群、文章项目或自动化任务做成本归因。

错误排查：先看哪一层失败

生图 API 新手排错清单

常见错误可以这样分：

  • 401 / 403：密钥错误、权限不足、模型未开通，先检查 Authorization 和模型名。
  • 400：参数不兼容，例如尺寸不支持、透明背景不支持、mask 尺寸和原图不一致、上传文件格式不对。
  • 429：请求过多或限流，应该进入队列，稍后重试，而不是让用户狂点按钮。
  • timeout / upstream error：上游生成慢或临时失败，可以自动重试一次，但不要无限重试。
  • safety / policy：提示词触发安全策略，应该告诉用户换一种描述，而不是假装“网络错误”。

一个实用原则是：只对网络抖动、排队超时、上游 5xx 自动重试；对 400、401、403、安全策略类错误直接提示用户修正输入。

Prompt 写法：别只写风格词

生图 prompt 建议包含五类信息：

主体：画面里最重要的人、物、场景
用途：公众号封面、产品 banner、教程插图、社媒海报
构图：横图/竖图、留白位置、近景/远景
风格：写实、3D、扁平插画、动漫、品牌色
限制：不要可读文字、不要水印、不要 logo 冒充

例如：

A horizontal technical blog cover about multimodal image generation API.
Main subject: a developer dashboard with floating image thumbnails and API request cards.
Composition: leave clean title space on the left, main visual on the right.
Style: modern 3D illustration, black and orange palette, soft lighting.
Constraints: no readable text, no watermark, no real company logos.

不要把所有需求塞成一长串风格词。越接近实际用途，越容易得到能用的图。

一个可复用的后端函数

最后，把调用封装成函数，方便以后接到公众号封面、社群机器人或批量营销图工作流里：

import base64
import os
from pathlib import Path
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NBILITY_API_KEY"],
    base_url=os.environ.get("NBILITY_BASE_URL", "https://api.nbility.dev/v1"),
)

def generate_image(prompt: str, out_path: str, *, size="1536x1024", quality="medium") -> Path:
    if len(prompt) > 4000:
        raise ValueError("prompt too long for this application policy")

    result = client.images.generate(
        model=os.environ.get("NBILITY_IMAGE_MODEL", "gpt-image-2"),
        prompt=prompt,
        size=size,
        quality=quality,
    )

    data = result.data[0].b64_json
    path = Path(out_path)
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_bytes(base64.b64decode(data))
    return path

生产环境里再补上：任务队列、用户限流、失败分类、图片审核、对象存储、用量记录。做到这一步，生图 API 就不再只是“玩一下”，而是可以进入真实内容生产链路的能力。

参考链接

相关文章

给公众号文章自动生成封面图
微信公众号封面图Image Generation

给公众号文章自动生成封面图

从文章标题、摘要、关键词到 900×383 头条封面、383×383 分享封面和 1283×383 组合图，搭建一套可复用的公众号封面自动生成工作流。

给小红书/推文生成配图工作流
小红书XTwitter

给小红书/推文生成配图工作流

从标题、卖点和平台尺寸出发，用 AI 生成小红书首图、轮播卡片和 X/Twitter 推文配图，并用脚本控制安全区、比例、导出和审核。

用 Nbility 跑通你的 Agent 工作流

获取 API Key，统一接入 OpenAI 兼容模型和开发工具。

管理 API Key