Image generation

Create a new image from a text prompt.

ImplementedAvailability depends on the selected model being enabled and priced in ApiLux.

Request

POST/images/generations

Requires the Authorization: Bearer apl_... header

Field	Type	Description
`model`required	string	Public model ID whose `kind` is `IMAGE`.
`prompt`required	string	Description of the image. Max 4000 characters.
`size`	string	For example `"1024x1024"`. Only meaningful for models that support it.
`n`	integer	How many images to create, 1–4. Defaults to 1.

Response

Field	Type	Description
`data[].b64_json`required	string	The image as base64. ApiLux always returns base64, never a provider URL.
`data[].mime_type`required	string	For example `image/png`.
`usage.images`required	integer	Number of images charged.
`apilux.credit_charged`required	integer	Credits charged.

Billing

By the number of images actually produced, not the n you requested — some models return a single image regardless.

Examples

cURL

curl https://apilux.net/api/v1/images/generations \
  -H "Authorization: Bearer apl_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 360 \
  -d '{
    "model": "IMAGE_MODEL_ID",
    "prompt": "Giao diện SaaS sáng, tối giản",
    "size": "1024x1024"
  }' \
  | jq -r '.data[0].b64_json' | base64 -d > image.png

Node.js

import { writeFileSync } from "node:fs";

const res = await fetch("https://apilux.net/api/v1/images/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.APILUX_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "IMAGE_MODEL_ID",
    prompt: "Giao diện SaaS sáng, tối giản",
  }),
});
const data = await res.json();
writeFileSync("image.png", Buffer.from(data.data[0].b64_json, "base64"));

Python

import base64, os, requests

res = requests.post(
    "https://apilux.net/api/v1/images/generations",
    headers={"Authorization": f"Bearer {os.environ['APILUX_API_KEY']}"},
    json={"model": "IMAGE_MODEL_ID", "prompt": "Giao diện SaaS sáng, tối giản"},
    timeout=360,
)
with open("image.png", "wb") as f:
    f.write(base64.b64decode(res.json()["data"][0]["b64_json"]))

Errors

HTTP	Code	Meaning
400	`invalid_request`	Invalid body (missing field, wrong type, value out of range).
401	`auth_missing_or_malformed`	Missing `Authorization` header, or it is not in the `Bearer apl_...` form.
401	`auth_invalid`	The API key does not exist.
401	`auth_revoked`	The API key has been revoked.
401	`auth_expired`	The API key has expired.
400	`unknown_model`	The model does not exist on ApiLux.
400	`capability_not_supported`	The model exists but cannot be used on this endpoint (e.g. a text model on an image endpoint).
503	`pricing_not_configured`	The model is implemented but has no price configured on ApiLux yet. This is our state, not a client error.
503	`model_disabled`	The model is currently disabled.
503	`model_temporarily_unavailable`	The model is enabled and priced, but the upstream provider is not currently serving it. This is temporary and can clear on its own — the model reappears in `GET /v1/models` once the provider serves it again. You are not charged and no provider call is made.
402	`insufficient_balance`	Wallet balance is not enough for this request.
429	`api_key_limit_exceeded`	This API key hit a limit you configured yourself. The wallet still has funds — only this key is capped until the window resets. The response carries `limit_type` (`spending` \| `requests` \| `tokens`) and `period` (`daily` \| `monthly` \| `lifetime`). Token limits on text endpoints are measured from actual usage, so the total can exceed the limit by at most one request.
503	`api_key_quota_reconciliation_required`	An earlier text request on this same key has not been reconciled yet. The usual cause: the provider returned a successful result without token usage, so the token limit for that window can no longer be trusted and ApiLux stops rather than let the limit be exceeded silently. Retrying will not help until that is done — contact support. You are not charged for the blocked request, no provider call is made, and image/video endpoints are unaffected.
502	`upstream_error`	The model provider failed. You are not charged.
504	`upstream_timeout`	The provider did not respond in time. You are not charged.
429	`upstream_rate_limited`	Rate limited. Retry after a few seconds.

Notes

Image generation is much slower than chat. Use a client timeout between 180 and 360 seconds.