# 生成图片

`POST /v1/images/generations`

OpenAI Images 兼容的同步图片生成接口。新接入优先使用 `POST /v1/images/generations/jobs` 创建异步任务；同步接口主要用于短耗时请求、兼容旧客户端或必须直接等待结果的场景。

## GPT Image 2 同步兼容
`gpt-image-2`、`gpt-image-2-2K` 和 `gpt-image-2-4K` 均支持本同步接口。服务会在内部创建异步任务并等待完成；客户端超时较短、批量并发或需要可靠轮询时，请改用 `POST /v1/images/generations/jobs`。

## 请求格式
使用 `application/json`。基础请求包含 `model` 和 `prompt`。

## 推荐方式
图片生成可能耗时较长。页面、移动端、Serverless、队列 worker、批量并发和参考图改图场景，推荐调用 `/v1/images/generations/jobs`，保存返回的任务 ID，再轮询 `/v1/images/generations/jobs/{job_id}` 查询结果。

## 典型用法
- 文生图：传 prompt、尺寸、质量和输出格式。
- 透明素材：`background=transparent`，输出格式选择 PNG。
- 网络 URL 参考图改图：将公网图片地址放入 JSON 的 `image` 字段。
- 多图参考：`image` 传 URL 数组，顺序按页面含义或用户排序保持一致。

## URL 参考图推荐
需要用 OSS/CDN 图片 URL 做参考图创作、换装、合成或改图时，推荐使用异步任务接口 `/v1/images/generations/jobs`。同步接口也兼容同样的 JSON `image` 数组，但客户端需要一直等待结果。大图建议先通过 OSS/CDN 图片处理 resize 到合适分辨率后提交。

## OpenAI 兼容格式
图片模型使用 `model`、`prompt`、`size`、`quality`、`format`、`image` 等字段提交。部分模型不支持 `n` 批量生成；需要多张结果时可发起多次异步任务。

## 读取结果
响应可能返回图片 URL 或 `b64_json`。接入时按所用接口分别解析；需要长期访问或统一域名时，再保存到对象存储。

## 错误定位
1. 长时间等待或客户端超时：改用 `/v1/images/generations/jobs` 异步任务。
2. 参考图无法读取：确认 URL 能公网访问，且图片未过期。
3. 尺寸报错：检查宽高、像素总量和模型尺寸范围。
4. 没有图片字段：保留完整响应，再按真实返回结构解析。

Tags: 图片生成