gpt image 2 official api integration guide zh hant image 0 图示

gpt-image-2 接入官方 API 的 9 步實戰指南：從零到生產

作者:

OpenAI 在 2026 年 4 月發佈的 gpt-image-2 已成爲圖像生成賽道最受關注的模型——99% 字符級文字渲染準確率、4K 高清輸出、原生中文/CJK 支持、O 系列推理能力整合。但很多開發者拿到模型後第一個問題就是：gpt-image-2 接入官方 API 究竟應該怎麼做？哪些參數是必需的？base_url 怎麼配？響應裏的 b64_json 拿到後該怎麼用？

本文是一份端到端的 gpt-image-2 接入官方 API 實戰指南，覆蓋從 SDK 安裝、base_url 配置到文生圖、圖片編輯、inpainting、錯誤處理的全部技術細節。所有代碼都基於 OpenAI 官方 SDK 和 APIYI 官轉通道（與官方字段 100% 一致），跑完本文你的項目就能立即在生產環境使用 gpt-image-2。

gpt-image-2-official-api-integration-guide-zh-hant 图示

gpt-image-2 接入官方 API 的準備工作清單

在寫第一行代碼之前，需要先把環境準備好。下面這份清單覆蓋了 gpt-image-2 接入官方 API 必須的 4 個先決條件。

gpt-image-2 接入官方 API 的環境清單

準備項 要求 說明
API Key 有效 Bearer Token 通過 APIYI 控制檯申請，註冊即可獲取測試額度
Python SDK openai >= 1.50.0 舊版本不支持 images.generate（） 的新參數
Node.js SDK openai >= 4.50.0 TypeScript 類型已同步官方
HTTP 超時 ≥ 360 秒 high 畫質 + 2K/4K 實測耗時 3-5 分鐘
網絡要求 國內可直連 api.apiyi.com 國內/家寬/海外節點均可訪問

gpt-image-2 接入官方 API 的 SDK 安裝

無論選擇哪種語言，安裝 OpenAI 官方 SDK 即可——APIYI 官轉通道與官方字段完全一致，不需要額外的客戶端庫。

# Python
pip install --upgrade openai

# Node.js
npm install openai@latest

# 如果使用 yarn / pnpm
yarn add openai
pnpm add openai

gpt-image-2 接入官方 API 的 API Key 獲取流程

獲取 API Key 的步驟極簡：

  1. 訪問 APIYI 控制檯 api.apiyi.com
  2. 註冊賬戶後進入「API 令牌」頁面
  3. 創建新 Token（建議爲不同項目使用獨立 Token 便於審計）
  4. 將 Token 保存到環境變量（強烈不建議硬編碼到代碼）

🚀 快速上手建議：首次接入 gpt-image-2 官方 API 時，推薦先用低畫質 + 1024×1024 跑通鏈路，再切換到 high 畫質和大尺寸。我們建議通過 API易 apiyi.com 平臺領取測試額度，免費額度足夠完成 PoC 全流程驗證。

# 在 ~/.zshrc 或 ~/.bashrc 中加入
export APIYI_KEY="sk-your-token-here"

gpt-image-2 接入官方 API 的 base_url 配置

整個 gpt-image-2 接入官方 API 流程中，唯一與原生 OpenAI SDK 不同的就是 base_url。把它從 api.openai.com 替換爲 api.apiyi.com，其他代碼全部保持一致。

gpt-image-2-official-api-integration-guide-zh-hant 图示

gpt-image-2 接入官方 API 的兩個端點

APIYI 提供與 OpenAI 完全一致的兩個圖像端點：

端點 用途 必需參數
POST /v1/images/generations 文生圖（純 prompt 生成） model、prompt
POST /v1/images/edits 圖片編輯、多圖融合、mask 重繪 model、prompt、image

gpt-image-2 接入官方 API 的客戶端初始化

下面給出 Python 和 Node.js 的客戶端初始化代碼，記住一定要把超時設置到 360 秒以上。

# Python
import os
from openai import OpenAI

client = OpenAI（
    api_key=os.getenv（"APIYI_KEY"），
    base_url="https://api.apiyi.com/v1"，  # 切到 APIYI 官轉通道
    timeout=600.0，                         # 高畫質場景必須延長
    max_retries=2
