Generate and Edit Images with GPT-Image-2.5 Through APIMart

What the image2.5 APIMart gateway does

The image2.5 gateway provides access to the GPT Image 2.5 generation and editing family through the APIMart API. Instead of integrating a separate credential and request format for every image model, you use one base URL, one bearer token, and the OpenAI-style /v1/images/generations endpoint.

The API is asynchronous. A generation request returns a task ID rather than an inline image. Your application then polls the task endpoint until processing completes or fails. Successful tasks contain temporary output URLs that should be downloaded before they expire.

APIMart is the service documented by the repository. The gpt-image-2.5-ext endpoint is a third-party relay route, while gpt-image-2.5-flare and gpt-image-2.5-sunburst are the token-billed routes. Verify current limits and pricing before a production run.

Key features

• One API base URL: Requests use https://api.apimart.ai/v1.
• Two model variants: Choose Flare for everyday generation and batch drafts, or Sunburst for editing precision and production-oriented assets.
• Two billing approaches: The relayed route is billed per delivered image, while the official routes use token-based billing.
• Asynchronous processing: Submit a request and poll GET /v1/tasks/{task_id} for progress.
• Multiple output tiers: The relayed route supports 1K, 2K, and 4K.
• Flexible compositions: Select from ten aspect ratios or use auto.
• Reference-driven generation: Supply up to 16 entries in image_urls for image-to-image or editing work.
• Small batches: Request between one and four delivered images with n on the relayed route.

Choose the correct model route

Relayed per-image route

Use model: "gpt-image-2.5-ext" when you want flat per-delivered-image billing. Select the underlying variant with version: "flare" or version: "sunburst".

• flare is positioned for high-volume generation, everyday images, and drafts.
• sunburst is positioned for edits and reference-driven production work.

The repository observed a price of $0.0085 per delivered 1K image for both variants on September 16, 2026. It also recorded $0.014 for 2K, $0.021 for 4K Flare, and advised checking the live price for 4K Sunburst. These are observation-dated figures, not permanent guarantees.

Official token-billed routes

Use gpt-image-2.5-flare or gpt-image-2.5-sunburst directly for token-based billing. These routes omit the version field and support the low, medium, high, xhigh, and max quality ladder. The official route also supports exact pixel dimensions.

A practical rule is to use the relayed route when predictable per-image cost matters, and consider the official route when its quality controls or exact dimensions are required.

Example output range

The repository demonstrates prompts for product photography, portraits, architecture, UI assets, illustrations, game art, food photography, and macro imagery. The following supplied images illustrate the type of visual output included with the project.

Installation and setup

1. Create an API key

Obtain a key from APIMart's API key page. Store it in an environment variable rather than placing it directly in source code.

export APIMART_API_KEY="your-api-key"

2. Select a client

cURL requires no project dependency beyond a standard command-line installation. For the Python example, install the requests package:

python -m pip install requests

The repository also includes a JavaScript example for Node.js 18 or newer, where fetch is available globally.

3. Understand the request headers

Send the API key in the Authorization header. The relayed-route examples also use a response-version header and a unique idempotency key.

• Authorization: Bearer $APIMART_API_KEY
• Content-Type: application/json
• X-APIMart-Response-Version: 2026-07-27
• Idempotency-Key: unique-request-value

Reuse the same idempotency key when retrying the same submission. Generate a new key when you intentionally want a new image task.

Basic usage: generate an image with cURL

The following request uses the per-image route, selects Flare, and asks for one square 1K image:

IDEMPOTENCY_KEY="$(uuidgen)"

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header "Authorization: Bearer $APIMART_API_KEY" \
  --header "Content-Type: application/json" \
  --header "X-APIMart-Response-Version: 2026-07-27" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data '{
    "model": "gpt-image-2.5-ext",
    "version": "flare",
    "prompt": "A cozy reading nook beside a window on a rainy day, warm table lamp, cinematic lighting",
    "size": "1:1",
    "resolution": "1K",
    "n": 1
  }'

A successful submission returns HTTP 202. Read the task identifier from data.id or use the returned data.poll_url.

Poll the task

Replace task_01EXAMPLE with the returned task ID:

curl --request GET \
  --url https://api.apimart.ai/v1/tasks/task_01EXAMPLE \
  --header "Authorization: Bearer $APIMART_API_KEY" \
  --header "X-APIMart-Response-Version: 2026-07-27"

The task status progresses through pending and processing before reaching completed or failed. The response can also report progress, cost, and credits_cost. When complete, retrieve the image URL from result.images[].url and inspect expires_at.

End-to-end Python example

This example submits one image and checks the task every five seconds until it reaches a terminal state:

import os
import time
import uuid
import requests

