ImgRouter API

One API.
The world’s top image models.

Call the same image models, cheaper than official, from anywhere. Official endpoints block some countries. This API does not.

Base URLhttps://api.imgrouter.comv1 stable

7 image routesREST JSON API100 Credits per $1

Get started

Generate your first image

Create a live API key, keep it on your server, and send your first request. The same JSON shape works across every enabled route.

1Create a keyOpen Console → API Keys

2Set your secretIMGROUTER_API_KEY

3Send a requestPOST /v1/images/generations

cURL

curl https://api.imgrouter.com/v1/images/generations \
  -H "Authorization: Bearer $IMGROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-hero-001" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Editorial product photograph, warm studio light",
    "size": "16:9",
    "resolution": "1K",
    "n": 1
  }'

200 response

{
  "id": "req_01K4…",
  "object": "image.generation",
  "created": 1787424152,
  "model": "gpt-image-2",
  "data": [
    { "url": "https://static.imgrouter.com/images/req_01K4.webp" }
  ],
  "usage": { "images": 1 }
}

Synchronous response. The generation endpoint waits for the selected model and returns the completed image URLs in one response.

Authentication

Authenticate every request

Send an ImgRouter API key as a Bearer token. Keys belong on trusted servers and should be loaded from a secret manager or environment variable.

HTTP header

Authorization: Bearer img_live_••••••••••••••••

img_live_stringProduction key. Uses live model routes and the wallet Credit balance.

img_test_stringTest-mode credential for isolated development workflows.

AuthorizationrequiredUse the exact format Bearer <API_KEY> on every request.

Full keys are shown once when created. Revoke a leaked key immediately and create a replacement.

SDK examples

Use your preferred runtime

Call the REST API directly or use an OpenAI-compatible client for the common image generation shape. ImgRouter-specific fields can always be sent through raw JSON.

JavaScript · fetch

const response = await fetch(
  "https://api.imgrouter.com/v1/images/generations",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.IMGROUTER_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "gpt-image-2",
      prompt: "A quiet coastal house at blue hour",
      size: "16:9",
      resolution: "1K",
      n: 1,
    }),
  },
);

const generation = await response.json();

Python · OpenAI SDK

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.imgrouter.com/v1",
    api_key=os.environ["IMGROUTER_API_KEY"],
)

image = client.images.generate(
    model="gpt-image-2",
    prompt="Editorial product photograph, warm studio light",
    size="1536x1024",
)

print(image.data[0].url)

API reference

List available models

Model availability and capabilities can change. Query this endpoint instead of hard-coding supported sizes and resolutions.

GET/v1/models

cURL

curl https://api.imgrouter.com/v1/models \
  -H "Authorization: Bearer $IMGROUTER_API_KEY"

200 response

{
  "object": "list",
  "data": [
    {
      "id": "gpt-image-2",
      "object": "model",
      "display_name": "GPT Image 2",
      "capabilities": {
        "sizes": ["1:1", "16:9", "9:16"],
        "resolutions": ["1K", "2K"],
        "qualities": ["standard", "pro"],
        "max_images": 6,
        "image_edit": true,
        "reference_image": true
      }
    }
  ]
}

idstringStable model identifier used in generation and edit requests.

capabilities.sizesstring[]Supported aspect ratios or size presets.

capabilities.resolutionsstring[]Accepted resolution tiers for this route.

capabilities.max_imagesintegerMaximum number of output images in one request.

capabilities.image_editbooleanWhether the model accepts the edit endpoint.

capabilities.reference_imagebooleanWhether reference image URLs are accepted.

API reference

Generate images

Create one or more images from a prompt. ImgRouter checks the selected model’s options, then reserves Credits and runs the request.

POST/v1/images/generations

cURL

curl https://api.imgrouter.com/v1/images/generations \
  -H "Authorization: Bearer $IMGROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-hero-001" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Editorial product photograph, warm studio light",
    "size": "16:9",
    "resolution": "1K",
    "n": 1
  }'

Request body

modelstring · requiredModel ID returned by GET /v1/models.

promptstring · requiredGeneration instruction between 1 and 5,000 characters.

sizestringAspect ratio or size supported by the selected model.

resolutionstringResolution tier such as 1K, 2K, or 4K when supported.

nintegerNumber of images. Defaults to 1 and cannot exceed max_images.

qualitystringQuality tier advertised in the model capabilities.

backgroundstringUse transparent only on models that support transparency.

seedintegerOptional deterministic seed where supported by the route.

negative_promptstringOptional concepts or visual traits to avoid.

output_formatstringRequested output format where the model supports it.

Response

200 · application/json

{
  "id": "req_01K4…",
  "object": "image.generation",
  "created": 1787424152,
  "model": "gpt-image-2",
  "data": [
    { "url": "https://static.imgrouter.com/images/req_01K4.webp" }
  ],
  "usage": { "images": 1 }
}

API reference

Edit with reference images

Use the same prompt and output controls, plus one or more HTTPS reference image URLs. The selected model must advertise image editing and reference support.

POST/v1/images/edits

cURL

curl https://api.imgrouter.com/v1/images/edits \
  -H "Authorization: Bearer $IMGROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: blue-hour-edit-001" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "Keep the composition and product. Change the scene to blue hour.",
    "reference_images": ["https://example.com/product.jpg"],
    "resolution": "1K",
    "n": 1
  }'

reference_imagesstring[] · requiredOne or more public HTTPS image URLs; maximum 16 across the unified API.

promptstring · requiredDescribe what should change and what must remain consistent.

modelstring · requiredChoose a route with image_edit and reference_image capabilities.

