Image Generation

POST /v1/images/generations

OpenAI-compatible image generation. The primary model is gpt-image-2. Two modes are supported:

• Synchronous — the request blocks until the image is ready and returns it directly (best for low concurrency / interactive use).
• Asynchronous — submit and immediately receive a job ID, then poll for the result (best for high volume / avoiding long-held connections).

Available models

Every model above supports both usage modes:

• Text-to-image — POST /v1/images/generations (synchronous) or POST /v1/images/generations/async (asynchronous).
• Image-to-image — POST /v1/images/edits (synchronous) or POST /v1/images/edits/async (asynchronous), sending image and prompt as multipart form fields. The size / resolution parameters are exactly the same as for text-to-image.

Compatibility: the model names gpt-image-2-2K and gpt-image-2-4K are still accepted so existing integrations keep working; they are equivalent to gpt-image-2 with resolution set to 2K / 4K. New integrations should use gpt-image-2 plus parameters.

Choosing the resolution tier

gpt-image-2 supports three resolution tiers — 1K / 2K / 4K — under one model name, selected by parameters (no need to switch models). Two equivalent ways:

• resolution (recommended): set the tier directly to 1K / 2K / 4K; set the aspect ratio with size, or omit it (defaults to a 1:1 square).
• size: pass the pixel dimensions for that tier (see the table below); the gateway derives both the tier and the aspect ratio from it.

gpt-image-2.5-flare / gpt-image-2.5-sunburst work the same way; gpt-image-2.5 supports 1K only.

Synchronous: POST /v1/images/generations

Request parameters

Tier precedence: resolution > the tier implied by size > default 1K.

Tip: for large images (2K/4K) or high concurrency, send "response_format": "url" — the response body is a few hundred bytes and the client downloads the image only when needed.

Resolution tier table

The model renders at its native resolution for the chosen tier and aspect ratio, so the pixel dimensions of the returned image can differ slightly from the requested size.

Billing

The billing unit and unit price for image generation are defined by the "Pricing" page and the Portal pricing page of the site you use. The usage block in the response reflects the token usage of this generation and can be used for reconciliation; higher tiers produce larger images and therefore cost more.

Examples

cURL

curl https://api.aiin1.ai/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a red fox running in snow, studio lighting",
    "n": 1
  }'

cURL (16:9 at the 2K tier, selected with size)

curl https://api.aiin1.ai/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a red fox running in snow, studio lighting",
    "size": "2560x1440",
    "n": 1
  }'

cURL (tier selected with resolution)

curl https://api.aiin1.ai/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "a red fox running in snow, studio lighting",
    "size": "1024x1024",
    "resolution": "2K",
    "n": 1
  }'

Python

import openai
 
client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.aiin1.ai/v1",
)
 
resp = client.images.generate(
    model="gpt-image-2",
    prompt="a red fox running in snow, studio lighting",
    n=1,
)
b64 = resp.data[0].b64_json   # base64-encoded PNG

The OpenAI SDK has no native resolution field — pass it via extra_body:

resp = client.images.generate(
    model="gpt-image-2",
    prompt="a red fox running in snow, studio lighting",
    size="1024x1024",
    n=1,
    extra_body={"resolution": "2K"},
)

Image-to-image: POST /v1/images/edits

Upload the source image and the prompt as multipart/form-data. The response has the same shape as synchronous text-to-image (inline base64).

The mask parameter is not supported yet and returns an error if sent; describe the region to change in prompt instead.

An edit usually takes 1–3 minutes and can take longer at peak times. Set the client read timeout to at least 15 minutes, otherwise the client may disconnect before the image is ready — or use the asynchronous edit route described at the end of this page.

Reference images can also be passed as image URLs or data URLs (JSON form, no file upload), on both the synchronous and asynchronous routes — see "Reference images by URL" at the end of this page.

cURL (single image)

curl https://api.aiin1.ai/v1/images/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F image=@input.png \
  -F model=gpt-image-2.5-sunburst \
  -F prompt="turn the sky into a starry night, keep the fox unchanged" \
  -F resolution=2K

cURL (multiple reference images, 16:9 landscape)

curl https://api.aiin1.ai/v1/images/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image[]=@product.png" \
  -F "image[]=@background.jpg" \
  -F model=gpt-image-2 \
  -F prompt="place the product from the first image onto the scene in the second image" \
  -F size=2560x1440

Python

import base64
import openai
 
client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.aiin1.ai/v1",
    timeout=900,   # edits are slow — keep the read timeout at 15 minutes or more
)
 
with open("input.png", "rb") as f:
    resp = client.images.edit(
        model="gpt-image-2.5-sunburst",
        image=f,                      # multiple reference images: image=[f1, f2]
        prompt="turn the sky into a starry night, keep the fox unchanged",
        extra_body={"resolution": "2K"},
    )
 
with open("output.png", "wb") as out:
    out.write(base64.b64decode(resp.data[0].b64_json))

Response

The image is returned inline as base64:

