Images

Endpoint

POST https://llm.nimbusapi.net/v1/images/generations

Parameters

Model catalog

Prices are the pass-through cost debited from your key balance. Nimbus does not mark up image generation.

Request body

{
  "model": "google/gemini-3-pro-image",
  "prompt": "A wide-angle photorealistic shot of an alpine cabin at golden hour, warm interior light spilling onto pine snow, hyperreal detail, cinematic depth of field",
  "n": 2,
  "size": "1536x1024",
  "quality": "high",
  "style": "natural",
  "response_format": "url",
  "user": "internal-user-4711"
}

Response — URL

Default response_format. Each image lives at a signed Nimbus CDN URL for 24 hours. Fetch and persist within that window if you need long-term storage.

{
  "created": 1735689600,
  "model": "google/gemini-3-pro-image",
  "data": [
    {
      "url": "https://cdn.nimbusapi.net/img/2026-07-01/01H9K7Z2Q4T5N6Y7B8M9F0G1H2-0.png",
      "revised_prompt": "Ultra-wide photorealistic photograph of an alpine cabin at golden hour, warm amber interior light spilling out through mullioned windows onto fresh pine-shadowed snow, cinematic shallow depth of field."
    },
    {
      "url": "https://cdn.nimbusapi.net/img/2026-07-01/01H9K7Z2Q4T5N6Y7B8M9F0G1H2-1.png",
      "revised_prompt": "..."
    }
  ],
  "usage": {
    "images": 2,
    "cost_usd": 0.16
  }
}

• revised_prompt — the actual prompt the model used after any safety rewriting. Log this alongside the request_id for reproducibility.
• usage.cost_usd — the exact amount debited from your key balance for this call.

Response — b64_json

Set response_format: "b64_json" to get the PNG inline as base64. Useful when you never want the image to touch the Nimbus CDN — e.g. compliance workloads. Response bodies are larger; expect ~1.4 MB per 1024x1024 image.

{
  "created": 1735689600,
  "model": "openai/gpt-5-image",
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA... (truncated) ...ggg==",
      "revised_prompt": "..."
    }
  ],
  "usage": { "images": 1, "cost_usd": 0.04 }
}

Basic call

curl -sS https://llm.nimbusapi.net/v1/images/generations \
  -H "Authorization: Bearer $NIMBUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5-image",
    "prompt": "A minimalist product shot of a matte-black hexagonal speaker on a warm concrete surface, soft window light from left",
    "n": 1,
    "size": "1024x1024",
    "quality": "standard"
  }'

Billing

Each successful image debits usage.cost_usd from the key balance. Failed generations (safety block, upstream error, invalid size) are never billed. If a request asks for n: 4 and one is refused by the safety filter, you are billed only for the images actually returned. The per-key USD spend cap (see /docs/authentication) applies here identically to chat completions.

Edge cases

• CDN URLs expire. All response_format: url links are signed and expire 24 hours after generation. Download and re-host any image you plan to serve to your own users.
• Size must match model. Requesting 2048x2048 on gpt-5-image-mini returns 400 unsupported_size. Use the Model catalog table above.
• Aspect ratio caveats. Gemini models handle 1536x1024 natively; OpenAI GPT-Image uses 1792x1024 for the same aspect ratio. Pick per-model.
• Safety refusals. When a prompt is refused, Nimbus returns 403 forbidden with code: policy_violation. No image, no billing. The error message names the category that triggered.
• Timeouts. High-quality 2048 images can take 25–40s upstream. Set your client HTTP timeout to at least 90s for image workloads.
• Batches vs parallel. Using n: 4 in one request is more cost-efficient than 4 parallel requests — Nimbus batches at the upstream when the model supports it.

Error codes

• 400 invalid_request — code: unsupported_size when the requested size is not in the model's catalog.
• 400 invalid_request — code: prompt_too_long when prompt exceeds 4000 characters.
• 402 insufficient_balance — key balance below the estimated cost. Estimated cost is n * per_image_rate.
• 403 forbidden — code: policy_violation when the safety filter rejects the prompt.
• 503 model_unavailable — every mirror for the requested image model is unhealthy. Fall back to a sibling (see catalog).