# img 2.5 图像生成 API Documentation

> img 2.5 文生图 / 图生图。传入 prompt 立即返回 task_id，完成后回调 notify。按分辨率计费：1K 25点、2K 40点、4K 60点。默认 Flare（更快），可选 Sunburst（更精细）。

## Overview

This document describes how to call the **img 2.5 图像生成** API.

- **Model / path slug**: `image/image25`
- **Task type**: `sync` (`sync` = synchronous, `async` = create task then poll / callback)
- **HTML docs**: `/doc/44`

## Authentication

All API requests require your platform API key as the query parameter `key`:

```
?key=YOUR_API_KEY
```

Get API Key:
1. Sign in to the console
2. Open [API Key Management](/user/key) and create or copy your key
3. Append `key=YOUR_API_KEY` to the request URL (or pass it in form/JSON when the endpoint accepts it)

---

## API Information

- **URL**: `GET|POST https://apis.xiaobao.ink/api/image/image25`
- **Content-Type**: `application/json` (request body commonly `application/json` or `application/x-www-form-urlencoded` for POST)
- **HTTP Method**: `GET / POST`
- **Note**: This endpoint accepts both GET query parameters and POST form/JSON body.

### Request Parameters

| Parameter | Required | Description |
|-----------|----------|-------------|
| `prompt` | Yes | 图片描述，最多20000字符 |
| `imageSize` | Yes | 分辨率 1K/2K/4K，默认1K。1K=25点，2K=40点，4K=60点 |
| `aspectRatio` | No | 可选，auto/1:1/3:2/2:3/16:9/9:16 等，默认auto |
| `urls` | No | 可选，参考图URL，逗号分隔或JSON数组，最多16张 |
| `background` | No | 可选，transparent/opaque/auto，默认opaque |
| `model` | No | 可选，flare（默认，更快）或 sunburst（更精细） |
| `notify` | Yes | 任务完成回调地址 |

> **Note**: `key` (API key) is required for authenticated calls even if omitted from the parameter list above.

### Request Example

```
/api/image/image25?key=你的key&prompt=一只橘猫坐在窗边晒太阳&imageSize=1K&aspectRatio=1:1&notify=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

```json
{
    "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 | 服务器内部错误 |

## Usage Flow

1. Obtain your API Key from the console
2. Call the endpoint with `key` and required parameters
3. Parse the JSON (or binary) response according to the examples above

---

_Generated for AI / LLM consumption. Source of truth: `api_list` (same as HTML `/doc/{id}`)._