{
  "created": 1730000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...",
      "revised_prompt": "..."
    }
  ],
  "usage": {
    "input_tokens": 18,
    "input_tokens_details": {
      "image_tokens": 0,
      "text_tokens": 18
    },
    "output_tokens": 7024,
    "output_tokens_details": {
      "image_tokens": 7024,
      "text_tokens": 0
    },
    "total_tokens": 7042
  }
}

To display in a browser, prefix it: data:image/png;base64,<b64_json>.

With "response_format": "url" the response carries a download link instead of base64:

{
  "created": 1730000000,
  "data": [
    {
      "url": "https://<bucket>.r2.cloudflarestorage.com/...&X-Amz-Signature=...",
      "revised_prompt": "..."
    }
  ],
  "usage": { "...": "same as above" }
}

The link is valid for about 2 hours — download or re-host it within that window; the image is deleted after 48 hours. In the rare case the image was generated but the link could not be created, the request returns 502 and is not billed; simply retry.

Asynchronous: POST /v1/images/generations/async

The request body is identical to synchronous text-to-image (model / prompt / n / size / resolution / quality, with the same meanings as above), but it returns a job ID immediately instead of blocking. Use this for batch generation or when the client shouldn't hold a long connection open.

This section covers async text-to-image. For async image-to-image see "Asynchronous image-to-image" at the end of this page.

1. Submit

curl https://api.aiin1.ai/v1/images/generations/async \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "a red fox running in snow",
    "size": "2560x1440",
    "n": 1
  }'

Returns 202 Accepted:

{
  "id": "nximg_xxxxxxxx",
  "status": "queued",
  "created": 1730000000,
  "object": "image.generation.async"
}

2. Poll: GET /v1/images/generations/async/{job_id}

curl https://api.aiin1.ai/v1/images/generations/async/nximg_xxxxxxxx \
  -H "Authorization: Bearer YOUR_API_KEY"

status transitions: queued → processing → succeeded (or failed). Poll every 1–2 seconds; generation usually takes seconds to tens of seconds.

In progress:

{ "id": "nximg_xxxxxxxx", "status": "processing", "created": 1730000000 }

Succeeded:

{
  "id": "nximg_xxxxxxxx",
  "status": "succeeded",
  "created": 1730000000,
  "data": [
    {
      "url": "https://<bucket>.r2.cloudflarestorage.com/...&X-Amz-Signature=...",
      "revised_prompt": "..."
    }
  ],
  "usage": {
    "input_tokens": 18,
    "input_tokens_details": {
      "image_tokens": 0,
      "text_tokens": 18
    },
    "output_tokens": 7024,
    "output_tokens_details": {
      "image_tokens": 7024,
      "text_tokens": 0
    },
    "total_tokens": 7042
  }
}

Failed:

{
  "id": "nximg_xxxxxxxx",
  "status": "failed",
  "created": 1730000000,
  "error": { "type": "upstream_error", "message": "generation failed", "code": "..." }
}

About url: unlike the synchronous route (inline base64), the async route returns a signed download URL on success (valid for ~2 hours). Download or re-host it within the validity window; an expired URL requires regenerating. Failed jobs are not billed.

Field reference

Asynchronous image-to-image: POST /v1/images/edits/async

The asynchronous version of POST /v1/images/edits. The request is exactly the same (multipart/form-data file upload, or the JSON form with image URLs; parameters as in the "Image-to-image" section above), but it returns a job ID immediately; poll for the result once the image is ready. Edits are slow (usually 1–3 minutes), so this route is recommended for batch work or when the client shouldn't hold a connection open.

Differences from the synchronous edit route:

• Up to 8 input images, at most 25 MB each and 32 MB for the whole request.
• mask is not supported and returns 400.
• On success it returns a signed download URL (valid for ~2 hours), not inline base64.

1. Submit a job

curl https://api.aiin1.ai/v1/images/edits/async \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F image=@input.png \
  -F model=gpt-image-2 \
  -F prompt="turn the sky into a starry night, keep the fox unchanged" \
  -F resolution=2K

For multiple reference images repeat image[] (or image), as with the synchronous route.

Returns 202 Accepted:

{
  "id": "nximg_xxxxxxxx",
  "status": "queued",
  "created": 1730000000,
  "object": "image.edit.async"
}

2. Poll for the result: GET /v1/images/edits/async/{job_id}

curl https://api.aiin1.ai/v1/images/edits/async/nximg_xxxxxxxx \
  -H "Authorization: Bearer YOUR_API_KEY"

The response is exactly the same as for async text-to-image (queued → processing → succeeded / failed; on success data[].url is the download link and usage is included). Poll every 2–5 seconds. Job IDs are shared by both async routes, so GET /v1/images/generations/async/{job_id} also works.

Python example

import time
import requests
 
API = "https://api.aiin1.ai/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}
 
