Image Generation

POST/v1/images/generationsIdempotency-Key optional

POST/v1/images/editsmultipart or JSON · Idempotency-Key optional

Both endpoints return the OpenAI images response shape. Use image-modality models (modality: "image" in /v1/models).

Generations

bash

curl "https://api.smartapihub.com/v1/images/generations" \
  -H "Authorization: Bearer $LLM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7f3d2c9e-order-4821" \
  -d '{
    "model": "openai/dall-e-3",
    "prompt": "An isometric illustration of a data centre at dusk, cyan accents",
    "n": 1,
    "size": "1024x1024",
    "quality": "hd",
    "response_format": "url"
  }'

Field	Type	Notes
`model`	string, required	Image model id.
`prompt`	string ≤ 32,000 chars, required
`n`	integer 1–10	Default 1. Each image is priced separately (`per_image`).
`size`	`WIDTHxHEIGHT`	e.g. `1024x1024`, `1792x1024`. Supported sizes depend on the model.
`quality`	`standard` \| `hd` \| `low` \| `medium` \| `high` \| `auto`	Model-dependent.
`style`	string	Model-dependent (e.g. `vivid`, `natural`).
`response_format`	`url` \| `b64_json`	Default `url`. See below.
`input_images`	string[] ≤ 10	Reference images as `https` URLs or base64 data, for models that accept them. URLs are fetched by the gateway and must pass the SSRF guard (public hosts only).
`user`	string	End-user identifier.
`routing`	object	Routing override.

Edits

Send multipart/form-data with the source image (and optional mask), or JSON with input_images[]:

bash

curl "https://api.smartapihub.com/v1/images/edits" \
  -H "Authorization: Bearer $LLM_API_KEY" \
  -F model="openai/gpt-image-1" \
  -F prompt="Replace the sky with a starry night" \
  -F image=@photo.png \
  -F mask=@mask.png \
  -F n=1 \
  -F size=1024x1024

Multipart fields: image (required), mask, prompt (required), model (required), n, size. Maximum multipart body size is 25 MiB. The JSON alternative accepts the same fields as generations plus input_images for the source image(s).

Response

json

{
  "created": 1725446400,
  "provider": "openai",
  "data": [
    {
      "url": "https://media.example.com/artifacts/…/img_01J6.png?X-Amz-Expires=3600&X-Amz-Signature=…",
      "revised_prompt": "An isometric illustration of a modern data centre at dusk…"
    }
  ],
  "usage": { "images": 1, "x_llm_cost_micro": 80000 }
}

`response_format` and URL expiry

`response_format`	`data[]` item	Notes
`url`	`{ url, revised_prompt? }`	When the operator has configured object storage, the gateway persists the output and returns a signed URL valid for about 1 hour (default). Without storage, the provider's own URL is passed through and its expiry is provider-defined — typically minutes to an hour. Either way: download promptly and store the file yourself if you need it later.
`b64_json`	`{ b64_json, revised_prompt? }`	Base64-encoded image bytes inline. Larger response, no expiry concerns.

revised_prompt is present when the provider rewrote your prompt.

Idempotency

Image requests may include an Idempotency-Key header (≤ 255 characters). Retrying with the same key and identical body returns the stored response with status 200 and the header Idempotent-Replayed: true — no second image is generated or charged. Reusing a key with a different body returns 409 idempotency_conflict; a retry while the original is still running returns 409 with retry_after. See Fallbacks → Idempotency for the full semantics.

Always send an Idempotency-Key when generating images from a job queue or a request handler that might be retried — image generation is expensive and not automatically retried by the gateway after a provider has accepted it.

Errors

HTTP	`code`	Cause
400	`validation_failed`	Bad `size` format, `n` out of range, prompt too long.
400	`ssrf_blocked`	An `input_images` URL points at a private or blocked address.
413	`request_too_large`	Multipart over 25 MiB / JSON over 10 MiB.
415	`unsupported_media_type`	Edits called with an unsupported `Content-Type`.
409	`idempotency_conflict`	Key reused with a different body or still in flight.
402 / 429 / 5xx	see Errors	Budget, rate limit, provider failures.