> ## Documentation Index
> Fetch the complete documentation index at: https://docs.toapis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# gpt-image-2.5-flare 图像生成

> 使用 gpt-image-2.5-flare 生成图像, 支持参考图, 图像质量固定为 high

<Note>
  中国大陆用户请使用 `https://toapis.cn` 作为 Base URL, 替换示例中的 `https://toapis.com`.
</Note>

`gpt-image-2.5-flare` 使用与 `gpt-image-2` 相同的异步图像生成接口, 支持文生图和参考图生成. 图像质量固定为 `high`, 无需设置 `quality` 参数.

## 请求参数

<ParamField header="Authorization" type="string" required>
  使用 `Bearer YOUR_API_KEY` 认证. 可在 [API Key 管理页面](https://toapis.com/console/token) 获取密钥.
</ParamField>

<ParamField body="model" type="string" default="gpt-image-2.5-flare" required>
  模型名称, 使用 `gpt-image-2.5-flare`.
</ParamField>

<ParamField body="prompt" type="string" required>
  描述需要生成的图像. 参考图生成时, 描述需要保留和修改的内容.
</ParamField>

<ParamField body="quality" type="string" default="high">
  图像质量固定为 `high`, 可省略此参数. 传入其他字符串值时会被忽略, 统一使用 `high`.
</ParamField>

<ParamField body="size" type="string" default="1:1">
  输出宽高比. 当前支持 `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `5:4`, `4:5`, `16:9`, `9:16`, `21:9`.

  也可使用 `aspect_ratio` 字段. 同时填写时, `aspect_ratio` 优先.
</ParamField>

<ParamField body="resolution" type="string" default="1K">
  输出分辨率档位, 支持 `1K`, `2K`, `4K`, 兼容小写形式.

  也可使用 `image_size` 字段. 同时填写时, `image_size` 优先.
</ParamField>

<ParamField body="n" type="integer" default={1}>
  沿用 `gpt-image-2` 的数量参数. 推荐每次请求使用 `1`.
</ParamField>

<ParamField body="reference_images" type="string[]">
  参考图 URL 列表, 不传时使用文生图. Playground 最多选择 6 张参考图.

  兼容 `image_urls` 字段. 不支持直接传入 base64; 本地图片请先通过 [上传图片接口](../../uploads/images) 获取 URL.
</ParamField>

<ParamField body="background" type="string">
  可选背景参数. 使用 `transparent` 请求透明背景; 普通生成省略此字段.
</ParamField>

<ParamField body="response_format" type="string" default="url">
  使用 `url`. 接口先返回任务 ID, 图片 URL 在任务完成后通过查询接口获取.
</ParamField>

## 查询任务

提交成功后保存响应中的 `id`, 使用 [查询任务接口](../../tasks/image-status) 轮询:

```bash theme={null}
curl --request GET \
  --url https://toapis.com/v1/images/generations/TASK_ID \
  --header 'Authorization: Bearer YOUR_API_KEY'
```

任务可能经过 `pending`, `queued`, `in_progress`, 最终变为 `completed` 或 `failed`. 成功后从 `result.data` 读取图片 URL; 失败时读取 `error`.

## Playground

在 Playground 选择 `gpt-image-2.5-flare`, 可设置比例和分辨率, 添加参考图后可提交图生图请求. 质量固定为 `high`, Playground 不展示质量选项.

<RequestExample>
  ```bash 文生图 theme={null}
  curl --request POST \
    --url https://toapis.com/v1/images/generations \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "gpt-image-2.5-flare",
      "prompt": "生成一张未来城市夜景海报, 霓虹灯, 电影感构图",
      "size": "16:9",
      "resolution": "2K",
      "n": 1
    }'
  ```

  ```bash 参考图生成 theme={null}
  curl --request POST \
    --url https://toapis.com/v1/images/generations \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "model": "gpt-image-2.5-flare",
      "prompt": "保留主体结构, 将画面改成赛博朋克风格",
      "size": "1:1",
      "resolution": "4K",
      "reference_images": ["https://example.com/reference.png"],
      "n": 1
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "task_img_example",
    "object": "generation.task",
    "model": "gpt-image-2.5-flare",
    "status": "pending",
    "progress": 0,
    "created_at": 1703884800,
    "metadata": {}
  }
  ```
</ResponseExample>