API docs that assume you ship

Image generation API docs
that read like production notes.

Bearer auth. JSON in. URL or base64 out. Fast and premium lanes, 64-grid sizes, idempotency, and errors that don’t send you spelunking through three vendor dashboards.

BASE URLhttps://renderroute.app/v1
HTTPS · JSON · Bearer auth
QUICKSTART

Generate your first image

Keep the API key on your server. The portrait preset is valid across the default provider fleet because both sides are multiples of 64.

curl https://renderroute.app/v1/images/generations \
  -H "Authorization: Bearer $RENDERROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: asset-4821-fast-v1" \
  -d '{
    "prompt": "Editorial product portrait on a warm stone pedestal",
    "quality": "fast",
    "width": 960,
    "height": 1472,
    "n": 1,
    "response_format": "url"
  }'
import httpx

payload = {
    "prompt": "Editorial product portrait on a warm stone pedestal",
    "quality": "fast",
    "width": 960,
    "height": 1472,
}
response = httpx.post(
    "https://renderroute.app/v1/images/generations",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Idempotency-Key": "asset-4821-fast-v1",
    },
    json=payload,
    timeout=90,
)
response.raise_for_status()
result = response.json()
const response = await fetch(
  "https://renderroute.app/v1/images/generations",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.RENDERROUTE_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": "asset-4821-fast-v1"
    },
    body: JSON.stringify({
      prompt: "Editorial product portrait on a warm stone pedestal",
      quality: "fast",
      width: 960,
      height: 1472
    })
  }
);
if (!response.ok) throw new Error(await response.text());
const result = await response.json();
02

Authentication

Bearer token. RenderRoute key stays on the server — never in browser bundles, mobile embeds, logs, analytics, or public repos.

Secret handling

Never expose provider keys or RenderRoute keys in frontend code. The production process reads RUNWARE_API_KEY and other credentials from the VPS environment.

03

Quality and routing

quality=fast for drafts and volume. quality=premium for concepts that earned it. provider=auto keeps failover; pinning a provider trades that for an exact integration target.

RequestPrimary routeFallback policy
quality=fastRunware FLUX schnellEligible fast providers
quality=premiumRunware FLUX devEligible premium providers only
provider=runwarePinned RunwareNo provider failover
safety_mode=adultVerified allowlistAdult-capable providers only
04

Dimensions

Width and height must land on multiples of 64. Auto-adjust can snap near-misses and reports both requested and final size in metadata.

NORMALIZED1024 × 1472nearest multiples of 64
05

Idempotency

Send Idempotency-Key on anything a client might retry. Same key + same body returns the stored result. Same key + different body returns a conflict — not a second bill by accident.

Key scope

Use one key per logical operation and request version, such as asset:4821:premium:v2. Do not reuse a fast key for a premium payload.

06

Errors

Stable error envelope: code, message, request ID, parameter, sanitized attempt markers. Safety rejection never hops to another provider.

Error envelopejson
{
  "error": {
    "code": "providers_exhausted",
    "message": "All eligible image providers are temporarily unavailable.",
    "request_id": "req_...",
    "provider_attempts": [
      "runware:provider_timeout",
      "together:provider_http_error",
      "leonardo:provider_timeout"
    ]
  }
}
MODELS

Model abstraction and pinning

Most applications should ask for fast or premium. Exact provider IDs remain available for evaluations and workflows that require an approved implementation.

Public selectionDefault modelRole
quality=fastrunware:100@1Drafts and responsive generation
quality=premiumrunware:101@1Selected final candidates
provider=autoEnvironment routeOperational resilience
Inspect live model metadata →
RESPONSE

Know what generated the asset

200 responsejson
{
  "created": 1784145600,
  "data": [{ "url": "https://.../image.webp" }],
  "meta": {
    "request_id": "req_01...",
    "provider": "runware",
    "provider_model": "runware:100@1",
    "quality": "fast",
    "safety_mode": "standard",
    "width": 960,
    "height": 1472,
    "requested_width": 960,
    "requested_height": 1472,
    "dimensions_adjusted": false,
    "duration_ms": 348,
    "fallback_used": false,
    "attempts": ["runware:success"],
    "estimated_provider_cost_usd": 0.0006
  }
}

The duration and cost shown here are illustrative. Live responses contain measured wall-clock duration and provider-reported or configured cost estimates.