> ## Documentation Index > Fetch the complete documentation index at: https://docs.poyo.ai/llms.txt > Use this file to discover all available pages before exploring further. # GPT Image 2.5 Flare > GPT Image 2.5 Flare API 根据提示词生成一张图像，或编辑最多 16 张参考图。它是 GPT Image 2.5 中速度更快的选项，支持蒙版、透明背景以及 1K 到 4K 输出。 > [!TIP] > > 1. 提交后会返回 `task_id`。如果提供了 `callback_url`，当任务状态变为 `finished` 或 `failed` 时，系统会向 `callback_url` 发送 POST 请求。 > 2. 无论是否提供 `callback_url`，都可以通过统一的[查询任务状态](https://docs.poyo.ai/zh/api-manual/task-management/status.md)接口获取结果。 使用 `gpt-image-2.5-flare` 根据提示词生成一张图像，或编辑最多 16 张参考图。传入非空的 `image_urls` 数组会自动进入编辑模式；省略该字段或传入空数组则为文生图。 ## 模型 * **gpt-image-2.5-flare** — GPT Image 2.5 Flare ## 必填参数 * `prompt` 必填，最多支持 32,000 个字符。 ## 可选参数 * `quality`：`low`、`medium`、`high`（默认）、`xhigh` 或 `max`。 * `background`：`auto`（默认）、`transparent` 或 `opaque`。 * `output_format`：`png`（默认）、`jpeg` 或 `webp`。透明背景需要 PNG 或 WebP。 * `mask_url`：可选的 HTTP(S) 蒙版图像 URL，用于标识要编辑的区域；需要非空的 `image_urls`。 * 参考图必须使用 HTTP(S) URL。每次请求输出一张图像。 ## 尺寸 * `size` 默认为 `1:1`。支持的比例：`1:1`、`2:3`、`3:2`、`4:3`、`3:4`、`4:5`、`5:4`、`16:9`、`9:16`、`21:9`。 * `resolution` 支持 `1K`（默认）、`2K` 和 `4K`。省略 size 时，使用所选档位的正方形。 * 显式指定 `size=auto` 仅可与 `1K` 搭配，由模型决定图像尺寸。`2K` 或 `4K` 请选择比例或自定义尺寸。 * 使用宽高比时，实际像素尺寸可能因模型和每次生成而不同。请以返回图像为准确认精确尺寸；需要精确像素时请使用自定义尺寸。 * 自定义 `WIDTHxHEIGHT` 尺寸需要 `2K` 或 `4K`。两个维度都必须能被 16 整除，最长边不得超过 3840，宽高比不得超过 3:1，总像素数必须在 655,360 到 8,294,400 之间。边长为 3840 像素时需要 `4K`。 ## 示例 ### 文生图 ```json theme={"dark"} { "model": "gpt-image-2.5-flare", "input": { "prompt": "A premium product photo of a silver espresso machine in a bright studio", "size": "16:9", "resolution": "2K", "quality": "medium" } } ``` ### 图像编辑 ```json theme={"dark"} { "model": "gpt-image-2.5-flare", "input": { "prompt": "Keep the product and replace the background with a warm modern studio", "image_urls": [ "https://example.com/product.png" ], "size": "1:1", "quality": "high" } } ``` ### 蒙版编辑 ```json theme={"dark"} { "model": "gpt-image-2.5-flare", "input": { "prompt": "Replace only the masked area with a small vase of flowers", "image_urls": [ "https://example.com/room.png" ], "mask_url": "https://example.com/mask.png", "size": "auto" } } ``` ### 透明背景 ```json theme={"dark"} { "model": "gpt-image-2.5-flare", "input": { "prompt": "A clean cutout of a small silver robot", "background": "transparent", "output_format": "webp", "size": "1:1", "resolution": "4K", "quality": "xhigh" } } ``` ## OpenAPI ````yaml zh/api-manual/image-series/gpt-image-2-5-flare.json POST /api/generate/submit openapi: 3.0.0 info: title: PoYo AI - GPT Image 2.5 Flare API description: >- GPT Image 2.5 Flare API 根据提示词生成一张图像，或编辑最多 16 张参考图像。它是 GPT Image 2.5 中速度更快的选项，支持蒙版、透明背景以及 1K 到 4K 输出。 version: 1.0.0 servers: - url: https://api.poyo.ai description: 生产环境 security: - BearerAuth: [] paths: /api/generate/submit: post: tags: - GPT Image 2.5 Flare summary: 提交 GPT Image 2.5 Flare 任务 description: GPT Image 2.5 Flare 单图生成与参考图编辑，支持背景、格式和蒙版控制。 operationId: submitGPTImage25FlareTask requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubmitRequest' examples: text-to-image: summary: 文生图 value: model: gpt-image-2.5-flare input: prompt: >- A premium product photo of a silver espresso machine in a bright studio size: '16:9' resolution: 2K quality: medium image-edit: summary: 图像编辑 value: model: gpt-image-2.5-flare input: prompt: >- Keep the product and replace the background with a warm modern studio image_urls: - https://example.com/product.png size: '1:1' quality: high mask-edit: summary: 蒙版编辑 value: model: gpt-image-2.5-flare input: prompt: Replace only the masked area with a small vase of flowers image_urls: - https://example.com/room.png mask_url: https://example.com/mask.png size: auto transparent-background: summary: 透明背景 value: model: gpt-image-2.5-flare input: prompt: A clean cutout of a small silver robot background: transparent output_format: webp size: '1:1' resolution: 4K quality: xhigh responses: '200': description: 任务提交成功 content: application/json: schema: $ref: '#/components/schemas/SubmitResponse' '400': description: 请求参数无效 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: 未授权：API Key 无效 content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: SubmitRequest: type: object required: - model - input additionalProperties: false properties: model: type: string enum: - gpt-image-2.5-flare description: GPT Image 2.5 Flare 模型标识。 callback_url: type: string format: uri description: 可选的 Webhook URL，用于任务完成或失败时的通知。 input: type: object additionalProperties: false required: - prompt description: 生成一张图像；当 image_urls 非空时编辑参考图像。 properties: prompt: type: string minLength: 1 maxLength: 32000 description: 描述图像或所需编辑的提示词。必须包含非空白文本。 image_urls: type: array maxItems: 16 items: type: string format: uri description: >- 可选的参考图像 URL。传入非空数组时为编辑模式；省略或传入空数组时为文生图模式。必须是可公开访问的 HTTP 或 HTTPS URL。 size: type: string default: '1:1' description: >- 宽高比或自定义 WIDTHxHEIGHT。支持的值：auto、1:1、2:3、3:2、4:3、3:4、4:5、5:4、16:9、9:16、21:9 或 WIDTHxHEIGHT。默认 1:1。auto 仅在 1K 下可用。自定义尺寸要求 resolution 为 2K 或 4K，宽高均能被 16 整除，最长边不超过 3840，宽高比不超过 3:1，总像素数在 655360–8294400 之间。自定义尺寸某条边为 3840 像素时需使用 4K。 example: '1:1' resolution: type: string enum: - 1K - 2K - 4K default: 1K description: >- 输出分辨率档位。使用宽高比时，实际像素尺寸可能因模型和生成结果而异，请以返回图像的实际尺寸为准。自定义 WIDTHxHEIGHT 则指定精确尺寸。 quality: type: string enum: - low - medium - high - xhigh - max default: high description: 输出质量等级。 background: type: string enum: - auto - transparent - opaque default: auto description: 背景模式。transparent 要求输出格式为 png 或 webp。 output_format: type: string enum: - png - jpeg - webp default: png description: 输出图像格式。 mask_url: type: string format: uri description: >- 可选的蒙版图像 URL，用于标识要编辑的区域。要求 image_urls 非空。必须是可公开访问的 HTTP 或 HTTPS URL。 SubmitResponse: type: object required: - code - data properties: code: type: integer example: 200 description: >- 业务状态码。`200` 表示成功，其他值都表示请求失败。请务必检查这个字段：部分参数校验错误会以 HTTP 200 返回，响应体里的 `code` 为 `400`。 - `200`：成功 - `400`：请求参数无效 - `401`：API Key 缺失或无效 - `402`：积分不足 - `403`：没有权限 - `404`：资源不存在 - `408`：请求超时 - `429`：请求频率超限 - `500`：服务器内部错误 - `502`：上游服务错误 - `503`：服务暂不可用 详见[错误码](/zh/api-manual/error-codes)。 enum: - 200 - 400 - 401 - 402 - 403 - 404 - 408 - 429 - 500 - 502 - 503 data: type: object required: - task_id - status - created_time properties: task_id: type: string example: task-unified-1786751400-abcd1234 description: 任务唯一标识，用于查询任务状态 status: type: string enum: - not_started - running - finished - failed example: not_started description: >- 任务状态。提交后立即返回时始终为 `not_started`。后续状态请通过[查询任务状态](/zh/api-manual/task-management/status)接口或 `callback_url` 获取。 - `not_started`：排队中，等待处理 - `running`：生成中 - `finished`：已完成，结果在 `files` 或 `output` 中 - `failed`：失败，详情见 `error_message` created_time: type: string format: date-time example: '2026-09-09T10:30:00' description: 任务创建时间，ISO 8601 格式 ErrorResponse: type: object required: - code - error properties: code: type: integer example: 400 enum: - 200 - 400 - 401 - 402 - 403 - 404 - 408 - 429 - 500 - 502 - 503 description: >- 业务状态码。`200` 表示成功，其他值都表示请求失败。请务必检查这个字段：部分参数校验错误会以 HTTP 200 返回，响应体里的 `code` 为 `400`。 - `200`：成功 - `400`：请求参数无效 - `401`：API Key 缺失或无效 - `402`：积分不足 - `403`：没有权限 - `404`：资源不存在 - `408`：请求超时 - `429`：请求频率超限 - `500`：服务器内部错误 - `502`：上游服务错误 - `503`：服务暂不可用 详见[错误码](/zh/api-manual/error-codes)。 error: type: object required: - message - type properties: message: type: string example: Invalid request parameters type: type: string example: invalid_request_error securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: API Key description: >- 所有 API 接口都需要 Bearer Token 认证。 创建 API Key：登录 PoYo，进入 **仪表盘 → API 密钥**（[poyo.ai/zh/dashboard/api-key](https://poyo.ai/zh/dashboard/api-key)），点击创建 Key。 在请求头中添加： ``` Authorization: Bearer YOUR_API_KEY ``` ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.