Reference image pricing. Each supplied reference may add a model-specific Credit charge. The current rate appears on the Pricing page before use.

API reference

Inspect a request

Every generation receives a request ID. Use it to reconcile application events with status, image count, timestamps, and settled Credit usage.

GET/v1/requests/{request_id}

cURL

curl https://api.imgrouter.com/v1/requests/req_01K4… \
  -H "Authorization: Bearer $IMGROUTER_API_KEY"

200 response

{
  "id": "req_01K4…",
  "status": "completed",
  "model": "gpt-image-2",
  "image_count": 1,
  "customer_cost": "4.800000",
  "created_at": "2026-08-22T18:30:00Z",
  "completed_at": "2026-08-22T18:30:07Z"
}

Request records are scoped to the authenticated account. A key cannot retrieve another account’s request.

API reference

Check your Credit balance

Retrieve the Credits available to the authenticated API key’s account and the all-time settled usage attributed to that key. Values also include their USD equivalent at the fixed top-up conversion of $1 = 100 Credits.

GET/v1/balance

cURL

curl https://api.imgrouter.com/v1/balance \
  -H "Authorization: Bearer $IMGROUTER_API_KEY"

200 response

{
  "success": true,
  "remain_balance": 25,
  "remain_credits": 2500,
  "used_balance": 1.875,
  "used_credits": 187.5,
  "unlimited_quota": false,
  "currency": "CREDITS"
}

remain_creditsnumberSpendable account Credits after subtracting any active request reservations.

remain_balancenumberUSD-equivalent value of remain_credits at 100 Credits per $1.

used_creditsnumberAll-time settled generation Credits charged through this API key.

used_balancenumberUSD-equivalent value of used_credits at 100 Credits per $1.

unlimited_quotabooleanAlways false for wallet-funded ImgRouter accounts.

currencystringThe accounting unit. Currently CREDITS.

API reference

Aggregate usage

Retrieve completed requests, output image count, and total Credit usage for a UTC time range.

GET/v1/usage?from={ISO_8601}&to={ISO_8601}

fromdate-timeInclusive UTC range start in ISO 8601 format.

todate-timeExclusive UTC range end in ISO 8601 format.

costCredit stringDecimal ImgRouter Credit total; returned as a string for exact accounting.

200 response

{
  "from": "2026-08-01T00:00:00Z",
  "to": "2026-09-01T00:00:00Z",
  "requests": 148,
  "images": 164,
  "cost": "786.400000"
}

Credits & billing

Credits, reservation, and settlement

ImgRouter uses its own Credit unit so small per-image prices remain readable. Top-ups use a fixed conversion and generation rates vary by model, resolution, and quality.

Top-up conversion$1 = 100 Credits

View live model rates

Credit top-ups support Stripe and WeChat. Credits are added only after server-side signed payment confirmation, and duplicate notifications never add Credits twice.

1ValidateCheck model controls and active price.

2ReserveHold the maximum request charge.

3SettleDebit completed images and release the rest.

Failed generations release their reservation and do not charge a successful-generation debit.

Idempotency & retries

Idempotency and safe retries

Attach a unique idempotency key to generation and edit requests that must run once. Keys are scoped to the authenticated user and may be up to 255 characters.

HTTP header

Idempotency-Key: order-4815-hero-v1

400Do not retry unchangedCorrect the parameters, model capability, or content before retrying.

409Wait and retrieveThe same idempotent operation is still in progress.

429Back offRetry with exponential backoff and jitter; reduce concurrency.

502 / 503 / 504Retry safelyUse the same Idempotency-Key and exponential backoff.

Errors

A stable error envelope

All API errors include a machine-readable code, a human-readable message, and a request ID for logging and support.

Error response

{
  "error": {
    "code": "invalid_parameter",
    "message": "resolution is not supported by this model.",
    "request_id": "req_01K4…"
  }
}

400invalid_parameterInvalid field, unsupported option, or rejected content.

401unauthorizedMissing, invalid, or revoked API key.

402insufficient_balanceNot enough available Credits or a limit was reached.

404not_foundModel or request does not exist for this account.

409idempotency_in_progressAn identical operation is still running.

429rate_limit_exceededRequest or concurrency limit was exceeded.

502provider_errorThe selected route returned a non-retryable failure.

503unavailableA route or internal dependency is temporarily unavailable.

504timeoutGeneration did not finish before the request timeout.

Models

Unified image model directory

All models use the same request shape. Query GET /v1/models at runtime for the capabilities currently available to your account.

ModelProviderResolutionCapabilities

GPT Image 2gpt-image-2OpenAI1K2K4KText-to-imageImage-to-imageImage edit

Nano Banana 2nano-banana-2-extGoogle0.5K1K2K4KText-to-imageImage-to-imageImage edit

Nano Banana Pronano-banana-pro-extGoogle1K2K4KText-to-imageImage-to-imageImage edit

Grok Imagine 2.0grok-imagine-2.0-extGrokqualityText-to-imageMulti-image

Grok Imagine Image 2.0grok-imagine-image-2.0Grok1K2KText-to-imageImage-to-imageImage edit

Grok Imagine Image Qualitygrok-imagine-image-qualityGrok1K2KText-to-imageImage-to-imageImage edit

MidjourneymidjourneyMidjourneyText-to-imageImage-to-imageImage edit

One API.The world’s top image models.

Generate your first image

Authenticate every request

Use your preferred runtime

List available models

Generate images

Request body

Response

Edit with reference images

Inspect a request

Check your Credit balance

Aggregate usage

Credits, reservation, and settlement

Idempotency and safe retries

A stable error envelope

Unified image model directory

One API.
The world’s top image models.