）

// Node.js
import OpenAI from "openai"；

const client = new OpenAI（{
  apiKey: process.env.APIYI_KEY，
  baseURL: "https://api.apiyi.com/v1"，  // 注意是 baseURL（駝峯）
  timeout: 600 * 1000，                  // 毫秒
  maxRetries: 2
}）；

💡 超時設置提醒：默認的 60 秒超時在 high 畫質 + 2K/4K 場景下必然失敗。我們建議通過 API易 apiyi.com 接入時，所有生產環境客戶端的請求超時都設置在 360-600 秒區間，避免長尾請求被錯誤中斷。

gpt-image-2 接入官方 API 的文生圖調用

進入實戰環節。下面用三種語言展示如何完成第一次 gpt-image-2 接入官方 API 的文生圖調用。

gpt-image-2 接入官方 API 的 Python 文生圖

import base64
from openai import OpenAI

client = OpenAI（
    api_key=os.getenv（"APIYI_KEY"），
    base_url="https://api.apiyi.com/v1"，
    timeout=600.0
）

response = client.images.generate（
    model="gpt-image-2"，
    prompt="A modern minimalist office desk with a vintage typewriter， soft morning light from the window， photorealistic， 8K"，
    size="1536x1024"，
    quality="high"，
    output_format="jpeg"，
    output_compression=92，
    n=1
）

# 關鍵: APIYI 返回的是純 base64 字符串，無 data:image/... 前綴
b64 = response.data[0].b64_json
with open（"output.jpg"， "wb"） as f:
    f.write（base64.b64decode（b64））

print（"✓ 圖像已保存到 output.jpg"）

gpt-image-2 接入官方 API 的 Node.js 文生圖

import fs from "node:fs/promises"；
import OpenAI from "openai"；

const client = new OpenAI（{
  apiKey: process.env.APIYI_KEY，
  baseURL: "https://api.apiyi.com/v1"，
  timeout: 600_000
}）；

const response = await client.images.generate（{
  model: "gpt-image-2"，
  prompt: "An e-commerce product photo of a leather backpack on a marble desk， studio lighting"，
  size: "1024x1024"，
  quality: "high"，
  output_format: "png"，
  n: 1
}）；

const b64 = response.data[0].b64_json；
await fs.writeFile（"output.png"， Buffer.from（b64， "base64"））；
console.log（"✓ 圖像已保存"）；

gpt-image-2 接入官方 API 的 cURL 文生圖

cURL 適合快速驗證 API Key 可用性、測試新參數組合。

curl https://api.apiyi.com/v1/images/generations \
  -H "Authorization: Bearer $APIYI_KEY" \
  -H "Content-Type: application/json" \
  --max-time 600 \
  -d '{
    "model": "gpt-image-2"，
    "prompt": "A futuristic cyberpunk city at night， neon signs in mixed Chinese and English"，
    "size": "2048x1152"，
    "quality": "high"，
    "output_format": "jpeg"，
    "output_compression": 90，
    "n": 1
  }' | jq -r '.data[0].b64_json' | base64 -d > output.jpg

注意 --max-time 600 必加——cURL 默認無超時，但很多 shell 包裝會加上 60 秒強制中斷。

gpt-image-2 接入官方 API 的響應處理要點

很多開發者第一次接入時會卡在 base64 解析。下面是幾個容易踩坑的點：

# ✗ 錯誤：APIYI 不返回 url 字段
url = response.data[0].url  # AttributeError

# ✓ 正確：使用 b64_json
b64 = response.data[0].b64_json

# ✗ 錯誤：瀏覽器直接渲染純 b64 字符串
<img src="{b64}">  # 不會顯示

# ✓ 正確：瀏覽器渲染需手動拼接前綴
data_uri = f"data:image/jpeg；base64，{b64}"
# <img src="{{ data_uri }}">

# ✓ 正確：服務端保存到磁盤
with open（"output.jpg"， "wb"） as f:
    f.write（base64.b64decode（b64））

gpt-image-2 接入官方 API 的完整參數詳解

掌握每個參數的取值範圍和適用場景，是 gpt-image-2 接入官方 API 進入生產環境的關鍵。

