Image API Essentials & Best Practices

The one-line answer: every image model on APIYI is synchronous — send the request, keep the connection open, and the generated image comes back in the same response. There is no async task ID and no polling endpoint; if your client disconnects early, that result is gone, yet the request is still billed. A generous timeout is rule number one for image API development.

Three Facts to Know Before You Start

Everything Is Synchronous

A single HTTP request blocks until completion, matching the official upstream API shape — there is no submit-then-poll mode. Even providers that are async upstream (like FLUX) are wrapped into synchronous calls by the gateway, so you never write a polling loop.

No Task ID

There is no task_id lookup endpoint, and you cannot recover an image later using a request_id. APIYI proxies requests transparently and does not store generated results — once the connection drops, the result is unrecoverable.

Disconnects Are Still Billed

If your client times out and disconnects, the server and upstream still finish generating, and the request is billed as usual. A timeout that is too small means paying for images you never receive.

Model Series Quick Reference

Recommended timeouts, output formats, and URL support for each image model series:

Model Series	Endpoint	Recommended Timeout	Output Format	URL Output & Validity
GPT-Image-2 (Official)	`/v1/images/generations`, `/v1/images/edits`	360s (high + 2K/4K measured at 3-5 minutes)	Raw b64_json (no `data:` prefix)	❌ Not supported (`response_format` returns 400; the `image2_OSS` group does not cover the official channel yet)
GPT-Image-2-All (Reverse)	Same as above	300s	Default `b64_json` (no `data:` prefix, verified 2026-07); switchable via explicit `response_format: "url"`	✅ Explicit `url`: R2 CDN, ~24 hours; use the `image2_OSS` group if you depend on URLs
GPT-Image-2-VIP	Same as above	300s	Same as All (default `b64_json`, no prefix, verified 2026-07)	✅ Same as All (explicit `url` or the `image2_OSS` group)
Nano Banana Pro	Native Gemini `:generateContent`	1K/2K 300s, 4K 600s, multi-image 5+ minutes	Raw base64 in `inlineData.data`	`NB_OSS` beta group (see below)
Nano Banana 2	Same as above	360s	Same as above	`NB_OSS` coverage: contact support
Nano Banana Lite	Same as above	300s (~4s typical, headroom for peak congestion)	Same as above	`NB_OSS` coverage: contact support
FLUX	`/v1/images/generations`	60-120s, 180s for flex models	`data[0].url` only (URL is the upstream default)	⚠️ Valid for only ~10 minutes, no CORS — re-host server-side immediately
Seedream	`/v1/images/generations` (unified generate/edit endpoint)	60s (4K + hd around 30-60s)	Default `url` (URL is the upstream default); optional `b64_json` (raw base64, no prefix)	✅ BytePlus TOS, ~24 hours

response_format has a narrow surface: only GPT-Image-2-All / VIP and Seedream accept it; the official GPT-Image-2 channel returns 400 unknown_parameter if you pass it. Where supported, always pass it explicitly rather than relying on the default — the default has historically varied across groups and load conditions.

Billing and What Drives the Price

The most common billing question from newcomers: “Is each reference image a flat fee, or do bigger images consume more tokens?” Start with three intuitions:

Output Dominates the Cost

Taking gpt-image-2 as an example: text input $5/M, image input $8/M, output $30/M. The biggest price levers are always the output size and quality (quality × size) — reference image count comes second.

Input Images Are Not Flat-Fee

GPT-family input images map to tokens by dimensions/aspect ratio (bigger = more, with both a floor and a cap), and count adds up strictly linearly. The Gemini family is the opposite — output images cost a fixed token amount per resolution tier.

Trust the Returned usage

Both input and output tokens are in the response: GPT family in usage.input_tokens_details.image_tokens, Gemini family in usageMetadata.promptTokensDetails. Reconcile and price against these — never estimate by image count.

Token Accounting: The Two Model Families

Family	Input Image Tokens	Output Image Tokens
GPT family (gpt-image-2 etc.)	Dynamic by dimensions: square images at or below 1024² are all 1024 tokens, 2048² and above cap at 1521 (verified 2026-07); N images = N × single	Determined by `size` × `quality`: 1024² ranges from 196 tokens at low to several thousand at high
Gemini family (all Nano Banana models)	Counted in the IMAGE modality of `promptTokensDetails`	Fixed per resolution tier: 1120 per image at 1K/2K, 2000 at 4K, regardless of aspect ratio

Cost Intuition for Multiple Input Images

