# GPT Image 2.5 Flare

Canonical page: https://agentsky.dev/models/openai/gpt-image-2.5-flare
JSON record: https://gateway.agentsky.dev/v1/endpoints/openai/gpt-image-2.5-flare

GPT Image 2.5 Flare is a image model from OpenAI, callable through the AgentSky API as openai/gpt-image-2.5-flare and billed per token (Single image generation: 1024x1024 (default): $0.0247 · 1360x768: $0.0247 · 768x1360: $0.0247 · 2048x2048: $0.0297 · 2736x1536: $0.0297 · 1536x2736: $0.0297 · 2880x2880: $0.033 · 3840x2160: $0.033 · 2160x3840: $0.033 · Other requests (example): Text input: $4.675 / 1M tokens · Cached text input: $1.16875 / 1M tokens · Image input: $7.48 / 1M tokens · Cached image input: $1.87 / 1M tokens · Text output: $0 / 1M tokens · Image output: $28.05 / 1M tokens).

Generate images, or provide images for editing and composition. Billing depends on the request and configured pricing route. Consult pricing_routes for eligible flat-price generation; other requests use native token billing with separate text, image and cached input rates. Without streaming, poll the run until COMPLETED; acceptance alone does not indicate completion. With input.stream=true, POST /v1/run returns gateway SSE: image_generation.partial_image previews followed by run.completed containing the final run, or run.failed. This is the gateway run protocol, not the OpenAI Images or Responses API. Streaming currently requires n=1. Reusing an Idempotency-Key replays the saved run without regenerating previews or charging twice. The complete request is limited to 32 MiB; an encoded result or individual SSE event is limited to 27 MiB and a stream to 108 MiB. Large batches or PNG outputs can exceed the result limit; prefer fewer images or JPEG/WebP compression. Interrupted or unverified results remain pending for reconciliation; never resubmit with a new key to recover a known run.

Decode run.output.data[].b64_json after COMPLETED. Token-priced routes report text/image input, cached input and image output token counts. Flat-price routes report no token usage.

## Facts

- **Id:** `openai/gpt-image-2.5-flare`
- **Provider:** OpenAI
- **Kind:** image model
- **Billed per:** token
- **Timeout:** 11 min
- **Max request:** 34 MB
- **Character limit:** prompt up to 32,000

## Call it

`POST https://gateway.agentsky.dev/v1/run` with `{"provider": "openai", "endpoint": "gpt-image-2.5-flare", "input": {…}}` and `Authorization: Bearer $AGENTSKY_API_KEY`.

### Input fields

| Field | Type | Required | Description |
|---|---|---|---|
| `prompt` | string | yes | Describe the image or the requested edit. Max: 32000. |
| `images` | array | no | For editing, 1–16 objects containing image_url (HTTP(S) or image data URL) or b64. Each remote image is at most 50 MiB; inline images and masks together must fit the 32 MiB complete request limit. |
| `mask` | object | no | Optional editing mask with image_url or b64. Must be PNG with alpha and match the first input image dimensions. |
| `n` | integer | no | Number of output images. Default: 1. Min: 1. Max: 10. |
| `size` | string | no | auto or WIDTHxHEIGHT; sides multiples of 16, longest at most 3840, ratio at most 3:1 and 655360–8294400 pixels. Sizes above 2560x1440 are experimental. Default: "auto". |
| `quality` | string | no | Rendering quality; higher settings can consume more output tokens. Allowed: low, medium, high, xhigh, max, auto. Default: "auto". |
| `output_format` | string | no | Generated image encoding. Allowed: png, jpeg, webp. Default: "png". |
| `output_compression` | integer | no | JPEG/WebP compression only. Min: 0. Max: 100. |
| `moderation` | string | no | Content moderation setting. Allowed: auto, low. Default: "auto". |
| `background` | string | no | Editing background; transparent is unsupported. Allowed: auto, opaque. |
| `input_fidelity` | string | no | Editing fidelity is fixed at high. Allowed: high. |
| `response_format` | string | no | Only base64 output is supported. Allowed: b64_json. |
| `stream` | boolean | no | Generation only: return gateway run SSE with validated image previews and a final run.completed or run.failed event. Requires n=1 and no images input. The current supplier rejects streaming edits; use stream=false for edits. Default: false. |
| `partial_images` | integer | no | Maximum preview images; nonzero requires stream=true. Previews are not separate billable generations. Default: 0. Min: 0. Max: 3. |

## Example

### curl

```bash
# Set once per job; reuse this key and the identical body after a timeout.
: "${AGENTSKY_IDEMPOTENCY_KEY:?Set a unique, saved key for this job}"
curl --fail-with-body https://gateway.agentsky.dev/v1/run \
  -H "authorization: Bearer $AGENTSKY_API_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: $AGENTSKY_IDEMPOTENCY_KEY" \
  -d '{"provider":"openai","endpoint":"gpt-image-2.5-flare","input":{"prompt":"A blue ceramic bowl on a white table","size":"1024x1024","quality":"low","output_format":"jpeg"}}'
# If status is READY/RUNNING, poll GET /v1/runs/{runId} with the same API key.
```

### JavaScript