gpt-image-2-official-api-integration-guide-zh-hant 图示

gpt-image-2 接入官方 API 的核心參數表

參數 取值 默認值 說明
model "gpt-image-2" 必填 模型 ID
prompt 字符串 必填 提示詞，支持中英文混合
size 8 種預設 + 自定義 auto 詳見下表
quality auto / low / medium / high auto 影響成本和耗時
output_format png / jpeg / webp png 推薦 jpeg + 90 壓縮
output_compression 1-100 100 僅對 jpeg/webp 生效
moderation auto / low auto low 降低審覈敏感度
n 1-10 1 單次生成數量

gpt-image-2 接入官方 API 的 size 參數完整選項

# 8 種官方預設
size = "1024x1024"   # 1:1 標準方圖
size = "1536x1024"   # 3:2 橫版
size = "1024x1536"   # 2:3 豎版
size = "2048x2048"   # 2K 方圖
size = "2048x1152"   # 16:9 橫版（適合電腦壁紙/海報）
size = "3840x2160"   # 4K 橫版
size = "2160x3840"   # 4K 豎版（適合手機壁紙）
size = "auto"        # 由模型自動選擇

如果需要自定義尺寸，必須滿足以下約束：

✓ 邊長是 16 的整數倍
✓ 最大邊長 ≤ 3840px
✓ 長短邊比例 ≤ 3:1
✓ 總像素在 655，360 ~ 8，294，400 之間

例如 1280x720（720P）合法，3840x1080（超寬屏）會因爲比例 > 3:1 被拒絕。

gpt-image-2 接入官方 API 的 quality 與成本對照

quality 是影響成本最大的參數。下面是完整定價對照表（每張圖）。

畫質 1024×1024 1024×1536 1536×1024 適用場景
low $0.006 $0.005 $0.005 草圖、縮略圖、快速迭代
medium $0.053 $0.041 $0.041 內容站、自媒體配圖
high $0.211 $0.165 $0.165 商品圖、海報、廣告物料

💰 成本優化：日均生圖 100 張的內容團隊，使用 medium 畫質比 high 節省 75% 成本。我們建議通過 API易 apiyi.com 平臺先用 low 畫質快速跑 prompt 調優，定稿後再升級到 medium/high 出最終圖，能把月度圖像生成預算降低 30-50%。

gpt-image-2 接入官方 API 的 output_format 選擇

輸出格式直接影響存儲成本和加載速度：

# 透明背景需求？gpt-image-2 不支持，會報 400
# ✗ output_format="png"， background="transparent" → 400 Bad Request

# 網頁/小程序展示：jpeg + 壓縮 90
output_format="jpeg"， output_compression=90

# 高保真存檔：png（無損）
output_format="png"

# 現代 Web 應用：webp 體積最小
output_format="webp"， output_compression=85

gpt-image-2 接入官方 API 的圖片編輯與 inpainting

除了文生圖，gpt-image-2 還支持圖片編輯、多圖融合、局部重繪（inpainting/outpainting）三大編輯場景。

gpt-image-2-official-api-integration-guide-zh-hant 图示

gpt-image-2 接入官方 API 的圖片編輯（參考圖模式）

參考圖編輯會自動啓用 high-fidelity 模式——所以不要傳 input_fidelity 參數（會被拒絕）。

from openai import OpenAI

client = OpenAI（
    api_key=os.getenv（"APIYI_KEY"），
    base_url="https://api.apiyi.com/v1"
）

# 單張參考圖編輯
with open（"source.jpg"， "rb"） as img:
    response = client.images.edit（
        model="gpt-image-2"，
        image=img，
        prompt="把背景換成日落海灘，保留前景人物姿勢和服裝"，
        size="1024x1024"，
        quality="high"
    ）

gpt-image-2 接入官方 API 的多圖融合（最多 16 張）

/images/edits 端點支持最多 16 張參考圖同時輸入，prompt 中用「圖1/圖2/圖3」指代。

images = [
    open（"character.jpg"， "rb"），     # 圖1：角色
    open（"background.jpg"， "rb"），    # 圖2：背景
    open（"outfit.jpg"， "rb"），        # 圖3：服裝參考
]