One reference image runs about 800-1600 image tokens ≈ $0.008-0.012 (gpt-image-2, measured, varying with dimensions/aspect ratio);
Count adds up linearly: 16 images ≈ $0.13, the same order of magnitude as one high output (≈$0.21) — input cost is no longer negligible in multi-image fusion;
Tokens are determined by pixel dimensions, not file size: compressing files helps upload stability but saves no tokens; to save tokens, reduce the image count (oversized images are capped, so no runaway bills either).

Full measurement table: gpt-image-2 — How Multiple Input Images Affect the Price; Gemini-family token accounting: usageMetadata guide and Nano Banana pricing.

Timeout Configuration

Why Default Timeouts Break Things

Most HTTP clients default to 30-60 second timeouts (requests has no limit itself but is often wrapped by frameworks that add ~30s), while image generation is a genuinely long request:

GPT-Image-2 at high quality with 2K/4K resolution measures 3-5 minutes end to end;
Nano Banana series 4K images start around 50 seconds, longer at peak times;
Multi-image fusion and image-edit requests are generally slower than text-to-image.

With default settings, the client kills the connection while the server is still generating normally — you see a wave of “timeouts” that are actually successful requests you disconnected from yourself, and every one of them is billed.

Per-Model Timeout Tiers

# Set client timeouts (seconds) per model, not one global value
IMAGE_TIMEOUTS = {
    "gpt-image-2": 360,                      # high + 2K/4K measured at 3-5 min
    "gpt-image-2-all": 300,
    "gpt-image-2-vip": 300,
    "gemini-3-pro-image": 600,               # Nano Banana Pro, 600s covers 4K
    "gemini-3.1-flash-image-preview": 360,   # Nano Banana 2
    "gemini-3.1-flash-lite-image": 300,      # Nano Banana Lite
    "flux": 120,                             # 180 recommended for flex models
    "seedream": 60,                          # 4K + hd around 30-60s
}

import requests

def generate_image(model: str, payload: dict, api_key: str) -> dict:
    resp = requests.post(
        "https://api.apiyi.com/v1/images/generations",
        headers={"Authorization": f"Bearer {api_key}"},
        json={"model": model, **payload},
        timeout=IMAGE_TIMEOUTS.get(model, 300),  # 300s fallback for unknown models
    )
    resp.raise_for_status()
    return resp.json()

Retry Strategy

Not every failure deserves a retry — start from how each case is billed:

Failure	Billed?	Recommendation
429 / 503 (rate limit, upstream overload)	Not billed	Retry with exponential backoff (e.g. 5s, 15s, 45s)
Client timeout / early disconnect	Billed	Increase the timeout first; if you must retry, cap attempts carefully
400 / 403 (parameter or permission errors)	Not billed	Fix the request before resending — blind retries are pointless
Content moderation block	Depends on the model (see note below)	Revise the prompt; resending as-is will most likely be blocked again

Moderation-block billing depends on the model: token-billed models (official GPT-Image-2 etc.) usually return a 400 error when moderation triggers — not billed. Only the per-image-billed Nano Banana Pro hits the “HTTP 200 but generation failed” Google-side block, and that call is billed — APIYI covers these non-user-fault failures with the Failed-Generation Credit Reimbursement Plan, which reimburses credit based on a per-image tally.

Working with base64 Output

Prefix Differences

The base64 payload is not uniform across series — this is the most common trap for new integrations:

Model Series	base64 Field	Includes `data:image/...;base64,` Prefix?
GPT-Image-2 (Official)	`data[0].b64_json`	No prefix (raw base64)
GPT-Image-2-All / VIP	`data[0].b64_json`	No prefix (verified 2026-07; earlier versions included the prefix)
Nano Banana series	`candidates[0].content.parts[].inlineData.data`	No prefix (raw base64)
Seedream (`b64_json` mode)	`data[0].b64_json`	No prefix (raw base64)

Prefix behavior has changed across channel versions, so always check startsWith("data:") first: strip the prefix before decoding (or use the value directly as an img src) when present, and decode raw values as-is — this avoids both the double-prefix bug and decoding failures on prefixed payloads.

Decoding to a File

import base64

b64 = response["data"][0]["b64_json"]
if b64.startswith("data:"):          # defensive strip: some channel versions included a data: prefix
    b64 = b64.split(",", 1)[1]
with open("output.png", "wb") as f:
    f.write(base64.b64decode(b64))

let b64 = response.data[0].b64_json;
if (b64.startsWith("data:")) {
  b64 = b64.slice(b64.indexOf(",") + 1);
}
require("fs").writeFileSync("output.png", Buffer.from(b64, "base64"));

