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();Authentication
Bearer token. RenderRoute key stays on the server — never in browser bundles, mobile embeds, logs, analytics, or public repos.
Never expose provider keys or RenderRoute keys in frontend code. The production process reads RUNWARE_API_KEY and other credentials from the VPS environment.
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.
| Request | Primary route | Fallback policy |
|---|---|---|
quality=fast | Runware FLUX schnell | Eligible fast providers |
quality=premium | Runware FLUX dev | Eligible premium providers only |
provider=runware | Pinned Runware | No provider failover |
safety_mode=adult | Verified allowlist | Adult-capable providers only |
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.
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.
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.
Errors
Stable error envelope: code, message, request ID, parameter, sanitized attempt markers. Safety rejection never hops to another provider.
{
"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"
]
}
}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 selection | Default model | Role |
|---|---|---|
quality=fast | runware:100@1 | Drafts and responsive generation |
quality=premium | runware:101@1 | Selected final candidates |
provider=auto | Environment route | Operational resilience |
Know what generated the asset
{
"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.