创建图像(文生图)使用文档

1. 文档概述

本文档用于规范 /v1/images/generations AI 图像生成接口的调用方式、参数定义、响应规则及异常处理方案。该接口支持通过文本提示词（Text Prompt）智能生成高清图像，可自定义图像尺寸、生成数量、风格、清晰度等参数，适用于AI绘画、素材生成、创意配图等业务场景。

本接口为 HTTP 通用接口，支持跨端调用，兼容后端服务、前端程序、脚本工具等各类调用客户端。

2. 接口基础信息

项目	内容
接口地址	`/v1/images/generations`
请求方式	POST
数据格式	Request：JSON；Response：JSON
接口鉴权	需携带 Token / API Key（请求头校验）
接口超时	120s
适用场景	文本生成图像、AI创意绘画、批量素材生成

3. 请求头（Request Headers）

所有请求必须携带以下请求头，否则接口返回 401 鉴权失败。

参数名	必填	类型	说明
Authorization	是	String	接口凭证，格式：`Bearer \{API\_KEY\}`
Content-Type	是	String	固定值：`application/json`

4. 请求参数（Request Body）

接口通过 JSON 格式传递请求参数，支持基础生成、画质、风格、高级调控等参数，具体定义如下：

参数名	必填	类型	默认值	取值范围/说明
model	是	String	无	用于图像生成的模型。实际生成图片的模型都是 gpt-image-2
prompt	是	String	无	正向提示词，描述需要生成的图像内容、风格、构图、画质等，支持中英文，最大长度为 32000 个字符
n	否	Integer	1	单次生成图像数量，仅支持 1
size	是	String	1024x1024	图像分辨率，支持最高 (4096 \times 4096)（4K）级别的标准图像输出画幅宽高比：支持从 3:1（超宽大图）到 1:3（超长竖图）之间的全比例覆盖
style	否	String	default	图像风格，可选：default（通用）、anime（动漫）、realistic（写实）、cartoon（卡通）、oil（油画）、watercolor（水彩）
quality	否	String	standard	画质等级，standard（标准）、hd（高清）、ultra（超高清）

特别说明
根据size参数会自动判断计费模型 ,

最大边长 ≤ 1536：自动切换为 1K 模型（gpt-image-2-1k）

1536 ＜最大边长 ≤ 3072：自动切换为 2K 模型（gpt-image-2-2k）

边长＞3072 或 size 参数不存在 / 解析失败：自动使用 4K 模型（gpt-image-2-4k）

关于使用类似cherry Studio 这种客户端调用时 size 参数不存在会默认使用 4K模型计费

无论是否触发模型切换，最终都会强制重写请求体 data\.model 字段，确保后端实际生效的模型为自动匹配的最优模型，杜绝自定义模型参数无效问题。

5. 响应参数（Response Body）

接口请求成功后，返回标准 JSON 数据，包含生成图像信息、请求耗时、种子等核心数据。

参数名	类型	说明
created	Long	图像生成时间戳（秒级）
data	Array	图像生成结果数组，数组长度对应请求参数 n，存储单张图像生成数据
data[].b64_json	String	生成图像的 Base64 编码字符串，可直接解码生成图片文件
data[].revised_prompt	String	模型优化重绘后的标准化提示词，为模型实际生成图像所使用的prompt，可用于效果溯源和复现
background	String	图像背景类型，opaque（不透明）/transparent（透明）
output_format	String	输出图片格式，默认 png，支持 jpg、webp
quality	String	本次生成画质等级，对应请求参数 quality 配置
size	String	本次生成图像分辨率，对应请求参数 size 配置
usage	Object	接口调用 Token 消耗统计，用于计费、用量统计
usage.input_tokens	Integer	输入总 Token 数（提示词文本消耗）
usage.input_tokens_details	Object	输入 Token 细分统计
usage.input_tokens_details.image_tokens	Integer	输入图像 Token 数，文生图场景默认为0
usage.input_tokens_details.text_tokens	Integer	输入文本提示词 Token 数
usage.output_tokens	Integer	输出总 Token 数（图像生成消耗）
usage.output_tokens_details	Object	输出 Token 细分统计
usage.output_tokens_details.image_tokens	Integer	输出图像 Token 消耗数
usage.output_tokens_details.text_tokens	Integer	输出文本 Token 数，文生图场景默认为0
usage.total_tokens	Integer	本次请求总消耗 Token 数

6. 完整请求示例

6.1 CURL 请求示例

6.2 成功响应示例

{
    "created": 1779560803,
    "data": [
        {
            "b64_json": "……………………",
            "revised_prompt": "A small tiger wearing a scarf…………"
        }
    ],
    "background": "opaque",
    "output_format": "png",
    "quality": "high",
    "size": "1024x1024",
    "usage": {
        "input_tokens": 48,
        "input_tokens_details": {
            "image_tokens": 0,
            "text_tokens": 48
        },
        "output_tokens": 3122,
        "output_tokens_details": {
            "image_tokens": 3122,
            "text_tokens": 0
        },
        "total_tokens": 3170
    }
}

7. 调用注意事项

参数规范：分辨率、风格、画质参数需严格按照约定取值，非法参数会直接返回 400 参数错误。

提示词优化：正向提示词建议精准描述主体、场景、光影、画质，反向提示词常规配置模糊、畸形、水印等负面词汇，大幅提升生成质量。

合规要求：禁止生成色情、暴力、违法、侵权类图像，违规调用将封禁接口权限。

创建图像(文生图)使用文档

1. 文档概述#

2. 接口基础信息#

3. 请求头（Request Headers）#

4. 请求参数（Request Body）#

5. 响应参数（Response Body）#

6. 完整请求示例#

6.1 CURL 请求示例#

6.2 成功响应示例#

7. 调用注意事项#