Quickstart

This walkthrough creates a text-to-image generation with gemini-3-pro-image, then polls until the image is ready.

1. Create a generation

POST to a generation endpoint. A successful call returns 202 Accepted with a job_id.

curl -s -X POST https://api.moonez.ai/api/v1/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3-pro-image",
    "prompt": "a red panda astronaut floating in a nebula",
    "aspect_ratio": "16:9",
    "resolution": "2K"
  }'

import requests

resp = requests.post(
    "https://api.moonez.ai/api/v1/generations",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "model": "gemini-3-pro-image",
        "prompt": "a red panda astronaut floating in a nebula",
        "aspect_ratio": "16:9",
        "resolution": "2K",
    },
)
job_id = resp.json()["job_id"]

const resp = await fetch("https://api.moonez.ai/api/v1/generations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "gemini-3-pro-image",
    prompt: "a red panda astronaut floating in a nebula",
    aspect_ratio: "16:9",
    resolution: "2K",
  }),
});
const { job_id } = await resp.json();

{
  "job_id": "0193a7f2-1c4a-7e0b-9b3a-2f1d8c6e4a55",
  "status": "queued",
  "status_url": "/api/v1/jobs/0193a7f2-1c4a-7e0b-9b3a-2f1d8c6e4a55"
}

2. Poll until done

Poll GET /jobs/{job_id} until status is done or failed.

curl -s https://api.moonez.ai/api/v1/jobs/$JOB_ID \
  -H "Authorization: Bearer $API_KEY"

import time

while True:
    job = requests.get(
        f"https://api.moonez.ai/api/v1/jobs/{job_id}",
        headers={"Authorization": f"Bearer {API_KEY}"},
    ).json()
    if job["status"] in ("done", "failed"):
        break
    time.sleep(2)

print(job["result"]["image_url"])

let job;
do {
  await new Promise((r) => setTimeout(r, 2000));
  job = await fetch(`https://api.moonez.ai/api/v1/jobs/${job_id}`, {
    headers: { Authorization: `Bearer ${API_KEY}` },
  }).then((r) => r.json());
} while (!["done", "failed"].includes(job.status));

console.log(job.result.image_url);

{
  "job_id": "0193a7f2-1c4a-7e0b-9b3a-2f1d8c6e4a55",
  "status": "done",
  "created_at": "2026-06-11T12:00:00Z",
  "started_at": "2026-06-11T12:00:01Z",
  "finished_at": "2026-06-11T12:00:09Z",
  "result": {
    "image_url": "https://cdn.moonez.ai/results/...?X-Amz-Signature=..."
  },
  "error": null
}

Next steps

Image-to-image

Transform existing images from URLs.

Webhooks

Get notified instead of polling.