response = client.images.edit（
    model="gpt-image-2"，
    image=images，
    prompt="將圖1的角色放置在圖2的背景中，讓角色穿上圖3的服裝風格，保持電影質感"，
    size="2048x1152"，
    quality="high"
）

這個能力在電商商品換背景、虛擬試穿、漫畫分鏡生成等場景極爲強大。

gpt-image-2 接入官方 API 的 Inpainting 局部重繪

Inpainting 通過 mask 參數指定要重繪的區域。關鍵規則：

  • mask 必須與第一張參考圖尺寸一致
  • mask 是帶 alpha 通道 的 PNG
  • 透明區域 = 要重繪的區域
  • 不透明區域 = 保持原圖
with open（"photo.png"， "rb"） as img， open（"mask.png"， "rb"） as msk:
    response = client.images.edit（
        model="gpt-image-2"，
        image=img，
        mask=msk，
        prompt="把紅框區域換成一隻橙色的貓"，
        size="1024x1024"，
        quality="high"
    ）

如果你需要在 Python 中程序化生成 mask，可以用 PIL：

from PIL import Image

# 創建一個與原圖同尺寸的 mask，默認全黑（不透明 = 保留）
mask = Image.new（"RGBA"， （1024， 1024）， （0， 0， 0， 255））

# 把要重繪的區域改爲透明（alpha=0）
for x in range（400， 700）:
    for y in range（300， 600）:
        mask.putpixel（（x， y）， （0， 0， 0， 0））

mask.save（"mask.png"）

gpt-image-2 接入官方 API 的錯誤處理與生產實踐

把 gpt-image-2 接入官方 API 推到生產，必須處理好錯誤碼、併發、超時三大問題。

gpt-image-2 接入官方 API 的完整錯誤碼錶

HTTP 狀態碼 含義 推薦處理
400 參數非法（size 越界、傳了不支持字段） 校驗輸入；不要傳 input_fidelity 或 background:transparent
401 令牌無效 檢查 Bearer Token、確認未過期
403 內容審覈攔截 調整 prompt，或加 moderation: "low"
429 限流 / 餘額不足 指數退避重試 + 餘額檢查
5xx 網關或後端錯誤 重試 1-2 次，仍失敗上報告警
超時 長尾請求未及時響應 客戶端超時設到 ≥ 360 秒

gpt-image-2 接入官方 API 的指數退避重試

下面是一個生產級的重試封裝，處理 429 和 5xx：

import time
import random
from openai import OpenAI， RateLimitError， APIStatusError

client = OpenAI（
    api_key=os.getenv（"APIYI_KEY"），
    base_url="https://api.apiyi.com/v1"，
    timeout=600.0
）

def generate_with_retry（prompt: str， max_retries: int = 5）:
    delay = 1.0
    for attempt in range（max_retries）:
        try:
            return client.images.generate（
                model="gpt-image-2"，
                prompt=prompt，
                size="1024x1024"，
                quality="high"
            ）
        except RateLimitError:
            sleep = delay + random.uniform（0， 0.5）
            print（f"429 限流，{sleep:.1f}s 後重試 （{attempt+1}/{max_retries}）"）
            time.sleep（sleep）
            delay *= 2
        except APIStatusError as e:
            if 500 <= e.status_code < 600 and attempt < max_retries - 1:
                time.sleep（delay）
                delay *= 2
                continue
            raise
    raise RuntimeError（"超過最大重試次數"）

gpt-image-2 接入官方 API 的併發控制

批量任務用 asyncio.Semaphore 限制併發數，避免短時打爆下游：

import asyncio
from openai import AsyncOpenAI

aclient = AsyncOpenAI（
    api_key=os.getenv（"APIYI_KEY"），
    base_url="https://api.apiyi.com/v1"，
    timeout=600.0
）

async def gen_one（prompt: str， sem: asyncio.Semaphore）:
    async with sem:
        return await aclient.images.generate（
            model="gpt-image-2"，
            prompt=prompt，
            size="1024x1024"，
            quality="medium"
        ）

async def batch（prompts: list[str]， concurrency: int = 30）:
    sem = asyncio.Semaphore（concurrency）
    return await asyncio.gather（*[gen_one（p， sem） for p in prompts]）

