Image Generation

Generate high-quality images from text prompts using nano-banana-2. Each job is async and billed at $0.013 per image. No daily cap.

Overview

The Image API generates images from natural-language prompts. Submit a job and poll for completion — or configure a webhook to receive the image.completed event automatically.

Pricing is simple: $0.013 per image. Generating a batch of 4 costs $0.052. There is no daily generation cap — only your balance limits usage.

Batch (n)	Cost
1 image	$0.013
2 images	$0.026
4 images	$0.052

Quick Start

# Submit image generation job
curl -X POST https://getvrex.com/api/v1/images \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A serene mountain lake at sunset with reflections",
    "n": 1,
    "size": "1024x1024"
  }'

# Poll for completion
curl https://getvrex.com/api/v1/images/{id} \
  -H "Authorization: Bearer sk-your-api-key"

Typical generation completes in 10–30 seconds. Poll every 2 seconds or use webhooks for zero-latency notification.

API Reference

POST/images

Submit an async image generation job.

Request Body

Name	Type	Required	Default	Description
prompt	string	Required	—	Text description of the image to generate. 1–2000 characters.
n	number	Optional	1	Number of images to generate in one job. Range: 1–4.
size	string	Optional	1024x1024	Output dimensions. One of: "1024x1024", "1280x720", "720x1280", "1920x1080".
model	string	Optional	nano-banana-2	Model to use. Currently fixed to "nano-banana-2".
seed	number	Optional	—	Reproducibility seed (integer). Omit for a random/non-deterministic result.
ref_images	string[]	Optional	—	Image-to-image (i2i): up to 4 reference images. Each item a data URL or HTTPS image URL, max 4 MB. Omit for plain text-to-image.
webhook_url	string	Optional	—	HTTPS URL to receive image.completed and image.failed events.
output_format	string	Optional	url	Response shape for image URLs. One of: "url" (presigned), "raw_key" (R2 object key).

Response (202 Accepted)

202Image generation job queued

{
  "id": "ig_a1b2c3d4e5f6",
  "status": "queued",
  "estimated_cost_usd": 0.013,
  "queue_position": 2,
  "poll_url": "/api/v1/images/ig_a1b2c3d4e5f6"
}

Errors

Code	Status	Description
VALIDATION_ERROR	400	Invalid request (prompt missing, n out of range, bad size, malformed ref_images/seed)
MINOR_SAFETY / ARTIST_IMPERSONATION / HATE_SPEECH	400	Prompt blocked by the acceptable-use policy (one of these specific codes)
INSUFFICIENT_BALANCE_FOR_IMAGE	402	Insufficient balance. Please top up your account.
WALLET_NOT_FOUND	404	No billing wallet exists yet for the account (top up to initialise)
QUEUE_FULL	429	Image generation queue at capacity (sends Retry-After)
DAILY_CAP_REACHED	429	Per-tier daily image cap reached (resets midnight UTC)
UPLOAD_ERROR / CREDIT_ERROR / INTERNAL_ERROR	500	Failed to process a ref image, charge, or create the job
FEATURE_DISABLED	503	Image generation is temporarily disabled

GET/images/:id

Poll the status of an image generation job.

Response

200Image generation status

{
  "id": "ig_a1b2c3d4e5f6",
  "status": "completed",
  "n": 1,
  "size": "1024x1024",
  "model": "nano-banana-2",
  "image_urls": [
    "https://r2.getvrex.com/image-gen/..."
  ],
  "cost_usd": 0.013,
  "actual_cost_usd": 0.013,
  "error": null,
  "created_at": "2025-01-01T12:00:00.000Z",
  "completed_at": "2025-01-01T12:00:20.000Z"
}

Possible statuses: pending, queued, processing, completed, failed

image_urls is an array of presigned download URLs (valid 1 hour). One URL per image in the batch. null until status is completed.

Webhook Event

Set webhook_url in the POST request to receive image.completed and image.failed events. Your server must respond with 2xx within 10 seconds. Note: webhook field names differ from the GET response (image_gen_id, n_returned, actual_cost_usd; no status).

200image.completed webhook payload

{
  "event": "image.completed",
  "image_gen_id": "ig_a1b2c3d4e5f6",
  "image_urls": [
    "https://r2.getvrex.com/image-gen/..."
  ],
  "n_returned": 1,
  "actual_cost_usd": 0.013,
  "timestamp": "2025-01-01T12:00:20.000Z"
}

200image.failed webhook payload (charge refunded in full)

{
  "event": "image.failed",
  "image_gen_id": "ig_a1b2c3d4e5f6",
  "error": "Flow engine generateImage failed: HTTP 502",
  "timestamp": "2025-01-01T12:00:20.000Z"
}

FAQ

How long does image generation take?

Typical generation completes in 10–30 seconds. Batch jobs (n=4) may take up to 60 seconds.

Are failed generations refunded?

Yes. If a generation fails after the balance is charged, the amount is automatically refunded.

How long are image URLs valid?

Presigned URLs expire after 1 hour. Re-fetch the job status to get fresh URLs after expiry.

What happens if my prompt is rejected?

Prompts that violate the acceptable-use policy are rejected with a 400 error carrying a specific code (MINOR_SAFETY, ARTIST_IMPERSONATION, or HATE_SPEECH). No charge is made.