文生图 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": "赛博朋克城市雨夜，霓虹招牌特写，电影画幅"
}
'

import requests

url = "https://api.apiyi.com/v1/images/generations"

payload = {
    "model": "gpt-image-2",
    "prompt": "赛博朋克城市雨夜，霓虹招牌特写，电影画幅"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({model: 'gpt-image-2', prompt: '赛博朋克城市雨夜，霓虹招牌特写，电影画幅'})
};

fetch('https://api.apiyi.com/v1/images/generations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.apiyi.com/v1/images/generations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'model' => 'gpt-image-2',
    'prompt' => '赛博朋克城市雨夜，霓虹招牌特写，电影画幅'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.apiyi.com/v1/images/generations"

	payload := strings.NewReader("{\n  \"model\": \"gpt-image-2\",\n  \"prompt\": \"赛博朋克城市雨夜，霓虹招牌特写，电影画幅\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.apiyi.com/v1/images/generations")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"gpt-image-2\",\n  \"prompt\": \"赛博朋克城市雨夜，霓虹招牌特写，电影画幅\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.apiyi.com/v1/images/generations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"gpt-image-2\",\n  \"prompt\": \"赛博朋克城市雨夜，霓虹招牌特写，电影画幅\"\n}"

response = http.request(request)
puts response.read_body

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，缩小响应体积。

图片 API 全部为同步调用：没有异步任务 ID，客户端断开连接结果即丢失、但请求仍会计费。请为本模型设置足够大的 timeout，详见 图片 API 调用须知与最佳实践。

⚠️ 不支持的参数

• 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

quality 不要传旧版 DALL·E 的 standard / hd。 只接受 low / medium / high / auto 四个官方枚举值。旧值在不同后端渠道下行为不一致：有时直接 400 报错（invalid_value），有时被静默忽略、按 auto 档跑出结果（费用不可控）。请始终显式传四个官方值之一。

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

​

响应格式

{
    "created": 1776832476,
    "data": [
        {
            "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
        }
    ],
    "usage": {
        "input_tokens": 17,
        "input_tokens_details": {
            "image_tokens": 0,
            "text_tokens": 17
        },
        "output_tokens": 196,
        "output_tokens_details": {
            "image_tokens": 196,
            "text_tokens": 0
        },
        "total_tokens": 213
    }
}

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

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

gpt-image-2-all / gpt-image-2-vip 实测（2026-07）同样返回纯 base64，但其历史版本曾带前缀——跨模型复用代码时建议统一做 startsWith('data:') 检测。

usage 字段反映本次实际计费的 token 数，input_tokens_details / output_tokens_details 把文本、图片两段 token 拆开列出（纯文生图时 image_tokens 恒为 0）。详细的字段说明和自行核算公式见 概览页「如何查看每次调用的真实 token 数」。

授权

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