# 跑 200 張圖，30 路併發
prompts = [f"商品場景圖變體 #{i}" for i in range（200）]
results = asyncio.run（batch（prompts））

gpt-image-2 接入官方 API 的成本預估

生產前先做成本預估。下面是幾個典型場景的月度費用估算：

業務場景 日均量 畫質 月成本估算
自媒體配圖 30 張 medium ~$48
電商商品圖 200 張 high ~$1266
SaaS 用戶生圖 1000 次 medium ~$1590
遊戲關鍵幀 500 張 high ~$3165

🎯 生產部署建議：建議爲不同業務線申請獨立 API Token 便於成本歸因和限流隔離。我們建議通過 API易 apiyi.com 控制檯開啓賬單告警，當月度消耗達到預設閾值時自動通知，避免預算超支。

gpt-image-2 接入官方 API 的可觀測性

生產環境務必記錄每次請求的關鍵指標：

import time
import logging

logger = logging.getLogger（"gpt-image-2"）

def call_with_metrics（prompt: str， **params）:
    start = time.perf_counter（）
    try:
        resp = client.images.generate（model="gpt-image-2"， prompt=prompt， **params）
        latency = time.perf_counter（） - start
        logger.info（
            "gpt-image-2 ok"，
            extra={
                "latency_ms": int（latency * 1000），
                "size": params.get（"size"），
                "quality": params.get（"quality"），
                "n": params.get（"n"， 1）
            }
        ）
        return resp
    except Exception as e:
        logger.error（f"gpt-image-2 failed: {type（e）.__name__}: {e}"）
        raise

關於 gpt-image-2 接入官方 API 的常見問題 FAQ

Q1：gpt-image-2 接入官方 API 時爲什麼會出現 input_fidelity 報 400？

gpt-image-2 在所有編輯場景自動啓用 high-fidelity，因此 input_fidelity 參數被拒絕。直接刪掉這個參數即可。如果你的代碼是從 gpt-image-1 遷移過來，需要全局搜索移除。我們建議通過 API易 apiyi.com 文檔對比新舊模型的參數差異：docs.apiyi.com。

Q2：gpt-image-2 接入官方 API 調用爲什麼經常超時？

high 畫質 + 2K/4K 單張圖實測耗時 3-5 分鐘。如果客戶端默認超時是 60 秒，必然失敗。修復方案：把 timeout 設到 360-600 秒。Python SDK 用 OpenAI（timeout=600），Node.js 用 timeout: 600_000，cURL 用 --max-time 600。

Q3：gpt-image-2 接入官方 API 返回的 b64_json 怎麼直接顯示在網頁上？

API 返回的是純 base64 字符串無前綴，瀏覽器無法直接渲染。需要拼接：

const dataUri = `data:image/${format}；base64，${b64}`；
imgElement.src = dataUri；

如果是後端服務，建議把 base64 解碼後保存到 OSS/CDN，前端只接收 URL，避免 base64 字符串塞滿 HTML 影響首屏速度。我們建議通過 API易 apiyi.com 平臺測試時優先用 cURL + base64 解碼到本地文件驗證，確認鏈路通暢後再接入完整的存儲分發架構。

Q4：gpt-image-2 接入官方 API 時透明背景能做嗎？

目前 gpt-image-2 不支持透明背景，傳 background: "transparent" 會被 400 拒絕。變通方案：生成純白/純綠背景圖後，用客戶端工具（如 rembg 庫）摳圖獲得透明背景。

Q5：gpt-image-2 接入官方 API 的 thinking 參數怎麼用？

thinking 是 gpt-image-2 引入的推理參數（off / low / medium / high），開啓後模型會先做佈局規劃再生成，質量更高但成本會顯著上升（high 模式成本約 4-5 倍基礎值）。建議：只在文字密集型海報、複雜構圖場景使用 medium，常規場景保持 off。我們建議通過 API易 apiyi.com 的統一接口先做 A/B 測試，再決定是否長期開啓。

Q6：gpt-image-2 接入官方 API 時遇到 403 內容審覈怎麼辦？

