Image Generations

The /v1/images/generations endpoint provides unified programmatic image generation across top image synthesis providers, including DALL-E 3, Imagen 3, and partner diffusion models. By funneling vision generation through nRouter, organizations gain automated multi-cloud failover, pre-generation prompt safety inspection, transparent per-image list pricing, and centralized billing.

POST https://api.nrouter.ai/v1/images/generations

Architectural Role & Lifecycle

Generating visual assets demands higher compute latency and distinct unit economics compared to standard text completions. nRouter manages this lifecycle through strict preflight controls:

1. Phase 1: In-Memory Key Auth & Vision Entitlements: Verifies virtual key hash (sk-nrouter-...) and validates tenant authorization for image generation engines.
2. Phase 2: Concurrency & Rate Limit Validation: Validates image generation RPM and concurrent job limits to prevent upstream provider rate exhaustion.
3. Phase 3: Content Moderation & Injection Scoring: Evaluates the image description prompt against safety classifiers. If prompt injection or prohibited content is detected, the request halts with HTTP 400 (x-nr-guardrails: blocked).
4. Phase 4: Per-Image Credit Reservation: Calculates the fixed cost per image based on the model tier, resolution, and quality level, placing an atomic hold on organization credits. Blocked requests incur zero hold and zero spend.
5. Provider Execution & Asset Return: Dispatches the generation job to the upstream provider. When the asset is synthesized, nRouter commits exact spend and stamps full telemetry headers onto the response payload.

Request Parameters

The request body must be a JSON object:

Response Payloads

Standard Image Response

{
  "created": 1700000000,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAYAAAD0eNT6...",
      "revised_prompt": "A modern minimalist server room illuminated in soft neon indigo..."
    }
  ]
}

Headers Reference

Inbound Request Headers

Outbound Response Headers

SDK Code Examples

import { nRouter } from "@nrouter_ai/sdk";
import * as fs from "node:fs";

const client = new nRouter({
  apiKey: process.env.NROUTER_API_KEY,
});

const response = await client.images.generate({
  model: "dall-e-3",
  prompt: "A futuristic enterprise datacenter cooling system with bioluminescent cooling fluid.",
  size: "1024x1024",
  quality: "hd",
  response_format: "b64_json",
});

const imageBase64 = response.data[0].b64_json;
if (imageBase64) {
  await fs.promises.writeFile("datacenter.png", Buffer.from(imageBase64, "base64"));
  console.log("Image saved to datacenter.png");
}

Error Handling & Failure Troubleshooting

{
  "error": {
    "type": "gateway_error",
    "message": "Size 2048x2048 is not supported for model dall-e-3.",
    "code": "invalid_request"
  }
}

curl -X POST "https://example.com/v1/images/generations" \  -H "Content-Type: application/json" \  -d '{    "model": "dall-e-3",    "prompt": "A sleek minimalist server room in deep twilight blue.",    "size": "1024x1024"  }'

{  "created": 1700000000,  "data": [    {      "b64_json": "<base64-png>"    }  ]}