BASE_URL = "https://api.apimart.ai/v1"
COMMON_HEADERS = {
    "Authorization": f"Bearer {os.environ['APIMART_API_KEY']}",
    "Content-Type": "application/json",
    "X-APIMart-Response-Version": "2026-07-27",
}

def generate_image(prompt, version="flare", resolution="1K", size="1:1"):
    submit_headers = {
        **COMMON_HEADERS,
        "Idempotency-Key": str(uuid.uuid4()),
    }

    response = requests.post(
        f"{BASE_URL}/images/generations",
        headers=submit_headers,
        json={
            "model": "gpt-image-2.5-ext",
            "version": version,
            "prompt": prompt,
            "size": size,
            "resolution": resolution,
            "n": 1,
        },
        timeout=60,
    )
    response.raise_for_status()
    task_id = response.json()["data"]["id"]

    while True:
        task_response = requests.get(
            f"{BASE_URL}/tasks/{task_id}",
            headers=COMMON_HEADERS,
            timeout=60,
        )
        task_response.raise_for_status()
        task = task_response.json()["data"]

        if task["status"] == "completed":
            return task
        if task["status"] == "failed":
            raise RuntimeError(f"Generation failed: {task}")

        time.sleep(5)

result = generate_image(
    "A sky garden at dawn, architectural photography",
    version="flare",
    resolution="1K",
    size="16:9",
)

for image in result["result"]["images"]:
    print(image["url"], image.get("expires_at"))

For a production client, return or store the complete task object so you can retain cost, progress, expiration, and error information instead of returning only a URL.

Use reference images for editing

To perform image-to-image generation or editing on the relayed route, add an image_urls array. It can contain up to 16 URLs or data URLs. The repository states that reference images do not add a separate charge on this route.

{
  "model": "gpt-image-2.5-ext",
  "version": "sunburst",
  "prompt": "Preserve the product label, replace the background with soft off-white, and add a natural cast shadow",
  "image_urls": [
    "https://example.com/source-product.jpg"
  ],
  "size": "1:1",
  "resolution": "2K",
  "n": 1
}

Sunburst is the repository's suggested variant for editing precision and reference-driven work. Use accessible URLs or valid data URLs, and keep the list within the documented limit.

Request field reference for the relayed route

• model: Required. Set it to gpt-image-2.5-ext.
• version: Accepts flare or sunburst; the default is Flare.
• prompt: Required and must not be empty after trimming.
• resolution: Accepts 1K, 2K, or 4K; the default is 1K.
• size: Accepts auto, 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 5:4, 4:5, or 21:9.
• n: Accepts an integer from 1 through 4.
• image_urls: An optional array containing up to 16 reference URLs or data URLs.

Calling the token-billed route

The official route uses the same generation path but changes the model ID, removes version, and adds a quality setting. This example selects Sunburst with high quality:

curl --request POST \
  --url https://api.apimart.ai/v1/images/generations \
  --header "Authorization: Bearer $APIMART_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "gpt-image-2.5-sunburst",
    "prompt": "Preserve the product label, replace the background with soft off-white, add a natural cast shadow",
    "size": "1:1",
    "resolution": "1k",
    "quality": "high",
    "n": 1
  }'

Consult the official-route reference and the relayed-route reference for the current field definitions.

Advanced tips for reliable integrations

1. Make retries idempotent. Preserve the original idempotency key if a submission times out and you are unsure whether the task was created. A new key may create another billable generation.
2. Treat polling as normal workflow. Handle both completed and failed. Avoid rapid polling; the repository example waits five seconds between checks.
3. Use the returned poll URL. The response includes data.poll_url, which avoids reconstructing the task endpoint manually.
4. Download outputs promptly. Generated image URLs are temporary. Copy each output to your own storage before its expires_at time.
5. Record actual cost. Persist cost and credits_cost from the task response. This lets you compare observed billing with published pricing.
6. Validate cost with one paid request. Pricing and promotional routing can change, so run a small test before launching a large batch.
7. Use the appropriate route. Choose the relayed route for predictable per-image billing and batches of up to four. Choose an official model ID when the quality ladder or exact pixel controls are important.
8. Switch variants without rewriting the client. On the relayed route, change only version between flare and sunburst.
9. Protect credentials. Keep the API key in environment variables or a secrets manager and never expose it in browser-side code.

Conclusion

APIMart's image2.5 gateway offers a consistent way to access GPT Image 2.5 generation and editing. Start with gpt-image-2.5-ext and Flare for predictable, high-volume generation, switch to Sunburst for editing or reference-driven work, and use the official model IDs when token billing and expanded quality controls fit the task better.

The essential integration pattern is simple: submit the image request, save the returned task ID, poll until completion, inspect the reported cost, and download every result before its temporary URL expires. Before scaling, review the current APIMart pricing and validate your chosen route with a small paid request.