先嚐試在請求里加 moderation: "low" 降低敏感度。如果仍被攔截，說明 prompt 觸發了核心安全策略（涉及暴力、未成年人不當內容、知名人物肖像等），需要重寫 prompt。注意：moderation: "low" 不是關閉審覈，只是放寬，仍會攔截高危內容。

Q7：gpt-image-2 接入官方 API 的 base_url 寫錯會怎樣？

如果寫成 https://api.apiyi.com（少了 /v1），SDK 會拼成 api.apiyi.com/images/generations 導致 404。正確寫法是 https://api.apiyi.com/v1。Python 用 base_url，Node.js 用 baseURL（駝峯），別搞錯大小寫。

Q8：gpt-image-2 接入官方 API 多圖融合的最佳實踐是什麼？

最多 16 張參考圖，prompt 裏用「圖1/圖2」指代。關鍵技巧：

  1. 第一張參考圖通常作爲「主體」，模型會優先保留其結構
  2. 複雜指令可分步：先寫「以圖1爲主體」，再寫「融合圖2 的色調」
  3. 多圖編輯成本是文生圖的 1.5-2 倍，預算敏感場景慎用
  4. 建議先用 2-3 張圖跑通邏輯，再擴展到更多參考圖

總結：gpt-image-2 接入官方 API 的完整路徑回顧

走完本文 9 個章節，你應該已經掌握了 gpt-image-2 接入官方 API 的完整工程方法：

  1. ✅ 準備工作 —— SDK 升級到最新、超時設到 ≥ 360 秒
  2. ✅ base_url 配置 —— 替換爲 https://api.apiyi.com/v1，其他代碼與官方一致
  3. ✅ 文生圖調用 —— Python/Node.js/cURL 三語言模板
  4. ✅ 參數詳解 —— size 8 種預設 + 自定義、quality 三檔、output_format 三選
  5. ✅ 圖片編輯 —— 最多 16 張參考圖、prompt 用「圖1/圖2」指代
  6. ✅ Inpainting 重繪 —— mask alpha 通道，透明區域重繪
  7. ✅ 錯誤處理 —— 400/401/403/429/5xx 完整應對方案
  8. ✅ 生產實踐 —— 指數退避、併發控制、成本預估、可觀測性

最後給一個落地建議：先用 low 畫質 + 1024×1024 跑通一次 hello world，再逐步加複雜度。這樣能快速發現 SDK 版本、超時、API Key 等基礎問題，避免一上來就在 high + 4K 的長尾請求裏浪費調試時間。

如果你的團隊正準備評估 gpt-image-2 接入方案、或者已經在寫第一版代碼遇到參數報錯、超時等問題，建議直接通過 API易 apiyi.com 申請測試 Key 跑一遍本文的代碼模板。所有示例都基於官方 SDK + APIYI 官轉通道（字段 100% 一致），通用性極高，能直接複用到你自己的項目。

參考資料

  1. OpenAI gpt-image-2 模型文檔：模型能力、參數、定價權威說明

    • 鏈接: developers.openai.com/api/docs/models/gpt-image-2
    • 說明: 包含 4K 渲染、字符級文字、推理整合等核心特性

  2. OpenAI Image Generation 指南：文生圖、編輯、inpainting 完整工作流

    • 鏈接: developers.openai.com/api/docs/guides/image-generation
    • 說明: 涵蓋 size/quality/format 全部參數詳解

  3. OpenAI Create Image API Reference：/v1/images/generations 端點完整字段

    • 鏈接: developers.openai.com/api/reference/resources/images/methods/generate
    • 說明: 請求/響應字段權威參考

  4. APIYI 官方接入文檔：gpt-image-2 中文版完整接入指南

    • 鏈接: docs.apiyi.com/api-capabilities/gpt-image-2/overview
    • 說明: 含 cURL/Python/Node.js 示例和錯誤碼處理

  5. OpenAI Cookbook · Rate Limits：429 錯誤的指數退避方案

    • 鏈接: developers.openai.com/cookbook/examples/how_to_handle_rate_limits
    • 說明: 官方推薦的限流處理代碼模板

作者: APIYI 技術團隊
發佈日期: 2026 年 4 月 27 日
關鍵詞: gpt-image-2 接入官方 API、base_url、文生圖、圖片編輯、inpainting、APIYI、OpenAI SDK

發佈留言