文生图 API 参考

gpt-image-2 文生图 API 参考与在线调试 — 任意合法尺寸（含 4K），按 token 计费

POST /v1/images/generations

文生图：根据文本描述生成图片

cURL

curl --request POST \
  --url https://api.apiyi.com/v1/images/generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "gpt-image-2",
  "prompt": "赛博朋克城市雨夜，霓虹招牌特写，电影画幅"
}
'

200

{
  "created": 1776832476,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ],
  "usage": {
    "input_tokens": 42,
    "output_tokens": 6240,
    "total_tokens": 6282
  }
}

右侧的交互式 Playground 支持直接在线调试。请在 Authorization 中填入你的 API Key（格式：Bearer sk-xxx），输入 prompt、选择 size / quality 后一键发送即可。

场景说明：本页用于「文本生成图片」。只需输入提示词即可，无需上传任何图片。如需根据现有图片做编辑、多图融合或 mask 局部重绘，请使用 图片编辑接口。

🖥️ 浏览器 Playground 限制（重要）

本接口的响应包含纯 base64 字符串（数 MB 量级）。受浏览器渲染限制，右侧 Playground 在收到响应后可能弹出 请求时发生错误: unable to complete request ——实际请求已经成功，只是浏览器无法把这么长的 base64 显示出来。

推荐做法（小白零踩坑）：

• 直接复制下方”代码示例”中的 Python / Node.js / cURL 到本地运行，代码会自动 base64.b64decode 并把图片保存为本地文件。
• 如要在浏览器里试 Playground，把 size 设为最小档（如 1024x1024）、quality 改为 low，缩小响应体积。

⚠️ 不支持的参数

• input_fidelity —— gpt-image-2 强制启用高保真，传了会 400 报错（从 1.5 迁移时直接删掉这一行）
• background: "transparent" —— 暂不支持透明背景，请改用 opaque 或自行后处理抠透明

超过 2560×1440 的输出仍属实验性，生产环境建议优先用预设尺寸：2048x1152 / 2048x2048 / 3840x2160。

​

代码示例

​

Python（OpenAI SDK 直连）

from openai import OpenAI
import base64

client = OpenAI(
    api_key="sk-your-api-key",
    base_url="https://api.apiyi.com/v1"
)

resp = client.images.generate(
    model="gpt-image-2",
    prompt="赛博朋克城市雨夜，霓虹招牌特写，电影画幅",
    size="2048x1152",
    quality="high",
    output_format="jpeg",
    output_compression=85
)

# b64_json 是纯 base64（无前缀），需要自己 decode 写文件
with open("out.jpg", "wb") as f:
    f.write(base64.b64decode(resp.data[0].b64_json))

​

Python（原生 requests）

import requests
import base64

API_KEY = "sk-your-api-key"

response = requests.post(
    "https://api.apiyi.com/v1/images/generations",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "model": "gpt-image-2",
        "prompt": "横版 2K 海边日落老灯塔，电影画幅",
        "size": "2048x1152",
        "quality": "high"
    },
    timeout=360  # high + 2K/4K 实测可能 3-5 分钟，按 120s 配会大量误超时
).json()

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

​

cURL

curl -X POST "https://api.apiyi.com/v1/images/generations" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只戴墨镜的橘猫坐在海边吧台，电影画幅",
    "size": "2048x1152",
    "quality": "high",
    "output_format": "jpeg",
    "output_compression": 85
  }'

​

Node.js（原生 fetch）

import fs from 'node:fs';

const resp = await fetch('https://api.apiyi.com/v1/images/generations', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer sk-your-api-key'
    },
    body: JSON.stringify({
        model: 'gpt-image-2',
        prompt: '极简线条风格的猫咪 LOGO',
        size: '1024x1024',
        quality: 'medium'
    })
});

const { data } = await resp.json();
// b64_json 是纯 base64（无前缀），需自己 decode
fs.writeFileSync('logo.png', Buffer.from(data[0].b64_json, 'base64'));

​

浏览器 JavaScript（直接渲染）

const resp = await fetch('https://api.apiyi.com/v1/images/generations', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer sk-your-api-key'
    },
    body: JSON.stringify({
        model: 'gpt-image-2',
        prompt: '水彩风的北欧极光',
        size: '1536x1024',
        quality: 'high'
    })
});

const { data } = await resp.json();
// 浏览器渲染需自己拼 data URL 前缀
document.getElementById('img').src = `data:image/png;base64,${data[0].b64_json}`;

​

参数说明速查

参数	类型	必填	默认	说明
model	string	是	—	固定填 gpt-image-2
prompt	string	是	—	提示词，支持中英文
size	string	否	auto	输出尺寸，预设或满足约束的自定义尺寸
quality	string	否	auto	low / medium / high / auto
output_format	string	否	png	png / jpeg / webp
output_compression	int	否	—	0–100，仅 jpeg / webp 生效
background	string	否	auto	opaque / auto（不支持 transparent）
moderation	string	否	auto	auto / low（低强度审核）
n	int	否	1	仅支持 1

详细的参数约束、可选值、示例请查看右侧 Playground 中的字段说明，所有 enum 字段均支持下拉选择。

​

响应格式

{
    "created": 1776832476,
    "data": [
        {
            "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
        }
    ],
    "usage": {
        "input_tokens": 42,
        "output_tokens": 6240,
        "total_tokens": 6282
    }
}

⚠️ b64_json 字段是纯 base64，不含 data:image/...;base64, 前缀。客户端需要：

• 写文件：base64.b64decode(b64_str) → 写入磁盘
• 浏览器渲染：自行拼前缀 data:image/png;base64, + b64

这与 gpt-image-2-all 的”已带前缀”行为不同，请留意。

usage 字段反映本次实际计费的 token 数。按”输入 text + 输入 image + 输出 image”三段之和计费，可结合 概览页定价表 估算成本。

授权

Authorization · string · header · 必填

在 API易控制台获取的 API Key

请求体

application/json

model · enum<string> · 默认值: gpt-image-2 · 必填

模型名称，固定为 gpt-image-2

可用选项: gpt-image-2

prompt · string · 必填

提示词，支持中英文。建议把场景描述放在最前面

示例:

"赛博朋克城市雨夜，霓虹招牌特写，电影画幅"

size · string · 默认值: auto

输出尺寸。预设值：1024x1024 / 1536x1024 / 1024x1536 / 2048x2048 / 2048x1152 / 3840x2160 / 2160x3840。 也可使用任意合法自定义尺寸（满足：最大边 ≤ 3840、两边 16 倍数、比例 ≤ 3:1、总像素 0.65–8.3MP）。

示例:

"2048x1152"

quality · enum<string> · 默认值: auto

画质档位。low（草图/批量）、medium（日常）、high（终稿/精细文字）、auto（默认）

可用选项: auto, low, medium, high

output_format · enum<string> · 默认值: png

输出格式

可用选项: png, jpeg, webp

output_compression · integer

输出压缩率（0–100），仅 jpeg/webp 生效

必填范围: 0 <= x <= 100

示例:

85

background · enum<string> · 默认值: auto

背景模式。auto（默认）或 opaque。不支持 transparent

可用选项: auto, opaque

moderation · enum<string> · 默认值: auto

审核强度。auto（默认）或 low（低强度）

可用选项: auto, low

n · enum<integer> · 默认值: 1

出图数量。本模型仅支持 1

可用选项: 1

响应

200

application/json

成功生成图片

created · integer

Unix 时间戳

示例:

1776832476

data · object[]

生成结果数组（本模型单次返回 1 张）

Show child attributes

usage · object

本次调用 token 用量（用于按 token 计费核算）

Show child attributes