Playground Rendering Limits

base64 responses are often several megabytes, and the browser Playground may show unable to complete request — this does not mean the request failed. The request succeeded and was billed; the browser simply cannot render a string that long. Verify results from code, or switch to a model/parameter that returns a url.

Input Image Preprocessing

Image-edit / reference-image endpoints (such as gpt-image-2’s /v1/images/edits) only accept png / jpg / webp. Products that let users upload their own photos hit one particularly sneaky trap: photos straight off a phone camera are often not standard JPEG.

Typical Symptom: 400 invalid_image_file

{
  "error": {
    "message": "Invalid image file or mode for image 1, please check your image file. ...",
    "code": "invalid_image_file"
  }
}

The usual root cause is MPO format (Multi-Picture Object, a multi-frame JPEG container): .jpg files straight out of Huawei Mate-series and similar phones embed an HDR gain-map sub-frame and are actually MPO. What makes them sneaky is that the file starts with the same FFD8 header — the extension, the HTTP Content-Type, and the file command all report JPEG — and only frame-aware parsing reveals the truth:

from PIL import Image
Image.open("photo.jpg").format   # "MPO" means you're hit; standard images return "JPEG"/"PNG"

Verified July 2026 (gpt-image-2 edits endpoint): MPO images are always rejected, while the same image re-encoded to standard JPEG/PNG succeeds at the full original resolution (3072×4096) — the problem is the format, not the size. This 400 is returned quickly at the input-validation stage and is not billed.

Recommendation: Re-encode Server-Side, Uniformly

Rather than debugging photos one by one, add a single re-encode step to your upload pipeline — it also absorbs HEIC, CMYK, and other non-standard inputs:

from PIL import Image
import io

def normalize_image(raw: bytes) -> bytes:
    """Any source image → standard JPEG that passes image-edit format validation"""
    im = Image.open(io.BytesIO(raw))
    im.load()                      # multi-frame formats (MPO etc.): keep the first frame only
    if im.mode not in ("RGB", "RGBA"):
        im = im.convert("RGB")     # normalize CMYK / P and other modes to RGB
    out = io.BytesIO()
    im.save(out, format="JPEG", quality=92)
    return out.getvalue()

While re-encoding, shrink the payload too (long edge up to 4096, JPEG quality 80-92) and keep each image under 1.5MB — upload success rates and generation speed both improve, and output quality does not depend on input file size. See gpt-image-2 image edit: Reference Image Format Requirements and Preprocessing.

Input Image Format Preprocessing

Image-edit / reference-image endpoints (such as gpt-image-2’s /v1/images/edits) only accept png / jpg / webp as input. Products that take user-shot photos hit one particularly sneaky trap: photos straight off a phone camera are often not standard JPEG.

Typical symptom: 400 invalid_image_file

{
  "error": {
    "message": "Invalid image file or mode for image 1, please check your image file. ...",
    "code": "invalid_image_file"
  }
}

The usual root cause is MPO format (Multi-Picture Object, a multi-frame JPEG container): .jpg files straight out of Huawei Mate-series phones embed an HDR gain-map sub-frame and are actually MPO. What makes these files sneaky is that the header is the same FFD8 — the extension, the HTTP Content-Type, and the file command all report JPEG — and only frame-aware parsing can tell:

from PIL import Image
Image.open("photo.jpg").format   # "MPO" means you're affected; standard files return "JPEG"/"PNG"

Verified July 2026 (gpt-image-2 edit endpoint): MPO files are always rejected; the same image re-encoded as standard JPEG/PNG succeeds at the full original resolution (3072×4096) — the problem is the format, not the size. This 400 is returned quickly at the input-validation stage and is not billed.

Recommendation: re-encode uniformly on the server side

Rather than debugging images one by one, add a single re-encode step to your upload pipeline — it also covers HEIC, CMYK, and other non-standard inputs:

from PIL import Image
import io

def normalize_image(raw: bytes) -> bytes:
    """Any input image → standard JPEG that passes image-edit endpoint validation"""
    im = Image.open(io.BytesIO(raw))
    im.load()                      # multi-frame formats (MPO etc.): keep only the first frame
    if im.mode not in ("RGB", "RGBA"):
        im = im.convert("RGB")     # normalize CMYK / P etc. to RGB
    out = io.BytesIO()
    im.save(out, format="JPEG", quality=92)
    return out.getvalue()

While re-encoding, compress as well (long edge no more than 4096px, JPEG quality 80-92) and keep each image within 1.5MB — upload success rate and generation speed both improve, and output quality is unrelated to input file size. See gpt-image-2 Image Edit — Reference Image Format Requirements and Preprocessing.

