One image API.
Every production route.
Generate and edit images across leading models through one consistent, authenticated contract. Switch models without rebuilding your integration.
https://api.imgrouter.comv1 stableGenerate 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.
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": "qwen-image-3.0",
"prompt": "Editorial product photograph, warm studio light",
"size": "16:9",
"resolution": "1K",
"n": 1
}'{
"id": "req_01K4…",
"object": "image.generation",
"created": 1787424152,
"model": "qwen-image-3.0",
"data": [
{ "url": "https://static.imgrouter.com/images/req_01K4.webp" }
],
"usage": { "images": 1 }
}Synchronous response. The generation endpoint waits for the routed model and returns the completed image URLs in one response.
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.
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.
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.
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: "qwen-image-3.0",
prompt: "A quiet coastal house at blue hour",
size: "16:9",
resolution: "1K",
n: 1,
}),
},
);
const generation = await response.json();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="qwen-image-3.0",
prompt="Editorial product photograph, warm studio light",
size="1536x1024",
)
print(image.data[0].url)List available models
Model availability and capabilities can change as routes are enabled or disabled. Query this endpoint instead of hard-coding supported sizes and resolutions.
/v1/modelscurl https://api.imgrouter.com/v1/models \
-H "Authorization: Bearer $IMGROUTER_API_KEY"{
"object": "list",
"data": [
{
"id": "qwen-image-3.0",
"object": "model",
"display_name": "Qwen Image 3.0",
"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.Generate images
Create one or more images from a prompt. ImgRouter validates the requested controls against the selected model before reserving Credits or routing the request.
/v1/images/generationscurl 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": "qwen-image-3.0",
"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
{
"id": "req_01K4…",
"object": "image.generation",
"created": 1787424152,
"model": "qwen-image-3.0",
"data": [
{ "url": "https://static.imgrouter.com/images/req_01K4.webp" }
],
"usage": { "images": 1 }
}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.
/v1/images/editscurl 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": "qwen-image-3.0",
"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.
Inspect a request
Every generation receives a request ID. Use it to reconcile application events with status, image count, timestamps, and settled Credit usage.
/v1/requests/{request_id}curl https://api.imgrouter.com/v1/requests/req_01K4… \
-H "Authorization: Bearer $IMGROUTER_API_KEY"{
"id": "req_01K4…",
"status": "completed",
"model": "qwen-image-3.0",
"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.
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.
/v1/balancecurl https://api.imgrouter.com/v1/balance \
-H "Authorization: Bearer $IMGROUTER_API_KEY"{
"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.Aggregate usage
Retrieve completed requests, output image count, and total Credit usage for a UTC time range.
/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.{
"from": "2026-08-01T00:00:00Z",
"to": "2026-09-01T00:00:00Z",
"requests": 148,
"images": 164,
"cost": "786.400000"
}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.
Console top-ups use Stripe Checkout. Credits are added only after the API verifies Stripe’s webhook signature and records the Checkout Session exactly once.
Failed generations release their reservation and do not add a successful-generation debit to the ledger.
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.
Idempotency-Key: order-4815-hero-v1400Do 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.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": {
"code": "invalid_parameter",
"message": "resolution is not supported by this model.",
"request_id": "req_01K4…"
}
}invalid_parameterInvalid field, unsupported option, or rejected content.unauthorizedMissing, invalid, or revoked API key.insufficient_balanceNot enough available Credits or a limit was reached.not_foundModel or request does not exist for this account.idempotency_in_progressAn identical operation is still running.rate_limit_exceededRequest or concurrency limit was exceeded.provider_errorThe selected route returned a non-retryable failure.unavailableA route or internal dependency is temporarily unavailable.timeoutGeneration did not finish before the request timeout.Unified image model directory
All routes use the same core request contract. Query GET /v1/models at runtime for the exact capabilities enabled in your workspace.