# 1. Submit (multiple reference images: files=[("image[]", f1), ("image[]", f2)])
with open("input.png", "rb") as f:
    job = requests.post(
        f"{API}/images/edits/async",
        headers=HEADERS,
        files=[("image", ("input.png", f, "image/png"))],
        data={
            "model": "gpt-image-2",
            "prompt": "turn the sky into a starry night, keep the fox unchanged",
            "resolution": "2K",
        },
        timeout=120,
    ).json()
 
# 2. Poll
while True:
    r = requests.get(f"{API}/images/edits/async/{job['id']}", headers=HEADERS, timeout=30).json()
    if r["status"] in ("succeeded", "failed"):
        break
    time.sleep(3)
 
if r["status"] == "succeeded":
    img = requests.get(r["data"][0]["url"], timeout=120).content   # URL valid for ~2 hours
    open("output.png", "wb").write(img)
else:
    print(r["error"])

Reference images by URL (JSON form)

Applies to POST /v1/images/edits (synchronous) and POST /v1/images/edits/async (asynchronous). When your images already live in object storage, a CDN or an image host, there is no need to download and re-upload them — put the links straight into a JSON request body.

How it works: the gateway first downloads and validates every reference image, and only starts generating once all of them pass. If any image has a problem, the request returns 400 before generation and is not billed. This prevents the case where a broken link still produces an image unrelated to your reference — and you get charged for it.

Request format

• Header: Content-Type: application/json (cannot be combined with multipart; a request uses one form or the other).
• Body parameters:

mask is not supported and returns 400.

How each item in images can be written

All of the following are accepted, and they can be mixed within one array:

You can also use the image field instead of images; its value may be a single string or an array.

URL requirements

Tip: compress reference images before sending them, ideally to 2 MB or less each (for example a JPEG whose longer side is at most 2048 pixels). Smaller images are submitted faster and succeed more often, especially at peak times.

data URL requirements

• The form must be data:image/png;base64,..., data:image/jpeg;base64,... or data:image/webp;base64,....
• The base64 must be valid, and the declared type must match the actual content (declaring image/png for JPEG content is rejected).
• data URLs count toward the 32 MB whole-request limit, and base64 adds about a third, so keep each original image under roughly 20 MB; prefer links for large images.

Converting a local file to a data URL:

import base64
 
def to_data_url(path: str) -> str:
    data = open(path, "rb").read()
    if data.startswith(b"\x89PNG"):
        mime = "image/png"
    elif data.startswith(b"\xff\xd8\xff"):
        mime = "image/jpeg"
    elif data[:4] == b"RIFF" and data[8:12] == b"WEBP":
        mime = "image/webp"
    else:
        raise ValueError("only PNG / JPEG / WEBP are supported")
    return f"data:{mime};base64,{base64.b64encode(data).decode()}"

Examples

cURL: synchronous, two reference images (one URL, one data URL), link output

curl https://api.aiin1.ai/v1/images/edits \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "place the product from the first image into the scene of the second image, keeping the product unchanged",
    "images": [
      "https://cdn.example.com/product.png",
      "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
    ],
    "size": "2560x1440",
    "response_format": "url"
  }'

Python: synchronous

import requests
 
API = "https://api.aiin1.ai/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}
 
r = requests.post(
    f"{API}/images/edits",
    headers=HEADERS,
    json={
        "model": "gpt-image-2",
        "prompt": "turn the sky into a starry night, keep everything else unchanged",
        "images": ["https://cdn.example.com/photo.jpg"],
        "response_format": "url",
    },
    timeout=900,   # edits are slow — keep the read timeout at 15 minutes or more
)
d = r.json()
if r.status_code != 200:
    raise RuntimeError(d["error"]["message"])      # e.g. "images[0]: host cdn.example.com answered HTTP 404"
img = requests.get(d["data"][0]["url"], timeout=120).content   # link valid for ~2 hours
open("output.png", "wb").write(img)

Python: asynchronous

import time
import requests
 
API = "https://api.aiin1.ai/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}
 
r = requests.post(
    f"{API}/images/edits/async",
    headers=HEADERS,
    json={
        "model": "gpt-image-2",
        "prompt": "turn the sky into a starry night, keep everything else unchanged",
        "images": ["https://cdn.example.com/photo.jpg"],
    },
    timeout=120,
)
job = r.json()
if r.status_code != 202:                       # a bad reference image is rejected with 400 at submit time
    raise RuntimeError(job["error"]["message"])
 
while True:
    res = requests.get(f"{API}/images/edits/async/{job['id']}", headers=HEADERS, timeout=30).json()
    if res["status"] in ("succeeded", "failed"):
        break
    time.sleep(3)

Error reference

A problem with a reference image returns HTTP 400 with error.type = invalid_request_error. For an error about one particular image, message starts with images[index]: (0-based, the position in the images array) followed by the reason; errors about the request as a whole (too many images, mask sent, no image given) have no index prefix. Errors show the host only, never the full URL.

Billing

• A reference image fails validation: no image is generated and nothing is billed.
• Validation passes and generation succeeds: billed exactly the same as the file-upload form.