API Reference
GPT Image 2.5 API
Image generation with GPT Image 2.5. Prompt and reference-image fields follow this page.
Overview
- 提示词生成
- 参考图可选
- JSON 任务结果
Use cases
- 高质量配图
- 设计草稿
- 营销视觉
- Gateway ·
https://xiaoapis.com - Auth · send
key(query or JSON body, as this API specifies) - Response · JSON. Check the business code and the HTTP status, not only HTTP 200
Authentication
Send the platform API key (query parameter key or JSON field key, as this page specifies). Create one in API key management.
REQUEST https://xiaoapis.com/api/image/image25
Content-Type: application/json
{
"key": "YOUR_API_KEY"
}
Request example
/api/image/image25?key=你的key&prompt=一只橘猫坐在窗边晒太阳&imageSize=1K&aspectRatio=1:1¬ify=https://your.domain/callback
Details
接口说明：
基于 OpenAI GPT Image 2.5，支持文生图与图生图（带参考图即图生图）。提交后立即返回 task_id，出图完成后向 notify 推送结果。回调与落库复用 /api/image/callback，失败自动退回点数。
默认模型 Flare（更快，适合日常与批量）；model=sunburst 为更精细的精品档，计费相同。
计费说明：
| 分辨率 imageSize | 扣除点数 | 约合（按 0.01 元/点） |
|---|---|---|
| 1K | 25 点 | 0.25 元 |
| 2K | 40 点 | 0.40 元 |
| 4K | 60 点 | 0.60 元 |
提交成功即按分辨率扣费；任务失败退回。27:16、16:27、9:8、8:9 仅支持 1K。
请求HEADER：
| 名称 | 值 |
|---|---|
| Content-Type | application/x-www-form-urlencoded;charset:utf-8; 或 application/json |
请求参数说明：
| 名称 | 必填 | 类型 | 示例值 | 说明 |
|---|---|---|---|---|
| key | 是 | string | 35kj5jnlj53453kl5j43nj5 | 接口密钥,在控制台->密钥管理查看 |
| prompt | 是 | string | 一只橘猫坐在窗边晒太阳，电影感光线 | 图片描述，最多 20000 字符 |
| notify | 是 | string | https://your.domain/callback | 任务完成回调地址，需公网可访问。兼容 callBackUrl |
| imageSize | 否 | string | 1K | 分辨率：1K / 2K / 4K，默认 1K。兼容 resolution、size（值为 1K/2K/4K 时） |
| aspectRatio | 否 | string | 1:1 | 画幅，默认 auto。支持 auto、1:1、3:2、2:3、4:3、3:4、16:9、9:16、21:9、27:16、16:27、9:8、8:9。兼容 aspect_ratio |
| urls | 否 | string/array | https://example.com/a.jpg | 参考图公网 URL，最多 16 张。逗号分隔、JSON 数组或数组提交均可。传入后走图生图。兼容 input_urls。单张不超过 30MB，格式 JPEG/PNG/WEBP |
| background | 否 | string | opaque | 背景：transparent 透明、opaque 不透明、auto 自动。默认 opaque |
| model | 否 | string | flare | flare（默认，更快）或 sunburst（更精细）。也兼容 gpt-image-2-5-flare / gpt-image-2-5-sunburst |
GET / POST / JSON 均可。本接口只提交任务，出图结果通过 notify 回调，不会在本次响应里返回图片地址。
返回参数说明：
| 名称 | 类型 | 说明 |
|---|---|---|
| code | int | 状态码，200 表示提交成功 |
| msg | string | 状态信息 |
| data | object | 任务信息 |
| data.id | int | 本地任务主键 |
| data.task_id | string | 任务 ID，用于对照回调 |
| data.model | string | 实际使用的模型标识，如 gpt-image-2-5-flare |
| data.image_size | string | 本次分辨率 |
| data.power_cost | number | 本次扣除点数 |
| data.exec_time | float | 上游提交耗时 |
| data.user_ip | string | 客户端 IP |
| exec_time | float | 接口执行耗时 |
| ip | string | 客户端IP |
回调 notify 说明：
任务成功或失败后，以 POST JSON 推送到你传入的 notify。成功时 data.image_url 为可访问的图片地址。
| 名称 | 类型 | 说明 |
|---|---|---|
| code | int | 200 成功，400 失败 |
| msg | string | success 或 任务失败 |
| data.task_id | string | 任务 ID |
| data.image_url | string | 生成图片地址；失败时为空 |
| data.fail_reason | string | 失败原因 |
| data.exec_time | number | 生成耗时（秒） |
Response example
{"code":200,"msg":"任务创建成功","data":{"id":128,"task_id":"task_2f8c1a0b","model":"gpt-image-2-5-flare","image_size":"1K","power_cost":25,"exec_time":0.42,"user_ip":"1.2.3.4"},"exec_time":0.86,"ip":"1.2.3.4"}
Error codes
| 错误码 | 类型 | 说明 |
|---|---|---|
| 403 | int | 没有权限 / 密钥无效 |
| 400 | int | 参数错误、点数不足、画幅与分辨率不匹配，或上游创建失败 |
| 500 | int | 服务器内部错误 |
FAQ
和「AI 图像」接口如何选择？
模型与参数集不同，按效果与价格对照文档选择。
如何传参考图？
使用 urls / input_urls 等字段提交公网图片地址，数量上限见文档。
是否异步？
以该接口文档的任务模型为准（同步或 task 查询）。
商业使用注意？
遵守平台服务条款与内容安全要求，勿生成违规内容。
失败常见原因？
提示词违规、参考图过大/不可达、额度不足。
Related APIs
Full console doc (with the debugger):/doc/44