Image Generation — Ngamia Docs

Image Generation lets you generate one or more images from a text prompt through a catalog model whose output modality is image. The endpoint is OpenAI-compatible, so existing image-generation clients work against it unmodified. Responses are raw OpenAI shape (no envelope), base64-encoded images, and the generation is billed only on success.

Capability	Endpoint	Response
Generate images	`POST /v1/images/generations`	Base64 image payloads plus billing usage

Image generation is billed in Ngamia credits at each successful request. Generated images are not factual records: review AI-generated content before distributing it, and keep generated assets under the same content policies as any other user media.

Generated image bytes are returned inline as b64_json and expose only the requested rendering. Models, sizes, and output formats vary per upstream provider — pass through parameters are honored only where the selected model supports them.

Generate an image

POST/v1/images/generationsAPI key or JWT

Send a JSON body with the model slug and a prompt. The request is authenticated by API key or JWT, rate-limited, and idempotent for safe replay. model and prompt are required; everything else passes through to the upstream unmodified.

curl -X POST "https://api.ngamia.cc/v1/images/generations" \
  -H "Authorization: Bearer $NGAMIA_API_KEY" \
  -H "Idempotency-Key: cover-art-demo-001" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-image-2",
    "prompt": "A baobab tree at sunset on the Tanzanian savanna",
    "n": 1,
    "size": "1536x864",
    "output_format": "png"
  }'

Field	Required	Description
`model`	Yes	A catalog model whose `output_modalities` includes `image` — refresh `GET /v1/models` for the live list.
`prompt`	Yes	The text description to render.
`n`	No	How many images to generate; `1`–`10`, default `1`.
`size`	No	Passed through to the upstream; honored only if the model supports it.
`output_format`	No	One of `png`, `jpeg`, `webp`, or `svg`; passed through unmodified.
`quality`	No	Passed through to the upstream; honored only if the model supports it.
other parameters	No	`seed`, `background`, and any other upstream parameter pass through unmodified.

A successful response is raw OpenAI shape, no envelope, with base64 images:

{
  "created": 1748372400,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAABAAAA...",
      "media_type": "image/png"
    }
  ],
  "usage": {
    "input_tokens": 20,
    "output_tokens": 196,
    "total_tokens": 216,
    "cost": 0.00598
  }
}

Response field	Description
`created`	Unix timestamp for the generation.
`data[].b64_json`	Base64-encoded image bytes — decode these to get the file.
`data[].media_type`	Image MIME type, for example `image/png`.
`data[].url`	Present only when the upstream returns a URL instead of inline bytes.
`usage`	Usage reported by the upstream — `input_tokens`, `output_tokens`, `total_tokens`, and `cost` (USD). The `cost` value is what gets converted to credits and billed.

Credits and billing

Image generation runs the gateway's normal lifecycle: a conservative credit check happens up front, and the account is settled against the upstream's reported usage.cost at the end, converted to credits by the platform's IMAGE_USD_TO_CREDIT_RATE. Images are charged only on a successful generation — a failed or empty response is logged but never billed. The endpoint rejects models whose output_modalities excludes image up front with a 400 invalid_request_error.

Use the Idempotency-Key header for safe retries: retrying a request keyed to a completed generation will not double-charge.

Errors

Status	Meaning	Action
`400`	Bad prompt, `n`/`size`, or a model without image output	Send a valid prompt and a catalog model advertising `image` output.
`401`	Missing or invalid credential	Refresh the JWT or use a valid server-side API key.
`402`	Insufficient credits	Ask the user to top up through the authenticated payment flow, then retry deliberately.
`404`	Unknown, disabled, or unpriced model	Refresh `GET /v1/models`; do not guess a provider model.
`429`	Rate limit exceeded	Retry with exponential backoff and jitter.
`502`	Upstream image or billable usage failed	Retry only when safe and preserve `request_id`.

Like every other OpenAI-compatible gateway route, failures return JSON errors in OpenAI wire format — always check the HTTP status before trusting a response as a successful generation.

Discover compatible models

Fetch the live catalog and select a record whose output_modalities includes image:

curl https://api.ngamia.cc/v1/models \
  -H "Authorization: Bearer $NGAMIA_API_KEY"

The catalog is paid-only by default and can change as models or prices change. Refresh it when your service starts and when a request returns a model-not-found or unsupported-modality error.

Security and privacy

Keep the API key on your server, not in a browser or mobile bundle. Prompts and generated images may contain sensitive or personal material. Obtain any consent required for your use case, avoid writing prompt text or generated bytes to logs or analytics, encrypt any retained material, apply an expiry, and delete it when no longer needed. Generated images are not verified facts or asset records — review them before publishing and apply the same content rules as any other user media. See Security & data handling.