```js
// Node.js 20+. Save one unique key per job; reuse it with the identical body.
const key = process.env.AGENTSKY_IDEMPOTENCY_KEY;
if (!key || !process.env.AGENTSKY_API_KEY) {
  throw new Error("Set AGENTSKY_API_KEY and a saved AGENTSKY_IDEMPOTENCY_KEY first");
}
const base = "https://gateway.agentsky.dev";
const headers = {
  authorization: `Bearer ${process.env.AGENTSKY_API_KEY}`,
  "content-type": "application/json",
  "Idempotency-Key": key,
};
const body = JSON.stringify({
  "provider": "openai",
  "endpoint": "gpt-image-2.5-flare",
  "input": {
    "prompt": "A blue ceramic bowl on a white table",
    "size": "1024x1024",
    "quality": "low",
    "output_format": "jpeg"
  }
});
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function request(path, options = {}) {
  for (let attempt = 0; attempt < 3; attempt++) {
    let response;
    let data;
    try {
      response = await fetch(base + path, {
        ...options, headers, signal: AbortSignal.timeout(180_000),
      });
      const text = await response.text();
      try { data = JSON.parse(text); } catch { /* Proxy timeouts may return HTML. */ }
    } catch (error) {
      if (attempt === 2) throw error; // Resume with the same key and body.
      await sleep(2000);
      continue;
    }
    // Failed runs can have non-2xx HTTP status. Never regenerate them automatically.
    if (data?.runId && data?.status) return data;
    if (response.ok && data) throw new Error("Unexpected response: missing runId/status");
    if (attempt < 2 && (response.status >= 500 || response.status === 408 || response.status === 429)) {
      await sleep(2000);
      continue; // POST retries keep the original key and body.
    }
    throw new Error(`HTTP ${response.status}: ${JSON.stringify(data ?? "Non-JSON response; retry with the same key and body")}`);
  }
}

let run = await request("/v1/run", { method: "POST", body });
console.log("Save runId:", run.runId);
const deadline = Date.now() + 30 * 60_000;
while (["READY", "RUNNING"].includes(run.status)) {
  if (Date.now() >= deadline) {
    throw new Error(`Still pending: poll /v1/runs/${run.runId} later; do not create a new job`);
  }
  await sleep(5000);
  run = await request(`/v1/runs/${encodeURIComponent(run.runId)}`);
}
console.log("Status:", run.status, "Charge:", run.price?.amount);
if (run.status !== "COMPLETED") {
  throw new Error(`Run ${run.runId}: ${JSON.stringify(run.error ?? run.status)}`);
}
console.log(run.output); // Output shape depends on the endpoint.
// READY/RUNNING price is provisional. Use the terminal receipt for reconciliation.
```

## Pricing

Single image generation: 1024x1024 (default): $0.0247 · 1360x768: $0.0247 · 768x1360: $0.0247 · 2048x2048: $0.0297 · 2736x1536: $0.0297 · 1536x2736: $0.0297 · 2880x2880: $0.033 · 3840x2160: $0.033 · 2160x3840: $0.033 · Other requests (example): Text input: $4.675 / 1M tokens · Cached text input: $1.16875 / 1M tokens · Image input: $7.48 / 1M tokens · Cached image input: $1.87 / 1M tokens · Text output: $0 / 1M tokens · Image output: $28.05 / 1M tokens

Read the final customer charge from price.amount.value after the run finishes. A RUNNING response is not the final bill.

## Questions

### What does GPT Image 2.5 Flare do?

Generate images, or provide images for editing and composition. Billing depends on the request and configured pricing route. Consult pricing_routes for eligible flat-price generation; other requests use native token billing with separate text, image and cached input rates. Without streaming, poll the run until COMPLETED; acceptance alone does not indicate completion. With input.stream=true, POST /v1/run returns gateway SSE: image_generation.partial_image previews followed by run.completed containing the final run, or run.failed. This is the gateway run protocol, not the OpenAI Images or Responses API. Streaming currently requires n=1. Reusing an Idempotency-Key replays the saved run without regenerating previews or charging twice. The complete request is limited to 32 MiB; an encoded result or individual SSE event is limited to 27 MiB and a stream to 108 MiB. Large batches or PNG outputs can exceed the result limit; prefer fewer images or JPEG/WebP compression. Interrupted or unverified results remain pending for reconciliation; never resubmit with a new key to recover a known run.

### How much does GPT Image 2.5 Flare cost?

Single image generation: 1024x1024 (default): $0.0247 · 1360x768: $0.0247 · 768x1360: $0.0247 · 2048x2048: $0.0297 · 2736x1536: $0.0297 · 1536x2736: $0.0297 · 2880x2880: $0.033 · 3840x2160: $0.033 · 2160x3840: $0.033 · Other requests (example): Text input: $4.675 / 1M tokens · Cached text input: $1.16875 / 1M tokens · Image input: $7.48 / 1M tokens · Cached image input: $1.87 / 1M tokens · Text output: $0 / 1M tokens · Image output: $28.05 / 1M tokens, using your plan when signed in. The customer charge is returned as price.amount.value with its currency; READY/RUNNING values are provisional.

### What does GPT Image 2.5 Flare take?

prompt is required; the rest of the fields are optional. Send them in the input object of a POST to /v1/run.

### What are the limits on GPT Image 2.5 Flare?

The catalog lists an execution timeout of 11 min. A request can return READY or RUNNING before completion; poll GET /v1/runs/{runId} with the same API key until it reaches a terminal status. An HTTP timeout does not prove the generation stopped.

### How do I retry safely and check the final charge?

Save a unique Idempotency-Key for each job. After a network error or HTML timeout, resend the identical POST body with the same key and API key to recover the existing run, then poll its runId. A new key can start another billable generation. An HTTP error or timeout does not establish the run outcome or final charge. Pending runs can still settle; check the terminal price.amount and billing state, and retain the runId for reconciliation. Do not automatically create a new job after a terminal failure.
