Quick start

Create a key, submit a generation, poll for the result. About ten lines in any language.

Create an API key

Open Settings → API Keys, create a key and copy it. The full key is shown once; store it as FLUX1_API_KEY.

export FLUX1_API_KEY="fx1_live_…"

Submit a generation

Choose a unique Idempotency-Key for this generation. Reuse it with the same body if the response is lost; use a new key only for another generation. See safe retries.

POST /v1/generations

curl https://flux1.ai/api/v1/generations \
  -H "Authorization: Bearer $FLUX1_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: mug-532b29ab-f26e-426f-ab35-281a4ba24db8" \
  -d '{
    "model": "nano-banana-2",
    "prompt": "product photo of a ceramic mug, soft daylight",
    "aspect_ratio": "1:1",
    "resolution": "1K"
  }'

Response

HTTP/1.1 202 Accepted
x-request-id: gen_7Hk2mP9qRtV3wXyZ1aBc4dEf

{
  "id": "gen_7Hk2mP9qRtV3wXyZ1aBc4dEf",
  "status": "queued",
  "model": "nano-banana-2",
  "media_type": "image",
  "credits": 10,
  "credits_refunded": false,
  "input": { "prompt": "product photo of a ceramic mug, soft daylight", "aspect_ratio": "1:1", "resolution": "1K" },
  "output": null,
  "error": null,
  "created_at": "2026-09-06T03:00:00.000Z",
  "completed_at": null
}

Poll until it finishes

Poll the id every 2–3 seconds until status is succeeded or failed, then download from output.images[0].url.

GET /v1/generations/{id}

curl https://flux1.ai/api/v1/generations/gen_7Hk2mP9qRtV3wXyZ1aBc4dEf \
  -H "Authorization: Bearer $FLUX1_API_KEY"

Response when finished

{
  "id": "gen_7Hk2mP9qRtV3wXyZ1aBc4dEf",
  "status": "succeeded",
  "model": "nano-banana-2",
  "media_type": "image",
  "credits": 10,
  "credits_refunded": false,
  "input": { "prompt": "product photo of a ceramic mug, soft daylight", "aspect_ratio": "1:1", "resolution": "1K" },
  "output": {
    "images": [
      { "url": "https://r2.flux1.ai/result-apimart-….png", "width": 1024, "height": 1024 }
    ]
  },
  "error": null,
  "created_at": "2026-09-06T03:00:00.000Z",
  "completed_at": "2026-09-06T03:00:14.000Z"
}

Complete examples

Both examples submit one generation, poll until it leaves queued, and print the first image URL.

generate.mjs (Node.js 18+)

import { randomUUID } from "node:crypto";

const BASE = "https://flux1.ai/api/v1";
const headers = { Authorization: `Bearer ${process.env.FLUX1_API_KEY}` };
// Generate once; save and reuse this value if you retry the POST.
const idempotencyKey = randomUUID();

const submit = await fetch(`${BASE}/generations`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json", "Idempotency-Key": idempotencyKey },
  body: JSON.stringify({
    model: "nano-banana-2",
    prompt: "isometric illustration of a tiny bookshop",
    aspect_ratio: "16:9",
  }),
});
if (!submit.ok) throw new Error((await submit.json()).error.message);
const { id } = await submit.json();

let generation;
do {
  await new Promise((r) => setTimeout(r, 2500));
  generation = await (await fetch(`${BASE}/generations/${id}`, { headers })).json();
} while (generation.status === "queued");

if (generation.status !== "succeeded") throw new Error(generation.error.message);
console.log(generation.output.images[0].url);

Generations lists every request field and what each status means.
Models has the live catalog with prices and allowed aspect ratios.
Errors explains the error envelope and which failures are charged.

Create an API key

Submit a generation

Poll until it finishes

Complete examples

Next

On this page