Use GPT Image 2 with Comfy Router

API Reference for openai/gpt-image-2, served by Comfy Router from OpenAI.

Quick start

Create a key in your Comfy workspace and export it as COMFY_API_KEY. The Python and TypeScript snippets use the Comfy SDKs (pip install comfy-sdk, npm install @comfyorg/sdk); the cURL snippet is the same call over raw HTTP. Model ID: openai/gpt-image-2 Endpoint: POST https://api.comfy.org/v2/models/openai/gpt-image-2

Wait for the result
Queue and collect later

from comfy_sdk import Comfy

# Reads COMFY_API_KEY from the environment.
# The SDK automatically creates an idempotency key and reuses it for automatic retries.
with Comfy() as client:
    result = client.models.run(
        "openai/gpt-image-2",
        {
            "prompt": "a rocketship on a launchpad",
            "quality": "low",
            "size": "1024x1024",
        },
    )

print(result)

import { comfy } from "@comfyorg/sdk";

// Reads COMFY_API_KEY from the environment.
// The SDK automatically creates an idempotency key and reuses it for automatic retries.
const { data } = await comfy.models.run("openai/gpt-image-2", {
  prompt: "a rocketship on a launchpad",
  quality: "low",
  size: "1024x1024",
});

console.log(data);

curl https://api.comfy.org/v2/models/openai/gpt-image-2 \
  -H "X-API-Key: $COMFY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d "{\"prompt\": \"a rocketship on a launchpad\", \"quality\": \"low\", \"size\": \"1024x1024\"}"

The same body, sent to POST https://api.comfy.org/v2/models/openai/gpt-image-2/requests. Router answers 201 with a request_id as soon as the run is admitted, and the result is collected once it is ready, from this process or another one. Queued delivery walks through status, cancellation and collection.

from comfy_sdk import Comfy

# Reads COMFY_API_KEY from the environment.
# Each submit() call mints its own Idempotency-Key and reuses it for automatic retries.
with Comfy() as client:
    handle = client.models.submit(
        "openai/gpt-image-2",
        {
            "prompt": "a rocketship on a launchpad",
            "quality": "low",
            "size": "1024x1024",
        },
    )
    print("request_id:", handle.request_id)  # with the model ID, all another process needs

    # Poll until the request completes, waiting the Retry-After the server names.
    for update in handle.iter_events():
        print(update.status, update.queue_position)

    # The provider's own payload, the same value models.run() returns.
    # A request that failed or was cancelled raises the typed Router error here.
    result = handle.get()

print(result)

import { comfy } from "@comfyorg/sdk";

// Reads COMFY_API_KEY from the environment.
// Each submit() call mints its own Idempotency-Key and reuses it for automatic retries.
const handle = await comfy.models.submit("openai/gpt-image-2", {
  prompt: "a rocketship on a launchpad",
  quality: "low",
  size: "1024x1024",
});
console.log("requestId:", handle.requestId); // with the model ID, all another process needs

// Poll until the request completes, waiting the Retry-After the server names.
for await (const update of handle.events()) {
  console.log(update.status, update.queuePosition);
}

// The same result models.run() returns. A request that failed or was cancelled rejects here.
const result = await handle.get();

console.log(result.data);

# 1. Submit. Router answers 201 with request_id, status_url, response_url and cancel_url.
curl https://api.comfy.org/v2/models/openai/gpt-image-2/requests \
  -H "X-API-Key: $COMFY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d "{\"prompt\": \"a rocketship on a launchpad\", \"quality\": \"low\", \"size\": \"1024x1024\"}"

# 2. Poll until status is COMPLETED, waiting the Retry-After seconds each response names.
REQUEST_ID="<request_id from the 201 body>"
curl -i https://api.comfy.org/v2/models/openai/gpt-image-2/requests/$REQUEST_ID/status \
  -H "X-API-Key: $COMFY_API_KEY"

# 3. Collect. 200 with the model's native output, 202 with the status body while it is still running.
curl https://api.comfy.org/v2/models/openai/gpt-image-2/requests/$REQUEST_ID \
  -H "X-API-Key: $COMFY_API_KEY"

Schema

Input

string

Background transparencyPossible values: transparent, opaque

string | string[]

The source image(s) to edit. PRESENCE OF THIS FIELD SELECTS THE EDIT OPERATION — omit it entirely for text-to-image generation. The model’s published example is the GENERATION call, which omits this field. Adding image is the whole of the difference between the two modes — same endpoint, same model id — except that an edit prompt describes the CHANGE you want rather than the scene, so the edit body below reads differently from the generation example even though only this field is structurally new. It is copyable exactly as printed:

{"prompt": "give the rocketship rainbow coloring", "image": ["data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg=="], "size": "1024x1024"}

— the payload is a complete 1x1 PNG, not an abbreviation, and this body is pinned as an accepted case in Router’s own request-validation tests. Swap in your own image’s bytes. Accepts one image or an array of them; gpt-image-1 and later take up to 16, which Router enforces from this schema before dispatching.

string

One image, as either an https URL Router fetches on the caller’s behalf or a data:image/<format>;base64,<payload> URI carrying the bytes inline. Accepted image types are png, webp and jpeg, and that set is ENFORCED at resolve time rather than left to the provider — an svg, gif, avif or tiff is refused here, naming the image you sent, instead of becoming a partner error two hops from the cause. Prefer the URL form. A base64 payload inflates roughly 4/3 and the whole request body is capped at 20 MiB, so the inline form caps out near a 15 MB source image; a URL sidesteps that entirely. THE URL MUST RESOLVE WITHOUT YOUR CREDENTIALS. Router fetches it server-side and sends no caller credential with the request, so a Comfy-signed asset URL — one whose signature is in the query string — is the supported form. An authenticated endpoint such as /api/assets/{id}/content answers Router 401 rather than the image; request that URL yourself and pass the signed URL it redirects to. The fetch is confined to Comfy’s own asset buckets rather than the open internet, on every redirect hop as well as the URL you send, so a third-party or redirecting URL is refused. The example below shows the shape only: a real value also carries the signing query parameters, which are deliberately omitted here because a published example lives in the spec forever and a real signature is both a leaked credential and a link that stops working. Each image is capped at 25 MiB and one request’s images at 64 MiB in total.

string

The gpt-image model to run. Router splices the addressed model id in, so a caller addressing /v2/models/openai/gpt-image-2 does not send this.

string

Content moderation settingPossible values: low, auto

integer

The number of images to generate (1-10).Range: 1 to 10

integer

Compression level for JPEG or WebP (0-100)Range: 0 to 100

string

Format of the output imagePossible values: png, webp, jpeg

string

required

A text description of the image to generate, or of the edit to make to image.

string

The quality of the generated or edited imagePossible values: low, medium, high, standard, hd

string

Size of the image (e.g., 1024x1024, 1536x1024, auto)

string

A unique identifier for end-user monitoring

Generated from the schema Router serves at GET /v2/models/openai/gpt-image-2/openapi.json, the same document it validates a call against before the request reaches the provider.

Output

object[]

string

Base64 encoded image data

string

Revised prompt

string

URL of the image

object

integer

object

integer

object

integer

string

Whether the generated image’s background is opaque or transparent. Populated on the fal-served branch only, which reports opaque.

integer

Unix timestamp, in seconds, of when the generation completed. Declared int64 because a present-day epoch value is close enough to 2^31 that an unformatted integer generates a 32-bit field in many SDK generators.Format: int64

string

The encoding of the bytes in data[].b64_json (for example png). Populated on the fal-served branch; absent on the OpenAI-served one, where the caller’s requested output_format is authoritative.

string

The quality tier the generation actually ran at. Populated on the fal-served branch when it can resolve one; absent otherwise.

string

The pixel dimensions the generation actually ran at, as <width>x<height>. Populated on the fal-served branch when it can resolve one; absent otherwise.

Examples

Input

{
  "prompt": "a rocketship on a launchpad",
  "quality": "low",
  "size": "1024x1024"
}

Output

{
  "created": 1767225600,
  "data": [
    {
      "b64_json": "PGJhc2U2ND4="
    }
  ],
  "usage": {
    "input_tokens": 12,
    "output_tokens": 1056,
    "total_tokens": 1068
  }
}

Before you ship

The SDKs create an Idempotency-Key and reuse it for automatic retries. For manual retries, reuse the original key. Router can hold the connection for up to 10 minutes. When a request fails, Router sends an X-Comfy-Error-Type response header explaining why. A 422 means Router rejected the input before calling the provider, and a 413 means the request body was larger than Router accepts. Download generated assets promptly because result URLs can expire. Any size limit named in a field description above is the provider’s own bound on that field, quoted from the provider’s specification. Router applies a separate cap to the whole request body, which base64-encoded media counts against: see request body size.

Headers

Authentication, idempotency, request IDs, error buckets, retry pacing, spend limits.

Using the Router API

Model discovery, validation errors, retries, and billing.

Limitations

What Router does not do today, and what to use instead.

Develop with Comfy

Deploy ComfyUI

Run Workflows

Demo Apps

Comfy Router

Comfy CLI

Specifications

Use GPT Image 2 with Comfy Router

Quick start

Schema

Input

Output

Examples

Input

Output

Before you ship

Headers

Using the Router API

Limitations

​Quick start

​Schema

​Input

​Output

​Examples

​Input

​Output

​Before you ship

Headers

Using the Router API

Limitations

Quick start

Schema

Input

Output

Examples

Input

Output

Before you ship