Getting URL Output Instead

There are three paths, in order of reliability:

URL is the upstream default — FLUX (valid only ~10 minutes, no CORS headers; download and re-host server-side immediately) and Seedream (BytePlus TOS, ~24 hours) return URLs natively, with no configuration needed.
OSS groups (deterministic URL output — recommended for production):
- image2_OSS group: covers GPT-Image-2-All / VIP (1x multiplier, no surcharge); switch your token to this group for stable URL output with no base64 fallback. The official GPT-Image-2 channel is not covered yet.
- NB_OSS beta group: covers the Nano Banana series, with the image URL delivered in the text field — see the NB-OSS group guide.
Explicit response_format: "url" — only GPT-Image-2-All / VIP (R2 CDN, ~24 hours) and Seedream accept it; the surface is narrow, and the official GPT-Image-2 channel returns 400 if you pass it. This is a per-request switch on the default group — businesses that depend on URLs should use an OSS group instead.

GPT-Image-2 (Official) currently has no URL output path at all — base64 only.

Every image URL these platforms return is a temporary link (10 minutes to 24 hours). Anything that needs long-term storage — product images, user creations, history — must be re-hosted to your own object storage / CDN immediately after generation, with your own URL saved to your database.

Troubleshooting Timeouts and Disconnects

If you have already raised the SDK timeout and still see frequent “timeouts”, work through this checklist:

Confirm the effective client-side timeout

Frameworks often wrap the HTTP client in another timeout layer (task-queue worker limits, serverless execution caps). Any layer shorter than the model’s generation time will kill the request.

Check intermediaries: nginx / load balancers / CDN

Self-hosted reverse proxies (proxy_read_timeout), cloud load balancer idle timeouts, and CDN origin timeouts commonly default to 60 seconds and will cut the connection before your client does. Every hop on a long-request path needs to be widened.

Enable keep-alive so idle connections are not reclaimed

Connections with no bytes flowing for a long time can be silently dropped by NAT devices or firewalls; TCP or HTTP keep-alive significantly reduces the odds.

Use the request ID and console logs to check billing

Record the x-request-id response header and look it up in the APIYI console call logs. If the call appears there, the server finished generating and billed the request — the connection was cut on your side of the path.

Want Task-Style Async Management?

The platform does not offer an async API, but you can build an async shell on top of the synchronous endpoints yourself:

Why There Is No Async API

FAQ: Is there an async image API? Can I query results by task ID?

Build Your Own Async Queue

Engineering guide: wrap synchronous calls in a task queue with your own task_id, persistence, and retries

NB-OSS URL Output Group

Switch Nano Banana output to URLs and cut base64 transfer overhead

​Three Facts to Know Before You Start

Everything Is Synchronous

No Task ID

Disconnects Are Still Billed

​Model Series Quick Reference

​Billing and What Drives the Price

Output Dominates the Cost

Input Images Are Not Flat-Fee

Trust the Returned usage

​Token Accounting: The Two Model Families

​Cost Intuition for Multiple Input Images

​Timeout Configuration

​Why Default Timeouts Break Things

​Per-Model Timeout Tiers

​Retry Strategy

​Working with base64 Output

​Prefix Differences

​Decoding to a File

​Playground Rendering Limits

​Input Image Preprocessing

​Typical Symptom: 400 invalid_image_file

​Recommendation: Re-encode Server-Side, Uniformly

​Input Image Format Preprocessing

​Typical symptom: 400 invalid_image_file

​Recommendation: re-encode uniformly on the server side

​Getting URL Output Instead

​Troubleshooting Timeouts and Disconnects

​Want Task-Style Async Management?

Why There Is No Async API

Build Your Own Async Queue

NB-OSS URL Output Group

Three Facts to Know Before You Start

Model Series Quick Reference

Billing and What Drives the Price

Token Accounting: The Two Model Families

Cost Intuition for Multiple Input Images

Timeout Configuration

Why Default Timeouts Break Things

Per-Model Timeout Tiers

Retry Strategy

Working with base64 Output

Prefix Differences

Decoding to a File

Playground Rendering Limits

Input Image Preprocessing

Typical Symptom: 400 invalid_image_file

Recommendation: Re-encode Server-Side, Uniformly

Input Image Format Preprocessing

Typical symptom: 400 invalid_image_file

Recommendation: re-encode uniformly on the server side

Getting URL Output Instead

Troubleshooting Timeouts and Disconnects

Want Task-Style Async Management?