Generate Image

Image generation is synchronous by default: the API waits for the image and returns its URL directly. Typical latency is a few seconds up to about 30s depending on the model and size.

Supplying a delivery target (callback_url or webhook) switches the call to the asynchronous contract instead — it returns 202 immediately and POSTs the finished image to you. See Async Image Generation for the full guide.

POST /v1/images/generate#

Generate an image from a text prompt. Returns a URL to the image hosted on the PicX CDN.

Auth: API Key

Parameter	Type	Required	Description
prompt	string	Yes	Text description of the image. Required. Maximum 4000 characters.
model	string	No	Model id. Defaults to gemini-3.1-flash-image-preview. See GET /v1/models.
size	string	No	Image quality: 1K, 2K, or 4K. Optional; the API uses 1K when omitted.
aspect_ratio	string	No	Aspect ratio in W:H form, e.g. 16:9, 1:1, or 9:16.
callback_url	string	No	Public HTTPS URL to POST the result to. Supplying this returns 202 instead of 200. Maximum 2048 characters; private and loopback addresses are rejected.
webhook	object	No	Delivery target as {"id": "…"} (a webhook registered in the console) or {"url": "…"} (one-off), with an optional events array. Also returns 202.
idempotency_key	string	No	Body-level twin of the Idempotency-Key header. The header wins if both are sent.

Header	Type	Required	Description
Idempotency-Key	string	No	Deduplicate retried requests. If a request with the same key was already completed, the original response is returned without re-billing credits. 8–128 URL-safe characters.

Response — 200, synchronous (no delivery target)

{
  "id": "img_abc123def456",
  "url": "https://cdn.picxstudio.com/generated/abc123.png",
  "model": "gemini-3.1-flash-image-preview",
  "size": "2K",
  "aspect_ratio": "16:9",
  "credits_used": 53,
  "created_at": "2026-06-17T20:00:00Z"
}

Response — 202, asynchronous (callback_url or webhook supplied)

{
  "id": "d3bfa107-6475-4f5b-ad32-c65c3e1b0377",
  "status": "pending",
  "type": "image",
  "model": "gemini-3.1-flash-image-preview",
  "poll_url": "/v1/generations/d3bfa107-6475-4f5b-ad32-c65c3e1b0377",
  "events_url": "/v1/generations/d3bfa107-6475-4f5b-ad32-c65c3e1b0377/events",
  "webhook": {
    "mode": "legacy_callback",
    "id": null,
    "url": "https://your-server.com/hooks/picx",
    "events": ["generation.completed", "generation.failed"]
  }
}

Generate an image#

JavaScript SDK

npm install picx-ai

import { PicX } from "picx-ai";

const picx = new PicX(process.env.PICX_API_KEY);

const asset = await picx.images.generate({
  prompt: "a cute cat on a windowsill, soft morning light",
  model: "gemini-3.1-flash-image-preview",
  size: "2K",
  aspect_ratio: "16:9",
});

console.log(asset.url);          // hosted CDN URL
console.log(asset.credits_used); // credits billed for this call

Python SDK

pip install picx-ai

import os
from picx import PicX

picx = PicX(os.environ["PICX_API_KEY"])

asset = picx.images.generate(
    prompt="a cute cat on a windowsill, soft morning light",
    model="gemini-3.1-flash-image-preview",
    size="2K",
    aspect_ratio="16:9",
)

print(asset.url)           # hosted CDN URL
print(asset.credits_used)  # credits billed for this call

curl

curl -X POST https://api.picxstudio.com/v1/images/generate \
  -H "Authorization: Bearer pxsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"a cute cat on a windowsill, soft morning light","model":"gemini-3.1-flash-image-preview","size":"2K","aspect_ratio":"16:9"}'

Generate without waiting#

Add callback_url and the call returns as soon as the job is queued. The SDKs return a job handle instead of an image.

const job = await picx.images.generate({
  prompt: "a cute cat on a windowsill",
  callback_url: "https://your-server.com/hooks/picx",
});

console.log(job.id);     // persist this to correlate the delivery
console.log(job.status); // "pending"

job = picx.images.generate(
    "a cute cat on a windowsill",
    callback_url="https://your-server.com/hooks/picx",
)

print(job.id, job.status)

Requires picx-ai 0.3.0 or later. Full details — payload shape, signature verification, retries, and the polling fallback — are in Async Image Generation.

Error handling#

import { PicX, ValidationError, RateLimitError } from "picx-ai";

const picx = new PicX(process.env.PICX_API_KEY);

try {
  const asset = await picx.images.generate({ prompt: "a sunset" });
  console.log(asset.url);
} catch (err) {
  if (err instanceof ValidationError) {
    console.error("Bad params:", err.message);
  } else if (err instanceof RateLimitError) {
    console.error(`Rate limited, retry in ${err.retryAfter}s`);
  } else {
    throw err;
  }
}

Prompt tips: be specific about subject, style, lighting, and composition. Quality cues like "photorealistic", "cinematic", or "4k" help.

If generation fails after credits are deducted, the credits are refunded automatically and the API returns a 500 with error details.

FAQ#

Is image generation synchronous or do I have to poll a job?#

Synchronous. The API waits for the image and returns its hosted URL directly in the response — typically a few seconds, up to about 30s depending on the model and size. There's no job to poll for this endpoint.

What does the API return — a URL or the raw image bytes?#

A URL, hosted on the PicX CDN (cdn.picxstudio.com). The image itself isn't returned inline in the response body.

How do I avoid double-billing if a request times out and I retry it?#

Send an Idempotency-Key header. If a request with the same key already completed, the original response is returned and credits aren't billed again.

What happens to my credits if generation fails?#

They're refunded automatically, and the API returns a 500 with error details — you're never charged for a failed generation.

Which image models are available, and which is used by default?#

gemini-3.1-flash-image-preview is the default when model is omitted. See the list of models for the full set and their credit costs.