# Flux1 AI API > REST API for AI image and video generation (Nano Banana, GPT Image, Seedream, Seedance, Veo), billed in the same credits as the Flux1 AI web app. - Base URL: https://flux1.ai/api/v1 - Auth: `Authorization: Bearer $FLUX1_API_KEY` (keys start with `fx1_live_`; call from a server, never a browser) - Flow: `POST /v1/generations` returns `202` with an id; poll `GET /v1/generations/{id}` every 2-3 seconds until `succeeded`, `failed` or `rejected` - Retries: send a unique `Idempotency-Key` per generation and reuse it only with the same body - Models, options and credit prices: `GET /v1/models`; never hard-code a price --- # Flux1 AI API > Build with Nano Banana, GPT Image, Seedream, Seedance and Veo. Generate images and video, edit with references, and track every request through one API. Source: https://flux1.ai/api/docs * **Base URL** `https://flux1.ai/api/v1` * **Authentication** `Authorization: Bearer fx1_live_…` * **Format** JSON request bodies, JSON responses * **Docs for agents** [`/api/docs/llms.txt`](https://flux1.ai/api/docs/llms.txt) — every page as Markdown ## Build with an AI agent Using Claude Code, Cursor or Codex? Hand it the Markdown docs instead of this page. Paste the prompt below, or see [For agents](https://flux1.ai/api/docs/for-agents) for the `AGENTS.md` snippet. - [llms.txt](https://flux1.ai/api/docs/llms.txt): Index of every page with a one-line summary and its Markdown URL. Small; load it first. - [llms-full.txt](https://flux1.ai/api/docs/llms-full.txt): Every page in one file, live model tables and prices included. For long-context models. - [{page}.md](https://flux1.ai/api/docs/quick-start.md): Any docs URL plus .md returns that page as Markdown. The Copy Markdown button copies the same text. ```text Read https://flux1.ai/api/docs/llms.txt first. It lists every Flux1 AI API docs page as Markdown. Open the pages you need before writing code, and answer from those docs only; do not guess field names or prices. Key facts: base URL https://flux1.ai/api/v1. Auth header "Authorization: Bearer $FLUX1_API_KEY", server-side only. POST /v1/generations returns 202 with an id; poll GET /v1/generations/{id} every 2-3 seconds until the status is succeeded, failed or rejected. Send a unique Idempotency-Key with every POST. ``` ## Image models Choose a model for its complete parameter reference, credit prices and ready-to-copy cURL, Node.js and Python examples. - [Nano Banana 2.1](https://flux1.ai/api/docs/image-models/nano-banana-2-1): Google's newest Nano Banana: 1K / 2K / 4K output, up to 14 references and extreme aspect ratios. Example cost: 12 credits / image. - [Nano Banana 2](https://flux1.ai/api/docs/image-models/nano-banana-2): Multi-subject consistency and 1K / 2K / 4K output with extreme aspect ratios. Example cost: 10 credits / image. - [Nano Banana Pro](https://flux1.ai/api/docs/image-models/nano-banana-pro): Native 2K with 4K output, precise typography and composition control. Example cost: 14 credits / image. - [Nano Banana](https://flux1.ai/api/docs/image-models/nano-banana): Fast text-to-image and image editing with strong character consistency. Example cost: 6 credits / image. - [Nano Banana 2 Lite](https://flux1.ai/api/docs/image-models/nano-banana-2-lite): Budget Nano Banana 2 at 1K. Example cost: 6 credits / image. - [GPT Image 2.5](https://flux1.ai/api/docs/image-models/gpt-image-2-5): OpenAI's latest image model: sharp text and precise edits at 1K, 2K or 4K, in Flare or Sunburst. Example cost: 12 credits / image. - [GPT Image 2](https://flux1.ai/api/docs/image-models/gpt-image-2): OpenAI text-to-image and image editing with reliable prompt following. Example cost: 12 credits / image. - [Seedream 5.0 Lite](https://flux1.ai/api/docs/image-models/seedream-5): Text-to-image and reference-image editing with 2K, 3K and 4K output. Example cost: 6 credits / image. Model previews are AI-created concept artwork inspired by each model name, not sample outputs from the listed models. ## Video models - [Seedance 2.0](https://flux1.ai/api/docs/video-models/seedance-2): Text-to-video, first-frame animation and first/last-frame transitions, with optional generated audio. Example cost: 360 credits / video (5s). - [Seedance 2.0 Fast](https://flux1.ai/api/docs/video-models/seedance-2-fast): Text-to-video, first-frame animation and first/last-frame transitions, with optional generated audio. Example cost: 280 credits / video (5s). - [Seedance 2.0 Mini](https://flux1.ai/api/docs/video-models/seedance-2-mini): Text-to-video, first-frame animation and first/last-frame transitions, with optional generated audio. Example cost: 175 credits / video (5s). - [Veo 3.1](https://flux1.ai/api/docs/video-models/veo-3-1): Veo 3.1 Fast and Quality with native audio, text, frame and Fast reference-image generation. Example cost: 200 credits / video (8s). ## How it works Every generation is asynchronous. `POST /v1/generations` validates the request, charges the credits for it, hands the job to the model provider and returns `202 Accepted` with a generation id. You then `GET /v1/generations/{id}` until `status` leaves `queued`. There are no webhooks in v1; polling every 2–3 seconds is the expected pattern. Credits are shared with the web app: the same balance and per-model prices. Pre-debit rejections cost nothing; check `credits_refunded` to confirm a refund. Uncertain submissions may require review. Use [Idempotency-Key](https://flux1.ai/api/docs/generations#idempotency) for retries. Persisted image tasks also appear in [My Images](https://flux1.ai/my-image). > The API is included with every paid plan and credit pack. Create keys at [Settings → API Keys](https://flux1.ai/manage/api-keys) and follow every request under [Settings → API Logs](https://flux1.ai/manage/api-logs). Free and gifted credits alone do not unlock it. ## Where to start - [Quick start](https://flux1.ai/api/docs/quick-start) — Submit your first generation with cURL, Node.js or Python. - [Generations](https://flux1.ai/api/docs/generations) — Create, poll and list generations. Request fields and statuses. - [Models and prices](https://flux1.ai/api/docs/models) — The live catalog with credit prices and option lists. - [For agents](https://flux1.ai/api/docs/for-agents) — llms.txt, Markdown for every page, and rules for your AGENTS.md. --- # Quick start > Create a key, submit a generation, poll for the result. About ten lines in any language. Source: https://flux1.ai/api/docs/quick-start ### Create an API key Open [Settings → API Keys](https://flux1.ai/manage/api-keys), create a key and copy it. The full key is shown once; store it as `FLUX1_API_KEY`. ```bash 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](https://flux1.ai/api/docs/generations#idempotency). ```bash title="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" }' ``` ```http title="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`. ```bash title="GET /v1/generations/{id}" curl https://flux1.ai/api/v1/generations/gen_7Hk2mP9qRtV3wXyZ1aBc4dEf \ -H "Authorization: Bearer $FLUX1_API_KEY" ``` ```json title="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. ### Node.js ```js title="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); ``` ### Python ```python title="generate.py (Python 3, requests)" import os, time, uuid, requests BASE = "https://flux1.ai/api/v1" headers = {"Authorization": f"Bearer {os.environ['FLUX1_API_KEY']}"} # Generate once; save and reuse this value if you retry the POST. idempotency_key = str(uuid.uuid4()) r = requests.post(f"{BASE}/generations", headers={**headers, "Idempotency-Key": idempotency_key}, json={ "model": "nano-banana-pro", "prompt": "a lighthouse at dusk, film grain", "aspect_ratio": "3:2", "resolution": "2K", }) r.raise_for_status() gen_id = r.json()["id"] while True: time.sleep(2.5) g = requests.get(f"{BASE}/generations/{gen_id}", headers=headers).json() if g["status"] != "queued": break if g["status"] != "succeeded": raise RuntimeError(g["error"]["message"]) print(g["output"]["images"][0]["url"]) ``` ## Next * [Generations](https://flux1.ai/api/docs/generations) lists every request field and what each `status` means. * [Models](https://flux1.ai/api/docs/models) has the live catalog with prices and allowed aspect ratios. * [Errors](https://flux1.ai/api/docs/errors) explains the error envelope and which failures are charged. ## Save your result Download the returned image to your own storage before `expires_at`. API results expire 30 days after storage and are automatically cleaned up. A result URL is temporary; see [result retention](https://flux1.ai/api/docs/generations#result-retention). --- # Authentication > Send your key as a bearer token. Keys are shown once, stored hashed, and can be revoked at any time. Source: https://flux1.ai/api/docs/authentication Send your key in the `Authorization` header as a bearer token. For clients migrating from other platforms, `x-api-key: fx1_live_…` is accepted too. ```bash curl https://flux1.ai/api/v1/credits \ -H "Authorization: Bearer $FLUX1_API_KEY" ``` Keys start with `fx1_live_`, are 41 characters long and are stored only as a SHA-256 hash on our side. If you lose one, revoke it and create another; the plaintext cannot be recovered. ## Rules | Rule | Detail | | ----------------------- | --------------------------------------------------------------------------------------------------------------------- | | Who can create keys | Any account with a completed paid credit-pack or subscription purchase. Free and gifted credits alone do not qualify. | | Active keys per account | 5 | | Revocation | Immediate. Requests with a revoked key return `401`; generations already in flight finish normally. | | Scope | A key acts as the account: it can spend credits and read that account's generations and logs, nothing else. | > **Keep keys on your server** > > Never put a key in a browser or a public repo. There is no CORS on the API on purpose; call it from your backend. ## Failed authentication A missing, malformed, unknown or revoked key returns `401` with `error.code` `unauthorized`. An account whose API access was disabled returns `403 api_access_disabled`. Failed attempts are limited to 20 per minute per IP; beyond that you get `429 rate_limited` until the window resets. Manage keys at [Settings → API Keys](https://flux1.ai/manage/api-keys). Every request made with a key, including rejected ones, shows up under [Settings → API Logs](https://flux1.ai/manage/api-logs). ## Access changes Access follows your purchases: any completed paid credit-pack, monthly or yearly subscription purchase unlocks key creation and API calls. Free accounts receive `403 payment_required` even if they have gift credits. Creating a key or starting a new generation requires sufficient credits; reading already-paid results and replaying the same request remain available when the balance reaches zero. We may disable API access for an account that violates the terms of service. Its existing keys then receive `403 api_access_disabled` on subsequent requests; already accepted tasks continue processing. If access is restored, keys that have not been revoked work again; revoked keys stay invalid. Write to [support](mailto:support@flux1.ai) if you believe your account was disabled by mistake. --- # For agents > Point Claude Code, Cursor, Codex or any LLM at Markdown versions of these docs. One index file, one full-text file, and a Markdown URL for every page. Source: https://flux1.ai/api/docs/for-agents Every page in these docs is also served as plain Markdown, with the live model tables, option lists and credit prices written out. Give your coding agent the Markdown, not the HTML: it is smaller, has no navigation chrome, and always matches what the rendered page shows. ## Machine-readable docs - [llms.txt](https://flux1.ai/api/docs/llms.txt): Index of every page with a one-line summary and its Markdown URL. Small; load it first. - [llms-full.txt](https://flux1.ai/api/docs/llms-full.txt): Every page in one file, live model tables and prices included. For long-context models. - [{page}.md](https://flux1.ai/api/docs/quick-start.md): Any docs URL plus .md returns that page as Markdown. The Copy Markdown button copies the same text. ```bash title="Fetch them yourself" curl https://flux1.ai/api/docs/llms.txt curl https://flux1.ai/api/docs/llms-full.txt curl https://flux1.ai/api/docs/image-models/nano-banana-2.md ``` All three are public: no API key, no cookies. They are built from the same source as the HTML pages, so the two never drift apart. ## Paste this prompt Start a session in Claude Code, Cursor, Codex or a chat assistant with this prompt, then ask your question. It sends the agent to the index first, so it opens only the pages it needs. ```text Read https://flux1.ai/api/docs/llms.txt first. It lists every Flux1 AI API docs page as Markdown. Open the pages you need before writing code, and answer from those docs only; do not guess field names or prices. Key facts: base URL https://flux1.ai/api/v1. Auth header "Authorization: Bearer $FLUX1_API_KEY", server-side only. POST /v1/generations returns 202 with an id; poll GET /v1/generations/{id} every 2-3 seconds until the status is succeeded, failed or rejected. Send a unique Idempotency-Key with every POST. ``` On any docs page, **Copy Markdown** copies that page, and **Open in** hands its Markdown URL to ChatGPT, Claude or Cursor. ## Add it to your project's agent rules If the project calls the API, keep the essentials where your agent reads them on every task: `AGENTS.md`, `CLAUDE.md`, or a file in `.cursor/rules/`. ```md title="AGENTS.md" ## Flux1 AI API - Docs: https://flux1.ai/api/docs/llms.txt (Markdown index). Read the page for a model before calling it; do not guess field names. - Base URL: https://flux1.ai/api/v1 - Auth: `Authorization: Bearer $FLUX1_API_KEY`. Server-side only; never ship the key to a browser or commit it. - Generations are async: POST /v1/generations returns 202 and an id. Poll GET /v1/generations/{id} every 2-3 s until status is succeeded, failed or rejected. - Send a unique Idempotency-Key on every POST; reuse it only to retry the same body. - Models, options and credit prices: GET /v1/models. Never hard-code a price. - Results expire 30 days after storage (`expires_at`); download outputs to your own storage. ``` ## What an agent should get right | Topic | Rule | Read | | ------------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | | Keys | Read `FLUX1_API_KEY` from the environment. There is no CORS on the API; calls from a browser fail by design. | [Authentication](https://flux1.ai/api/docs/authentication) | | Request shape | One endpoint for every model. `model` plus that model's fields at the top level of the body. | [Generations](https://flux1.ai/api/docs/generations) | | Waiting | No webhooks in v1. Poll every 2–3 seconds; stop on `succeeded`, `failed` or `rejected`. | [Generations](https://flux1.ai/api/docs/generations) | | Retries | A lost response is retried with the same `Idempotency-Key` and body, never a new key. | [Safe retries](https://flux1.ai/api/docs/generations#idempotency) | | Cost | Credits are charged on submit and refunded on failure. Check `credits_refunded`, not the status alone. | [Credits](https://flux1.ai/api/docs/credits) | | Errors | Branch on `error.code`, not the message text. Back off on `429`. | [Errors](https://flux1.ai/api/docs/errors)
[Rate limits](https://flux1.ai/api/docs/rate-limits) | ## Not available yet There is no MCP server, OpenAPI file or official SDK for the API today. The Markdown above plus `GET /v1/models` cover what those would describe; the [roadmap](https://flux1.ai/api/docs/roadmap) lists what comes next. --- # Models > The live catalog with credit prices, allowed aspect ratios and reference-image limits. Source: https://flux1.ai/api/docs/models `GET /v1/models` returns the live catalog with prices and option lists. The table below is rendered from the same source, so it is always current. | Model id | Type | Credits | Aspect ratios | Reference images | Typical time | | --- | --- | --- | --- | --- | --- | | `seedance-2` (Seedance 2.0) | video | 480p 32 credits / second · 720p 72 credits / second | 16:9 4:3 1:1 3:4 9:16 21:9 | up to 2 | Not yet measured | | `seedance-2-fast` (Seedance 2.0 Fast) | video | 480p 27 credits / second · 720p 56 credits / second | 16:9 4:3 1:1 3:4 9:16 21:9 | up to 2 | Not yet measured | | `seedance-2-mini` (Seedance 2.0 Mini) | video | 480p 16 credits / second · 720p 35 credits / second | 16:9 4:3 1:1 3:4 9:16 21:9 | up to 2 | Not yet measured | | `veo-3-1` (Veo 3.1) | video | fast 200 credits / generation · quality 550 credits / generation | 16:9 9:16 | up to 3 | Not yet measured | | `seedream-5` (Seedream 5.0 Lite) | image | 6 credits / image | 1:1 4:3 3:4 16:9 9:16 2:3 3:2 21:9 | up to 14 | Not yet measured | | `nano-banana` (Nano Banana) | image | 6 credits / image | auto 1:1 2:3 3:2 3:4 4:3 4:5 5:4 9:16 16:9 21:9 | up to 14 | 10–15 s | | `nano-banana-pro` (Nano Banana Pro) | image | 1K 14 · 2K 14 · 4K 28 | auto 1:1 2:3 3:2 3:4 4:3 4:5 5:4 9:16 16:9 21:9 | up to 14 | 10–20 s | | `nano-banana-2` (Nano Banana 2) | image | 1K 10 · 2K 14 · 4K 21 | auto 1:1 2:3 3:2 3:4 4:3 4:5 5:4 9:16 16:9 21:9 1:4 4:1 1:8 8:1 | up to 14 | 10–20 s | | `nano-banana-2-1` (Nano Banana 2.1) | image | 1K 12 · 2K 16 · 4K 21 | auto 1:1 2:3 3:2 3:4 4:3 4:5 5:4 9:16 16:9 21:9 1:4 4:1 1:8 8:1 | up to 14 | 60–90 s | | `nano-banana-2-lite` (Nano Banana 2 Lite) | image | 6 credits / image | auto 1:1 2:3 3:2 3:4 4:3 4:5 5:4 9:16 16:9 21:9 | up to 14 | 8–15 s | | `gpt-image-2-5` (GPT Image 2.5) | image | 1K 12 · 2K 16 · 4K 24 | auto 1:1 16:9 9:16 4:3 3:4 3:2 2:3 5:4 4:5 21:9 | up to 16 | 30–60 s | | `gpt-image-2` (GPT Image 2) | image | 12 credits / image | auto 1:1 2:3 3:2 3:4 4:3 4:5 5:4 9:16 16:9 21:9 2:1 1:2 3:1 1:3 9:21 | up to 15 | 15–30 s | ## Model references - [Nano Banana 2.1](https://flux1.ai/api/docs/image-models/nano-banana-2-1): Google's newest Nano Banana: 1K / 2K / 4K output, up to 14 references and extreme aspect ratios. Example cost: 12 credits / image. - [Nano Banana 2](https://flux1.ai/api/docs/image-models/nano-banana-2): Multi-subject consistency and 1K / 2K / 4K output with extreme aspect ratios. Example cost: 10 credits / image. - [Nano Banana Pro](https://flux1.ai/api/docs/image-models/nano-banana-pro): Native 2K with 4K output, precise typography and composition control. Example cost: 14 credits / image. - [Nano Banana](https://flux1.ai/api/docs/image-models/nano-banana): Fast text-to-image and image editing with strong character consistency. Example cost: 6 credits / image. - [Nano Banana 2 Lite](https://flux1.ai/api/docs/image-models/nano-banana-2-lite): Budget Nano Banana 2 at 1K. Example cost: 6 credits / image. - [GPT Image 2.5](https://flux1.ai/api/docs/image-models/gpt-image-2-5): OpenAI's latest image model: sharp text and precise edits at 1K, 2K or 4K, in Flare or Sunburst. Example cost: 12 credits / image. - [GPT Image 2](https://flux1.ai/api/docs/image-models/gpt-image-2): OpenAI text-to-image and image editing with reliable prompt following. Example cost: 12 credits / image. - [Seedream 5.0 Lite](https://flux1.ai/api/docs/image-models/seedream-5): Text-to-image and reference-image editing with 2K, 3K and 4K output. Example cost: 6 credits / image. - [Seedance 2.0](https://flux1.ai/api/docs/video-models/seedance-2): Text-to-video, first-frame animation and first/last-frame transitions, with optional generated audio. Example cost: 360 credits / video (5s). - [Seedance 2.0 Fast](https://flux1.ai/api/docs/video-models/seedance-2-fast): Text-to-video, first-frame animation and first/last-frame transitions, with optional generated audio. Example cost: 280 credits / video (5s). - [Seedance 2.0 Mini](https://flux1.ai/api/docs/video-models/seedance-2-mini): Text-to-video, first-frame animation and first/last-frame transitions, with optional generated audio. Example cost: 175 credits / video (5s). - [Veo 3.1](https://flux1.ai/api/docs/video-models/veo-3-1): Veo 3.1 Fast and Quality with native audio, text, frame and Fast reference-image generation. Example cost: 200 credits / video (8s). Model previews are AI-created concept artwork inspired by each model name, not sample outputs from the listed models. Prices are credits per generated image and match the web generator. Resolution-priced models default to the cheapest tier when `resolution` is omitted. ```bash curl https://flux1.ai/api/v1/models -H "Authorization: Bearer $FLUX1_API_KEY" ``` ```json title="Response (abridged)" { "data": [ { "id": "nano-banana-2", "label": "Nano Banana 2", "media_type": "image", "parameters": ["prompt", "images", "aspect_ratio", "resolution"], "pricing": { "type": "resolution", "credits": { "1K": 10, "2K": 14, "4K": 21 } }, "constraints": { "aspect_ratios": ["auto", "1:1", …], "resolutions": ["1K", "2K", "4K"], "max_images": 14 }, "estimated_seconds": [10, 20] }, … ] } ``` ## Reading a model entry * `parameters` lists the main request fields. `parameter_details` describes every accepted field with its type, default, allowed values and limits. `example_input` provides a starting point; spread it alongside `model` in the request body. * Seedream 5.0 Lite rejects unknown fields. Its output size is controlled by `quality`, not `resolution`. Nano Banana and GPT Image models ignore unknown fields. * GPT Image 2 is sold at the 1K tier only, so it takes no `resolution`. GPT Image 2.5 adds `version`: `flare` (faster) or `sunburst` (more precise edits), both at the same price. * `pricing.type` is `fixed` (one price) or `resolution` (a price per `resolution` value). * `constraints` carries allowed `aspect_ratios`, `resolutions` or `qualities`, `output_formats` and `max_images` as applicable. Invalid options are rejected with `400 invalid_request` before any credits are charged. `max_images` limits reference images; one output is generated per request. * `estimated_seconds` is a typical range, not a guarantee; `null` means no measured range is published yet. Poll rather than sleep for a fixed time. Seedance 2.0, Fast, Mini and Veo 3.1 appear with `media_type: "video"`. Seedance pricing is per second at the selected resolution; Veo pricing is per generation at the selected Fast/Quality mode. See the model pages for exact supported durations and parameters. --- # Nano Banana 2.1 > Google's newest Nano Banana model. Generate and edit images at 1K, 2K or 4K with up to 14 reference images. Source: https://flux1.ai/api/docs/image-models/nano-banana-2-1 **POST /api/v1/generations** Authorization: `Bearer $FLUX1_API_KEY`. Requires a completed paid purchase; new generations require enough credits. Content-Type: `application/json`. Send an `Idempotency-Key` unique to this generation and reuse it with the same body on retries. See [Safe retries](https://flux1.ai/api/docs/generations#idempotency). Model: `nano-banana-2-1`. One generated image per request. Pricing: {"type":"resolution","credits":{"1K":12,"2K":16,"4K":21}}. per_second prices multiply by duration; mode prices are per generation. Reference images do not add an extra charge. Check credits_refunded to confirm a refund; unresolved submissions may require review. ## Request body Set `model` to `nano-banana-2-1`. Send the following fields alongside `model` at the top level: ### prompt Type: string. Required. Describe the image to create, or the changes to make to your reference images. Whitespace is trimmed. Maximum length: 5000 characters. ### images Type: string[]. Optional. Optional reference images. Use publicly accessible HTTPS URLs or data:image/* base64 URIs (up to 20,000,000 characters per entry). Omit for text-to-image. Maximum items: 14. ### aspect_ratio Type: string. Optional. Output width-to-height ratio. Auto lets the model choose. Default: `auto`. Allowed values: `auto`, `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`, `1:4`, `4:1`, `1:8`, `8:1`. ### resolution Type: string. Optional. Output resolution tier; values are case-insensitive. Omit or leave empty to use the default. Default: `1K`. Allowed values: `1K`, `2K`, `4K`. ## Request examples ### cURL ```bash # Set FLUX1_IDEMPOTENCY_KEY once per generation; reuse it on retries. curl --request POST 'https://flux1.ai/api/v1/generations' \ --header "Authorization: Bearer $FLUX1_API_KEY" \ --header 'Content-Type: application/json' \ --header "Idempotency-Key: ${FLUX1_IDEMPOTENCY_KEY:?Set a unique key for this generation}" \ --data '{ "model": "nano-banana-2-1", "prompt": "A ceramic cup on a linen table, soft morning light", "aspect_ratio": "1:1", "resolution": "1K" }' ``` ### Node.js ```js import { randomUUID } from "node:crypto"; // Generate once per generation. Save and reuse this key when retrying. const idempotencyKey = randomUUID(); const response = await fetch("https://flux1.ai/api/v1/generations", { method: "POST", headers: { Authorization: `Bearer ${process.env.FLUX1_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": idempotencyKey, }, body: JSON.stringify({ "model": "nano-banana-2-1", "prompt": "A ceramic cup on a linen table, soft morning light", "aspect_ratio": "1:1", "resolution": "1K" }), }); const result = await response.json(); if (!response.ok) throw new Error(result.error?.message ?? "Request failed"); console.log(result.id); ``` ### Python ```python import json import os import uuid import requests # Generate once per generation. Save and reuse this key when retrying. idempotency_key = str(uuid.uuid4()) response = requests.post( "https://flux1.ai/api/v1/generations", headers={ "Authorization": f"Bearer {os.environ['FLUX1_API_KEY']}", "Idempotency-Key": idempotency_key, }, json=json.loads("{\n \"model\": \"nano-banana-2-1\",\n \"prompt\": \"A ceramic cup on a linen table, soft morning light\",\n \"aspect_ratio\": \"1:1\",\n \"resolution\": \"1K\"\n}"), timeout=90, ) response.raise_for_status() print(response.json()["id"]) ``` ### Image editing Replace example.com with your publicly accessible reference image URL. ```json { "model": "nano-banana-2-1", "prompt": "Keep the subject and composition. Change the background to a warm ivory studio.", "aspect_ratio": "1:1", "resolution": "1K", "images": [ "https://example.com/reference.png" ] } ``` ## Response ```json { "id": "gen_example", "status": "queued", "model": "nano-banana-2-1", "media_type": "image", "credits": 12, "credits_refunded": false, "input": { "prompt": "A ceramic cup on a linen table, soft morning light", "aspect_ratio": "1:1", "resolution": "1K" }, "output": null, "expires_at": null, "content_expired": false, "error": null, "created_at": "2026-09-07T08:00:00.000Z", "completed_at": null } ``` Poll `GET /api/v1/generations/{id}` every 2–3 seconds until `succeeded` or `failed`. Read `output.images[0].url` on success. Download before expires_at (30 days after storage). Inspect error and credits_refunded on failure. See [Generation lifecycle](https://flux1.ai/api/docs/generations) and [Error reference](https://flux1.ai/api/docs/errors). ## Model notes * `nano-banana-2-1` is Google's Nano Banana 2.1 (released 2026-10-06), the successor to Nano Banana 2. * Choose output size with `resolution`: `1K` (default), `2K` or `4K`. Reference images do not change the price. * `aspect_ratio` accepts `auto`, `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` and the extreme ratios `1:4`, `4:1`, `1:8`, `8:1`. With `auto` and a reference image, the output follows the input's ratio. * Expect about 60–90 seconds per image; poll `GET /v1/generations/{id}` until it finishes. --- # Nano Banana 2 > Generate and edit at 1K, 2K or 4K with up to 14 reference images and a wide range of aspect ratios. Source: https://flux1.ai/api/docs/image-models/nano-banana-2 **POST /api/v1/generations** Authorization: `Bearer $FLUX1_API_KEY`. Requires a completed paid purchase; new generations require enough credits. Content-Type: `application/json`. Send an `Idempotency-Key` unique to this generation and reuse it with the same body on retries. See [Safe retries](https://flux1.ai/api/docs/generations#idempotency). Model: `nano-banana-2`. One generated image per request. Pricing: {"type":"resolution","credits":{"1K":10,"2K":14,"4K":21}}. per_second prices multiply by duration; mode prices are per generation. Reference images do not add an extra charge. Check credits_refunded to confirm a refund; unresolved submissions may require review. ## Request body Set `model` to `nano-banana-2`. Send the following fields alongside `model` at the top level: ### prompt Type: string. Required. Describe the image to create, or the changes to make to your reference images. Whitespace is trimmed. Maximum length: 5000 characters. ### images Type: string[]. Optional. Optional reference images. Use publicly accessible HTTPS URLs or data:image/* base64 URIs (up to 20,000,000 characters per entry). Omit for text-to-image. Maximum items: 14. ### aspect_ratio Type: string. Optional. Output width-to-height ratio. Auto lets the model choose. Default: `auto`. Allowed values: `auto`, `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`, `1:4`, `4:1`, `1:8`, `8:1`. ### resolution Type: string. Optional. Output resolution tier; values are case-insensitive. Omit or leave empty to use the default. Default: `1K`. Allowed values: `1K`, `2K`, `4K`. ## Request examples ### cURL ```bash # Set FLUX1_IDEMPOTENCY_KEY once per generation; reuse it on retries. curl --request POST 'https://flux1.ai/api/v1/generations' \ --header "Authorization: Bearer $FLUX1_API_KEY" \ --header 'Content-Type: application/json' \ --header "Idempotency-Key: ${FLUX1_IDEMPOTENCY_KEY:?Set a unique key for this generation}" \ --data '{ "model": "nano-banana-2", "prompt": "A ceramic cup on a linen table, soft morning light", "aspect_ratio": "1:1", "resolution": "1K" }' ``` ### Node.js ```js import { randomUUID } from "node:crypto"; // Generate once per generation. Save and reuse this key when retrying. const idempotencyKey = randomUUID(); const response = await fetch("https://flux1.ai/api/v1/generations", { method: "POST", headers: { Authorization: `Bearer ${process.env.FLUX1_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": idempotencyKey, }, body: JSON.stringify({ "model": "nano-banana-2", "prompt": "A ceramic cup on a linen table, soft morning light", "aspect_ratio": "1:1", "resolution": "1K" }), }); const result = await response.json(); if (!response.ok) throw new Error(result.error?.message ?? "Request failed"); console.log(result.id); ``` ### Python ```python import json import os import uuid import requests # Generate once per generation. Save and reuse this key when retrying. idempotency_key = str(uuid.uuid4()) response = requests.post( "https://flux1.ai/api/v1/generations", headers={ "Authorization": f"Bearer {os.environ['FLUX1_API_KEY']}", "Idempotency-Key": idempotency_key, }, json=json.loads("{\n \"model\": \"nano-banana-2\",\n \"prompt\": \"A ceramic cup on a linen table, soft morning light\",\n \"aspect_ratio\": \"1:1\",\n \"resolution\": \"1K\"\n}"), timeout=90, ) response.raise_for_status() print(response.json()["id"]) ``` ### Image editing Replace example.com with your publicly accessible reference image URL. ```json { "model": "nano-banana-2", "prompt": "Keep the subject and composition. Change the background to a warm ivory studio.", "aspect_ratio": "1:1", "resolution": "1K", "images": [ "https://example.com/reference.png" ] } ``` ## Response ```json { "id": "gen_example", "status": "queued", "model": "nano-banana-2", "media_type": "image", "credits": 10, "credits_refunded": false, "input": { "prompt": "A ceramic cup on a linen table, soft morning light", "aspect_ratio": "1:1", "resolution": "1K" }, "output": null, "expires_at": null, "content_expired": false, "error": null, "created_at": "2026-09-07T08:00:00.000Z", "completed_at": null } ``` Poll `GET /api/v1/generations/{id}` every 2–3 seconds until `succeeded` or `failed`. Read `output.images[0].url` on success. Download before expires_at (30 days after storage). Inspect error and credits_refunded on failure. See [Generation lifecycle](https://flux1.ai/api/docs/generations) and [Error reference](https://flux1.ai/api/docs/errors). --- # Nano Banana Pro > Generate and edit at 2K or 4K, with control over typography and composition. Source: https://flux1.ai/api/docs/image-models/nano-banana-pro **POST /api/v1/generations** Authorization: `Bearer $FLUX1_API_KEY`. Requires a completed paid purchase; new generations require enough credits. Content-Type: `application/json`. Send an `Idempotency-Key` unique to this generation and reuse it with the same body on retries. See [Safe retries](https://flux1.ai/api/docs/generations#idempotency). Model: `nano-banana-pro`. One generated image per request. Pricing: {"type":"resolution","credits":{"1K":14,"2K":14,"4K":28}}. per_second prices multiply by duration; mode prices are per generation. Reference images do not add an extra charge. Check credits_refunded to confirm a refund; unresolved submissions may require review. ## Request body Set `model` to `nano-banana-pro`. Send the following fields alongside `model` at the top level: ### prompt Type: string. Required. Describe the image to create, or the changes to make to your reference images. Whitespace is trimmed. Maximum length: 5000 characters. ### images Type: string[]. Optional. Optional reference images. Use publicly accessible HTTPS URLs or data:image/* base64 URIs (up to 20,000,000 characters per entry). Omit for text-to-image. Maximum items: 14. ### aspect_ratio Type: string. Optional. Output width-to-height ratio. Auto lets the model choose. Default: `1:1`. Allowed values: `auto`, `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`. ### resolution Type: string. Optional. Output resolution tier; values are case-insensitive. Omit or leave empty to use the default. Default: `2K`. Allowed values: `1K`, `2K`, `4K`. ## Request examples ### cURL ```bash # Set FLUX1_IDEMPOTENCY_KEY once per generation; reuse it on retries. curl --request POST 'https://flux1.ai/api/v1/generations' \ --header "Authorization: Bearer $FLUX1_API_KEY" \ --header 'Content-Type: application/json' \ --header "Idempotency-Key: ${FLUX1_IDEMPOTENCY_KEY:?Set a unique key for this generation}" \ --data '{ "model": "nano-banana-pro", "prompt": "A ceramic cup on a linen table, soft morning light", "aspect_ratio": "1:1", "resolution": "2K" }' ``` ### Node.js ```js import { randomUUID } from "node:crypto"; // Generate once per generation. Save and reuse this key when retrying. const idempotencyKey = randomUUID(); const response = await fetch("https://flux1.ai/api/v1/generations", { method: "POST", headers: { Authorization: `Bearer ${process.env.FLUX1_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": idempotencyKey, }, body: JSON.stringify({ "model": "nano-banana-pro", "prompt": "A ceramic cup on a linen table, soft morning light", "aspect_ratio": "1:1", "resolution": "2K" }), }); const result = await response.json(); if (!response.ok) throw new Error(result.error?.message ?? "Request failed"); console.log(result.id); ``` ### Python ```python import json import os import uuid import requests # Generate once per generation. Save and reuse this key when retrying. idempotency_key = str(uuid.uuid4()) response = requests.post( "https://flux1.ai/api/v1/generations", headers={ "Authorization": f"Bearer {os.environ['FLUX1_API_KEY']}", "Idempotency-Key": idempotency_key, }, json=json.loads("{\n \"model\": \"nano-banana-pro\",\n \"prompt\": \"A ceramic cup on a linen table, soft morning light\",\n \"aspect_ratio\": \"1:1\",\n \"resolution\": \"2K\"\n}"), timeout=90, ) response.raise_for_status() print(response.json()["id"]) ``` ### Image editing Replace example.com with your publicly accessible reference image URL. ```json { "model": "nano-banana-pro", "prompt": "Keep the subject and composition. Change the background to a warm ivory studio.", "aspect_ratio": "1:1", "resolution": "2K", "images": [ "https://example.com/reference.png" ] } ``` ## Response ```json { "id": "gen_example", "status": "queued", "model": "nano-banana-pro", "media_type": "image", "credits": 14, "credits_refunded": false, "input": { "prompt": "A ceramic cup on a linen table, soft morning light", "aspect_ratio": "1:1", "resolution": "2K" }, "output": null, "expires_at": null, "content_expired": false, "error": null, "created_at": "2026-09-07T08:00:00.000Z", "completed_at": null } ``` Poll `GET /api/v1/generations/{id}` every 2–3 seconds until `succeeded` or `failed`. Read `output.images[0].url` on success. Download before expires_at (30 days after storage). Inspect error and credits_refunded on failure. See [Generation lifecycle](https://flux1.ai/api/docs/generations) and [Error reference](https://flux1.ai/api/docs/errors). --- # Nano Banana > Fast text-to-image and reference-image editing. Every accepted parameter, default and price in one place. Source: https://flux1.ai/api/docs/image-models/nano-banana **POST /api/v1/generations** Authorization: `Bearer $FLUX1_API_KEY`. Requires a completed paid purchase; new generations require enough credits. Content-Type: `application/json`. Send an `Idempotency-Key` unique to this generation and reuse it with the same body on retries. See [Safe retries](https://flux1.ai/api/docs/generations#idempotency). Model: `nano-banana`. One generated image per request. Pricing: {"type":"fixed","credits":6}. per_second prices multiply by duration; mode prices are per generation. Reference images do not add an extra charge. Check credits_refunded to confirm a refund; unresolved submissions may require review. ## Request body Set `model` to `nano-banana`. Send the following fields alongside `model` at the top level: ### prompt Type: string. Required. Describe the image to create, or the changes to make to your reference images. Whitespace is trimmed. Maximum length: 5000 characters. ### images Type: string[]. Optional. Optional reference images. Use publicly accessible HTTPS URLs or data:image/* base64 URIs (up to 20,000,000 characters per entry). Omit for text-to-image. Maximum items: 14. ### aspect_ratio Type: string. Optional. Output width-to-height ratio. Auto lets the model choose. Default: `1:1`. Allowed values: `auto`, `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`. ## Request examples ### cURL ```bash # Set FLUX1_IDEMPOTENCY_KEY once per generation; reuse it on retries. curl --request POST 'https://flux1.ai/api/v1/generations' \ --header "Authorization: Bearer $FLUX1_API_KEY" \ --header 'Content-Type: application/json' \ --header "Idempotency-Key: ${FLUX1_IDEMPOTENCY_KEY:?Set a unique key for this generation}" \ --data '{ "model": "nano-banana", "prompt": "A ceramic cup on a linen table, soft morning light", "aspect_ratio": "1:1" }' ``` ### Node.js ```js import { randomUUID } from "node:crypto"; // Generate once per generation. Save and reuse this key when retrying. const idempotencyKey = randomUUID(); const response = await fetch("https://flux1.ai/api/v1/generations", { method: "POST", headers: { Authorization: `Bearer ${process.env.FLUX1_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": idempotencyKey, }, body: JSON.stringify({ "model": "nano-banana", "prompt": "A ceramic cup on a linen table, soft morning light", "aspect_ratio": "1:1" }), }); const result = await response.json(); if (!response.ok) throw new Error(result.error?.message ?? "Request failed"); console.log(result.id); ``` ### Python ```python import json import os import uuid import requests # Generate once per generation. Save and reuse this key when retrying. idempotency_key = str(uuid.uuid4()) response = requests.post( "https://flux1.ai/api/v1/generations", headers={ "Authorization": f"Bearer {os.environ['FLUX1_API_KEY']}", "Idempotency-Key": idempotency_key, }, json=json.loads("{\n \"model\": \"nano-banana\",\n \"prompt\": \"A ceramic cup on a linen table, soft morning light\",\n \"aspect_ratio\": \"1:1\"\n}"), timeout=90, ) response.raise_for_status() print(response.json()["id"]) ``` ### Image editing Replace example.com with your publicly accessible reference image URL. ```json { "model": "nano-banana", "prompt": "Keep the subject and composition. Change the background to a warm ivory studio.", "aspect_ratio": "1:1", "images": [ "https://example.com/reference.png" ] } ``` ## Response ```json { "id": "gen_example", "status": "queued", "model": "nano-banana", "media_type": "image", "credits": 6, "credits_refunded": false, "input": { "prompt": "A ceramic cup on a linen table, soft morning light", "aspect_ratio": "1:1" }, "output": null, "expires_at": null, "content_expired": false, "error": null, "created_at": "2026-09-07T08:00:00.000Z", "completed_at": null } ``` Poll `GET /api/v1/generations/{id}` every 2–3 seconds until `succeeded` or `failed`. Read `output.images[0].url` on success. Download before expires_at (30 days after storage). Inspect error and credits_refunded on failure. See [Generation lifecycle](https://flux1.ai/api/docs/generations) and [Error reference](https://flux1.ai/api/docs/errors). --- # Nano Banana 2 Lite > Budget-friendly 1K image generation and editing with the same asynchronous API. Source: https://flux1.ai/api/docs/image-models/nano-banana-2-lite **POST /api/v1/generations** Authorization: `Bearer $FLUX1_API_KEY`. Requires a completed paid purchase; new generations require enough credits. Content-Type: `application/json`. Send an `Idempotency-Key` unique to this generation and reuse it with the same body on retries. See [Safe retries](https://flux1.ai/api/docs/generations#idempotency). Model: `nano-banana-2-lite`. One generated image per request. Pricing: {"type":"fixed","credits":6}. per_second prices multiply by duration; mode prices are per generation. Reference images do not add an extra charge. Check credits_refunded to confirm a refund; unresolved submissions may require review. ## Request body Set `model` to `nano-banana-2-lite`. Send the following fields alongside `model` at the top level: ### prompt Type: string. Required. Describe the image to create, or the changes to make to your reference images. Whitespace is trimmed. Maximum length: 5000 characters. ### images Type: string[]. Optional. Optional reference images. Use publicly accessible HTTPS URLs or data:image/* base64 URIs (up to 20,000,000 characters per entry). Omit for text-to-image. Maximum items: 14. ### aspect_ratio Type: string. Optional. Output width-to-height ratio. Auto lets the model choose. Default: `auto`. Allowed values: `auto`, `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`. ## Request examples ### cURL ```bash # Set FLUX1_IDEMPOTENCY_KEY once per generation; reuse it on retries. curl --request POST 'https://flux1.ai/api/v1/generations' \ --header "Authorization: Bearer $FLUX1_API_KEY" \ --header 'Content-Type: application/json' \ --header "Idempotency-Key: ${FLUX1_IDEMPOTENCY_KEY:?Set a unique key for this generation}" \ --data '{ "model": "nano-banana-2-lite", "prompt": "A ceramic cup on a linen table, soft morning light", "aspect_ratio": "1:1" }' ``` ### Node.js ```js import { randomUUID } from "node:crypto"; // Generate once per generation. Save and reuse this key when retrying. const idempotencyKey = randomUUID(); const response = await fetch("https://flux1.ai/api/v1/generations", { method: "POST", headers: { Authorization: `Bearer ${process.env.FLUX1_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": idempotencyKey, }, body: JSON.stringify({ "model": "nano-banana-2-lite", "prompt": "A ceramic cup on a linen table, soft morning light", "aspect_ratio": "1:1" }), }); const result = await response.json(); if (!response.ok) throw new Error(result.error?.message ?? "Request failed"); console.log(result.id); ``` ### Python ```python import json import os import uuid import requests # Generate once per generation. Save and reuse this key when retrying. idempotency_key = str(uuid.uuid4()) response = requests.post( "https://flux1.ai/api/v1/generations", headers={ "Authorization": f"Bearer {os.environ['FLUX1_API_KEY']}", "Idempotency-Key": idempotency_key, }, json=json.loads("{\n \"model\": \"nano-banana-2-lite\",\n \"prompt\": \"A ceramic cup on a linen table, soft morning light\",\n \"aspect_ratio\": \"1:1\"\n}"), timeout=90, ) response.raise_for_status() print(response.json()["id"]) ``` ### Image editing Replace example.com with your publicly accessible reference image URL. ```json { "model": "nano-banana-2-lite", "prompt": "Keep the subject and composition. Change the background to a warm ivory studio.", "aspect_ratio": "1:1", "images": [ "https://example.com/reference.png" ] } ``` ## Response ```json { "id": "gen_example", "status": "queued", "model": "nano-banana-2-lite", "media_type": "image", "credits": 6, "credits_refunded": false, "input": { "prompt": "A ceramic cup on a linen table, soft morning light", "aspect_ratio": "1:1" }, "output": null, "expires_at": null, "content_expired": false, "error": null, "created_at": "2026-09-07T08:00:00.000Z", "completed_at": null } ``` Poll `GET /api/v1/generations/{id}` every 2–3 seconds until `succeeded` or `failed`. Read `output.images[0].url` on success. Download before expires_at (30 days after storage). Inspect error and credits_refunded on failure. See [Generation lifecycle](https://flux1.ai/api/docs/generations) and [Error reference](https://flux1.ai/api/docs/errors). --- # GPT Image 2.5 > OpenAI's latest image model. Sharp text and precise edits at 1K, 2K or 4K, with Flare for speed or Sunburst for precision. Source: https://flux1.ai/api/docs/image-models/gpt-image-2-5 **POST /api/v1/generations** Authorization: `Bearer $FLUX1_API_KEY`. Requires a completed paid purchase; new generations require enough credits. Content-Type: `application/json`. Send an `Idempotency-Key` unique to this generation and reuse it with the same body on retries. See [Safe retries](https://flux1.ai/api/docs/generations#idempotency). Model: `gpt-image-2-5`. One generated image per request. Pricing: {"type":"resolution","credits":{"1K":12,"2K":16,"4K":24}}. per_second prices multiply by duration; mode prices are per generation. Reference images do not add an extra charge. Check credits_refunded to confirm a refund; unresolved submissions may require review. ## Request body Set `model` to `gpt-image-2-5`. Send the following fields alongside `model` at the top level: ### prompt Type: string. Required. Describe the image to create, or the changes to make to your reference images. Whitespace is trimmed. Maximum length: 5000 characters. ### images Type: string[]. Optional. Optional reference images. Use publicly accessible HTTPS URLs or data:image/* base64 URIs (up to 20,000,000 characters per entry). Omit for text-to-image. Maximum items: 16. ### aspect_ratio Type: string. Optional. Output width-to-height ratio. Auto lets the model choose. Default: `auto`. Allowed values: `auto`, `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `3:2`, `2:3`, `5:4`, `4:5`, `21:9`. ### resolution Type: string. Optional. Output resolution tier; values are case-insensitive. Omit or leave empty to use the default. Default: `1K`. Allowed values: `1K`, `2K`, `4K`. ### version Type: string. Optional. flare is faster for everyday images and drafts; sunburst makes more precise edits. Both cost the same. Default: `flare`. Allowed values: `flare`, `sunburst`. ## Request examples ### cURL ```bash # Set FLUX1_IDEMPOTENCY_KEY once per generation; reuse it on retries. curl --request POST 'https://flux1.ai/api/v1/generations' \ --header "Authorization: Bearer $FLUX1_API_KEY" \ --header 'Content-Type: application/json' \ --header "Idempotency-Key: ${FLUX1_IDEMPOTENCY_KEY:?Set a unique key for this generation}" \ --data '{ "model": "gpt-image-2-5", "prompt": "A ceramic cup on a linen table, soft morning light", "aspect_ratio": "1:1", "resolution": "1K", "version": "flare" }' ``` ### Node.js ```js import { randomUUID } from "node:crypto"; // Generate once per generation. Save and reuse this key when retrying. const idempotencyKey = randomUUID(); const response = await fetch("https://flux1.ai/api/v1/generations", { method: "POST", headers: { Authorization: `Bearer ${process.env.FLUX1_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": idempotencyKey, }, body: JSON.stringify({ "model": "gpt-image-2-5", "prompt": "A ceramic cup on a linen table, soft morning light", "aspect_ratio": "1:1", "resolution": "1K", "version": "flare" }), }); const result = await response.json(); if (!response.ok) throw new Error(result.error?.message ?? "Request failed"); console.log(result.id); ``` ### Python ```python import json import os import uuid import requests # Generate once per generation. Save and reuse this key when retrying. idempotency_key = str(uuid.uuid4()) response = requests.post( "https://flux1.ai/api/v1/generations", headers={ "Authorization": f"Bearer {os.environ['FLUX1_API_KEY']}", "Idempotency-Key": idempotency_key, }, json=json.loads("{\n \"model\": \"gpt-image-2-5\",\n \"prompt\": \"A ceramic cup on a linen table, soft morning light\",\n \"aspect_ratio\": \"1:1\",\n \"resolution\": \"1K\",\n \"version\": \"flare\"\n}"), timeout=90, ) response.raise_for_status() print(response.json()["id"]) ``` ### Image editing Replace example.com with your publicly accessible reference image URL. ```json { "model": "gpt-image-2-5", "prompt": "Keep the subject and composition. Change the background to a warm ivory studio.", "aspect_ratio": "1:1", "resolution": "1K", "version": "flare", "images": [ "https://example.com/reference.png" ] } ``` ## Response ```json { "id": "gen_example", "status": "queued", "model": "gpt-image-2-5", "media_type": "image", "credits": 12, "credits_refunded": false, "input": { "prompt": "A ceramic cup on a linen table, soft morning light", "aspect_ratio": "1:1", "resolution": "1K", "version": "flare" }, "output": null, "expires_at": null, "content_expired": false, "error": null, "created_at": "2026-09-07T08:00:00.000Z", "completed_at": null } ``` Poll `GET /api/v1/generations/{id}` every 2–3 seconds until `succeeded` or `failed`. Read `output.images[0].url` on success. Download before expires_at (30 days after storage). Inspect error and credits_refunded on failure. See [Generation lifecycle](https://flux1.ai/api/docs/generations) and [Error reference](https://flux1.ai/api/docs/errors). --- # GPT Image 2 > OpenAI text-to-image and image editing at 1K with up to 15 reference images and wide aspect ratios. Source: https://flux1.ai/api/docs/image-models/gpt-image-2 **POST /api/v1/generations** Authorization: `Bearer $FLUX1_API_KEY`. Requires a completed paid purchase; new generations require enough credits. Content-Type: `application/json`. Send an `Idempotency-Key` unique to this generation and reuse it with the same body on retries. See [Safe retries](https://flux1.ai/api/docs/generations#idempotency). Model: `gpt-image-2`. One generated image per request. Pricing: {"type":"fixed","credits":12}. per_second prices multiply by duration; mode prices are per generation. Reference images do not add an extra charge. Check credits_refunded to confirm a refund; unresolved submissions may require review. ## Request body Set `model` to `gpt-image-2`. Send the following fields alongside `model` at the top level: ### prompt Type: string. Required. Describe the image to create, or the changes to make to your reference images. Whitespace is trimmed. Maximum length: 5000 characters. ### images Type: string[]. Optional. Optional reference images. Use publicly accessible HTTPS URLs or data:image/* base64 URIs (up to 20,000,000 characters per entry). Omit for text-to-image. Maximum items: 15. ### aspect_ratio Type: string. Optional. Output width-to-height ratio. Auto lets the model choose. Default: `auto`. Allowed values: `auto`, `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`, `2:1`, `1:2`, `3:1`, `1:3`, `9:21`. ## Request examples ### cURL ```bash # Set FLUX1_IDEMPOTENCY_KEY once per generation; reuse it on retries. curl --request POST 'https://flux1.ai/api/v1/generations' \ --header "Authorization: Bearer $FLUX1_API_KEY" \ --header 'Content-Type: application/json' \ --header "Idempotency-Key: ${FLUX1_IDEMPOTENCY_KEY:?Set a unique key for this generation}" \ --data '{ "model": "gpt-image-2", "prompt": "A ceramic cup on a linen table, soft morning light", "aspect_ratio": "1:1" }' ``` ### Node.js ```js import { randomUUID } from "node:crypto"; // Generate once per generation. Save and reuse this key when retrying. const idempotencyKey = randomUUID(); const response = await fetch("https://flux1.ai/api/v1/generations", { method: "POST", headers: { Authorization: `Bearer ${process.env.FLUX1_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": idempotencyKey, }, body: JSON.stringify({ "model": "gpt-image-2", "prompt": "A ceramic cup on a linen table, soft morning light", "aspect_ratio": "1:1" }), }); const result = await response.json(); if (!response.ok) throw new Error(result.error?.message ?? "Request failed"); console.log(result.id); ``` ### Python ```python import json import os import uuid import requests # Generate once per generation. Save and reuse this key when retrying. idempotency_key = str(uuid.uuid4()) response = requests.post( "https://flux1.ai/api/v1/generations", headers={ "Authorization": f"Bearer {os.environ['FLUX1_API_KEY']}", "Idempotency-Key": idempotency_key, }, json=json.loads("{\n \"model\": \"gpt-image-2\",\n \"prompt\": \"A ceramic cup on a linen table, soft morning light\",\n \"aspect_ratio\": \"1:1\"\n}"), timeout=90, ) response.raise_for_status() print(response.json()["id"]) ``` ### Image editing Replace example.com with your publicly accessible reference image URL. ```json { "model": "gpt-image-2", "prompt": "Keep the subject and composition. Change the background to a warm ivory studio.", "aspect_ratio": "1:1", "images": [ "https://example.com/reference.png" ] } ``` ## Response ```json { "id": "gen_example", "status": "queued", "model": "gpt-image-2", "media_type": "image", "credits": 12, "credits_refunded": false, "input": { "prompt": "A ceramic cup on a linen table, soft morning light", "aspect_ratio": "1:1" }, "output": null, "expires_at": null, "content_expired": false, "error": null, "created_at": "2026-09-07T08:00:00.000Z", "completed_at": null } ``` Poll `GET /api/v1/generations/{id}` every 2–3 seconds until `succeeded` or `failed`. Read `output.images[0].url` on success. Download before expires_at (30 days after storage). Inspect error and credits_refunded on failure. See [Generation lifecycle](https://flux1.ai/api/docs/generations) and [Error reference](https://flux1.ai/api/docs/errors). --- # Seedream 5.0 Lite > Generate and edit images with Seedream 5.0 Lite. Choose 2K, 3K or 4K output, with up to 14 reference images. Source: https://flux1.ai/api/docs/image-models/seedream-5 **POST /api/v1/generations** Authorization: `Bearer $FLUX1_API_KEY`. Requires a completed paid purchase; new generations require enough credits. Content-Type: `application/json`. Send an `Idempotency-Key` unique to this generation and reuse it with the same body on retries. See [Safe retries](https://flux1.ai/api/docs/generations#idempotency). Model: `seedream-5`. One generated image per request. Pricing: {"type":"fixed","credits":6}. per_second prices multiply by duration; mode prices are per generation. Reference images do not add an extra charge. Check credits_refunded to confirm a refund; unresolved submissions may require review. ## Request body Set `model` to `seedream-5`. Send the following fields alongside `model` at the top level: ### prompt Type: string. Required. Describe the image to create or the changes to apply. Whitespace is trimmed; the result must not be empty. Maximum length: 3000 characters. ### images Type: string[]. Optional. Publicly accessible HTTPS image URLs, up to 2,048 characters each. Omit or pass [] for text-to-image; supply references for image editing. JPEG, PNG or WebP, up to 30 MB each (provider limit). Base64 is not accepted. Maximum items: 14. ### aspect_ratio Type: string. Optional. Output width-to-height ratio. Custom dimensions and auto are not supported. Default: `1:1`. Allowed values: `1:1`, `4:3`, `3:4`, `16:9`, `9:16`, `2:3`, `3:2`, `21:9`. ### quality Type: string. Optional. basic → 2K, high → 3K, ultra → 4K. Use this field to choose the resolution tier. Default: `basic`. Allowed values: `basic`, `high`, `ultra`. ### output_format Type: string. Optional. Generated image file format. Default: `png`. Allowed values: `png`, `jpeg`. ## Request examples ### cURL ```bash # Set FLUX1_IDEMPOTENCY_KEY once per generation; reuse it on retries. curl --request POST 'https://flux1.ai/api/v1/generations' \ --header "Authorization: Bearer $FLUX1_API_KEY" \ --header 'Content-Type: application/json' \ --header "Idempotency-Key: ${FLUX1_IDEMPOTENCY_KEY:?Set a unique key for this generation}" \ --data '{ "model": "seedream-5", "prompt": "A ceramic cup on a linen table, soft morning light", "aspect_ratio": "1:1", "quality": "basic", "output_format": "png" }' ``` ### Node.js ```js import { randomUUID } from "node:crypto"; // Generate once per generation. Save and reuse this key when retrying. const idempotencyKey = randomUUID(); const response = await fetch("https://flux1.ai/api/v1/generations", { method: "POST", headers: { Authorization: `Bearer ${process.env.FLUX1_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": idempotencyKey, }, body: JSON.stringify({ "model": "seedream-5", "prompt": "A ceramic cup on a linen table, soft morning light", "aspect_ratio": "1:1", "quality": "basic", "output_format": "png" }), }); const result = await response.json(); if (!response.ok) throw new Error(result.error?.message ?? "Request failed"); console.log(result.id); ``` ### Python ```python import json import os import uuid import requests # Generate once per generation. Save and reuse this key when retrying. idempotency_key = str(uuid.uuid4()) response = requests.post( "https://flux1.ai/api/v1/generations", headers={ "Authorization": f"Bearer {os.environ['FLUX1_API_KEY']}", "Idempotency-Key": idempotency_key, }, json=json.loads("{\n \"model\": \"seedream-5\",\n \"prompt\": \"A ceramic cup on a linen table, soft morning light\",\n \"aspect_ratio\": \"1:1\",\n \"quality\": \"basic\",\n \"output_format\": \"png\"\n}"), timeout=90, ) response.raise_for_status() print(response.json()["id"]) ``` ### Image editing Replace example.com with your publicly accessible reference image URL. ```json { "model": "seedream-5", "prompt": "Keep the subject and composition. Change the background to a warm ivory studio.", "aspect_ratio": "1:1", "quality": "basic", "output_format": "png", "images": [ "https://example.com/reference.png" ] } ``` ## Response ```json { "id": "gen_example", "status": "queued", "model": "seedream-5", "media_type": "image", "credits": 6, "credits_refunded": false, "input": { "prompt": "A ceramic cup on a linen table, soft morning light", "aspect_ratio": "1:1", "quality": "basic", "output_format": "png" }, "output": null, "expires_at": null, "content_expired": false, "error": null, "created_at": "2026-09-07T08:00:00.000Z", "completed_at": null } ``` Poll `GET /api/v1/generations/{id}` every 2–3 seconds until `succeeded` or `failed`. Read `output.images[0].url` on success. Download before expires_at (30 days after storage). Inspect error and credits_refunded on failure. See [Generation lifecycle](https://flux1.ai/api/docs/generations) and [Error reference](https://flux1.ai/api/docs/errors). ## Model notes * `seedream-5` is **Seedream 5.0 Lite**. Seedream 5.0 Pro is a separate model and is not yet available through this API. * Choose output size with `quality`: `basic` produces 2K, `high` produces 3K and `ultra` produces 4K. Choose PNG or JPEG with `output_format`. * Send `prompt`, `images`, `aspect_ratio`, `quality` and `output_format` alongside `model` in the JSON body. Unknown fields are rejected, including `resolution`, `seed`, `n`, `batch_size`, custom dimensions and `webhook_url`. * Omitting `images`, or using an empty array, creates a text-to-image task. Providing 1–14 HTTPS references creates an image-editing task. Base64 input is not accepted by this model. * Content safety checking is enabled. This API produces one image per request; `images` counts references, not outputs. * The final image is saved to Flux storage before the generation is marked successful. A temporary status-query or storage error keeps the task queued for another attempt. --- # Seedance 2.0 > Generate 4–15 second videos from text, a first frame, or first and last frames. Source: https://flux1.ai/api/docs/video-models/seedance-2 **POST /api/v1/generations** Authorization: `Bearer $FLUX1_API_KEY`. Requires a completed paid purchase; new generations require enough credits. Content-Type: `application/json`. Send an `Idempotency-Key` unique to this generation and reuse it with the same body on retries. See [Safe retries](https://flux1.ai/api/docs/generations#idempotency). Model: `seedance-2`. One generated video per request. Pricing: {"type":"per_second","credits":{"480p":32,"720p":72}}. per_second prices multiply by duration; mode prices are per generation. Reference images do not add an extra charge. Check credits_refunded to confirm a refund; unresolved submissions may require review. ## Request body Set `model` to `seedance-2`. Send the following fields alongside `model` at the top level: ### prompt Type: string. Required. Video description, 3–2,000 characters after trimming. Maximum length: 2000 characters. ### first_frame_url Type: string. Optional. Optional public HTTPS image URL (JPEG, PNG or WebP). Omit for text-to-video. Maximum URL length 2,048 characters. ### last_frame_url Type: string. Optional. Optional last-frame HTTPS image URL; requires first_frame_url. Reference video/audio and mixed reference modes are not accepted. ### aspect_ratio Type: string. Optional. Output width-to-height ratio. Default: `16:9`. Allowed values: `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `21:9`. ### resolution Type: string. Optional. Resolution determines the per-second rate. 1080p/4K are not available through this API. Default: `720p`. Allowed values: `480p`, `720p`. ### duration Type: number. Optional. Whole seconds, 4–15 inclusive. Cost is the per-second rate multiplied by this value. Automatic duration (-1) is not accepted. Default: `5`. Range: 4–15; allowed values are specified in the field description. ### generate_audio Type: boolean. Optional. Generate audio with the video. Both audio settings use the same displayed rate. Default: `true`. ## Request examples ### cURL ```bash # Set FLUX1_IDEMPOTENCY_KEY once per generation; reuse it on retries. curl --request POST 'https://flux1.ai/api/v1/generations' \ --header "Authorization: Bearer $FLUX1_API_KEY" \ --header 'Content-Type: application/json' \ --header "Idempotency-Key: ${FLUX1_IDEMPOTENCY_KEY:?Set a unique key for this generation}" \ --data '{ "model": "seedance-2", "prompt": "A paper boat drifting across a quiet pond, slow tracking shot", "resolution": "720p", "duration": 5, "aspect_ratio": "16:9", "generate_audio": true }' ``` ### Node.js ```js import { randomUUID } from "node:crypto"; // Generate once per generation. Save and reuse this key when retrying. const idempotencyKey = randomUUID(); const response = await fetch("https://flux1.ai/api/v1/generations", { method: "POST", headers: { Authorization: `Bearer ${process.env.FLUX1_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": idempotencyKey, }, body: JSON.stringify({ "model": "seedance-2", "prompt": "A paper boat drifting across a quiet pond, slow tracking shot", "resolution": "720p", "duration": 5, "aspect_ratio": "16:9", "generate_audio": true }), }); const result = await response.json(); if (!response.ok) throw new Error(result.error?.message ?? "Request failed"); console.log(result.id); ``` ### Python ```python import json import os import uuid import requests # Generate once per generation. Save and reuse this key when retrying. idempotency_key = str(uuid.uuid4()) response = requests.post( "https://flux1.ai/api/v1/generations", headers={ "Authorization": f"Bearer {os.environ['FLUX1_API_KEY']}", "Idempotency-Key": idempotency_key, }, json=json.loads("{\n \"model\": \"seedance-2\",\n \"prompt\": \"A paper boat drifting across a quiet pond, slow tracking shot\",\n \"resolution\": \"720p\",\n \"duration\": 5,\n \"aspect_ratio\": \"16:9\",\n \"generate_audio\": true\n}"), timeout=90, ) response.raise_for_status() print(response.json()["id"]) ``` ### Image to video Replace example.com with your publicly accessible reference image URL. ```json { "model": "seedance-2", "prompt": "Animate this scene with a slow camera movement", "resolution": "720p", "duration": 5, "aspect_ratio": "16:9", "generate_audio": true, "first_frame_url": "https://example.com/reference.png" } ``` ## Response ```json { "id": "gen_example", "status": "queued", "model": "seedance-2", "media_type": "video", "credits": 360, "credits_refunded": false, "input": { "prompt": "A paper boat drifting across a quiet pond, slow tracking shot", "resolution": "720p", "duration": 5, "aspect_ratio": "16:9", "generate_audio": true }, "output": null, "expires_at": null, "content_expired": false, "error": null, "created_at": "2026-09-07T08:00:00.000Z", "completed_at": null } ``` Poll `GET /api/v1/generations/{id}` every 2–3 seconds until `succeeded` or `failed`. Read `output.video.url` on success. Download before expires_at (30 days after storage). Inspect error and credits_refunded on failure. See [Generation lifecycle](https://flux1.ai/api/docs/generations) and [Error reference](https://flux1.ai/api/docs/errors). ## Model notes * `seedance-2` uses the Seedance 2.0 model. First-frame and first/last-frame modes use the same duration-based price as text-to-video. Audio is optional and does not change the price. * This API offers 480p and 720p only. Reference video/audio inputs, automatic duration, custom callbacks, 1080p and 4K are not accepted. * Resolution names are provider tiers; dimensions and media duration can be rounded by the provider. `output.video.duration` records requested seconds, not an independently measured file duration. * Results are stored in Flux R2 before success. Download the video before `expires_at`, 30 days after storage. No email reminder is sent. * A temporary polling or storage failure leaves the task queued for retry. An ambiguous submission never triggers another provider submission automatically; use the same Idempotency-Key and request ID when checking progress. Provider contract: [KIE Seedance 2](https://docs.kie.ai/market/bytedance/seedance-2). --- # Seedance 2.0 Fast > Seedance Fast video generation with optional audio and per-second pricing. Source: https://flux1.ai/api/docs/video-models/seedance-2-fast **POST /api/v1/generations** Authorization: `Bearer $FLUX1_API_KEY`. Requires a completed paid purchase; new generations require enough credits. Content-Type: `application/json`. Send an `Idempotency-Key` unique to this generation and reuse it with the same body on retries. See [Safe retries](https://flux1.ai/api/docs/generations#idempotency). Model: `seedance-2-fast`. One generated video per request. Pricing: {"type":"per_second","credits":{"480p":27,"720p":56}}. per_second prices multiply by duration; mode prices are per generation. Reference images do not add an extra charge. Check credits_refunded to confirm a refund; unresolved submissions may require review. ## Request body Set `model` to `seedance-2-fast`. Send the following fields alongside `model` at the top level: ### prompt Type: string. Required. Video description, 3–2,000 characters after trimming. Maximum length: 2000 characters. ### first_frame_url Type: string. Optional. Optional public HTTPS image URL (JPEG, PNG or WebP). Omit for text-to-video. Maximum URL length 2,048 characters. ### last_frame_url Type: string. Optional. Optional last-frame HTTPS image URL; requires first_frame_url. Reference video/audio and mixed reference modes are not accepted. ### aspect_ratio Type: string. Optional. Output width-to-height ratio. Default: `16:9`. Allowed values: `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `21:9`. ### resolution Type: string. Optional. Resolution determines the per-second rate. 1080p/4K are not available through this API. Default: `720p`. Allowed values: `480p`, `720p`. ### duration Type: number. Optional. Whole seconds, 4–15 inclusive. Cost is the per-second rate multiplied by this value. Automatic duration (-1) is not accepted. Default: `5`. Range: 4–15; allowed values are specified in the field description. ### generate_audio Type: boolean. Optional. Generate audio with the video. Both audio settings use the same displayed rate. Default: `true`. ## Request examples ### cURL ```bash # Set FLUX1_IDEMPOTENCY_KEY once per generation; reuse it on retries. curl --request POST 'https://flux1.ai/api/v1/generations' \ --header "Authorization: Bearer $FLUX1_API_KEY" \ --header 'Content-Type: application/json' \ --header "Idempotency-Key: ${FLUX1_IDEMPOTENCY_KEY:?Set a unique key for this generation}" \ --data '{ "model": "seedance-2-fast", "prompt": "A paper boat drifting across a quiet pond, slow tracking shot", "resolution": "720p", "duration": 5, "aspect_ratio": "16:9", "generate_audio": true }' ``` ### Node.js ```js import { randomUUID } from "node:crypto"; // Generate once per generation. Save and reuse this key when retrying. const idempotencyKey = randomUUID(); const response = await fetch("https://flux1.ai/api/v1/generations", { method: "POST", headers: { Authorization: `Bearer ${process.env.FLUX1_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": idempotencyKey, }, body: JSON.stringify({ "model": "seedance-2-fast", "prompt": "A paper boat drifting across a quiet pond, slow tracking shot", "resolution": "720p", "duration": 5, "aspect_ratio": "16:9", "generate_audio": true }), }); const result = await response.json(); if (!response.ok) throw new Error(result.error?.message ?? "Request failed"); console.log(result.id); ``` ### Python ```python import json import os import uuid import requests # Generate once per generation. Save and reuse this key when retrying. idempotency_key = str(uuid.uuid4()) response = requests.post( "https://flux1.ai/api/v1/generations", headers={ "Authorization": f"Bearer {os.environ['FLUX1_API_KEY']}", "Idempotency-Key": idempotency_key, }, json=json.loads("{\n \"model\": \"seedance-2-fast\",\n \"prompt\": \"A paper boat drifting across a quiet pond, slow tracking shot\",\n \"resolution\": \"720p\",\n \"duration\": 5,\n \"aspect_ratio\": \"16:9\",\n \"generate_audio\": true\n}"), timeout=90, ) response.raise_for_status() print(response.json()["id"]) ``` ### Image to video Replace example.com with your publicly accessible reference image URL. ```json { "model": "seedance-2-fast", "prompt": "Animate this scene with a slow camera movement", "resolution": "720p", "duration": 5, "aspect_ratio": "16:9", "generate_audio": true, "first_frame_url": "https://example.com/reference.png" } ``` ## Response ```json { "id": "gen_example", "status": "queued", "model": "seedance-2-fast", "media_type": "video", "credits": 280, "credits_refunded": false, "input": { "prompt": "A paper boat drifting across a quiet pond, slow tracking shot", "resolution": "720p", "duration": 5, "aspect_ratio": "16:9", "generate_audio": true }, "output": null, "expires_at": null, "content_expired": false, "error": null, "created_at": "2026-09-07T08:00:00.000Z", "completed_at": null } ``` Poll `GET /api/v1/generations/{id}` every 2–3 seconds until `succeeded` or `failed`. Read `output.video.url` on success. Download before expires_at (30 days after storage). Inspect error and credits_refunded on failure. See [Generation lifecycle](https://flux1.ai/api/docs/generations) and [Error reference](https://flux1.ai/api/docs/errors). Text, first-frame and first/last-frame modes share the displayed price. Only 480p/720p and integer durations of 4–15 seconds are supported. Generated audio is optional and does not add a separate charge. Reference video/audio inputs and automatic duration are not supported. Resolution names are provider tiers. Actual dimensions and media duration can be rounded; `output.video.duration` records the requested seconds. The final video is stored before success and expires 30 days after storage. Download it before `expires_at`; no email reminder is sent. Retry uncertain submissions with the same Idempotency-Key. Provider contract: [KIE Seedance 2 Fast](https://docs.kie.ai/market/bytedance/seedance-2-fast). --- # Seedance 2.0 Mini > Lower-cost Seedance video generation with per-second pricing and optional audio. Source: https://flux1.ai/api/docs/video-models/seedance-2-mini **POST /api/v1/generations** Authorization: `Bearer $FLUX1_API_KEY`. Requires a completed paid purchase; new generations require enough credits. Content-Type: `application/json`. Send an `Idempotency-Key` unique to this generation and reuse it with the same body on retries. See [Safe retries](https://flux1.ai/api/docs/generations#idempotency). Model: `seedance-2-mini`. One generated video per request. Pricing: {"type":"per_second","credits":{"480p":16,"720p":35}}. per_second prices multiply by duration; mode prices are per generation. Reference images do not add an extra charge. Check credits_refunded to confirm a refund; unresolved submissions may require review. ## Request body Set `model` to `seedance-2-mini`. Send the following fields alongside `model` at the top level: ### prompt Type: string. Required. Video description, 3–2,000 characters after trimming. Maximum length: 2000 characters. ### first_frame_url Type: string. Optional. Optional public HTTPS image URL (JPEG, PNG or WebP). Omit for text-to-video. Maximum URL length 2,048 characters. ### last_frame_url Type: string. Optional. Optional last-frame HTTPS image URL; requires first_frame_url. Reference video/audio and mixed reference modes are not accepted. ### aspect_ratio Type: string. Optional. Output width-to-height ratio. Default: `16:9`. Allowed values: `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `21:9`. ### resolution Type: string. Optional. Resolution determines the per-second rate. 1080p/4K are not available through this API. Default: `720p`. Allowed values: `480p`, `720p`. ### duration Type: number. Optional. Whole seconds, 4–15 inclusive. Cost is the per-second rate multiplied by this value. Automatic duration (-1) is not accepted. Default: `5`. Range: 4–15; allowed values are specified in the field description. ### generate_audio Type: boolean. Optional. Generate audio with the video. Both audio settings use the same displayed rate. Default: `true`. ## Request examples ### cURL ```bash # Set FLUX1_IDEMPOTENCY_KEY once per generation; reuse it on retries. curl --request POST 'https://flux1.ai/api/v1/generations' \ --header "Authorization: Bearer $FLUX1_API_KEY" \ --header 'Content-Type: application/json' \ --header "Idempotency-Key: ${FLUX1_IDEMPOTENCY_KEY:?Set a unique key for this generation}" \ --data '{ "model": "seedance-2-mini", "prompt": "A paper boat drifting across a quiet pond, slow tracking shot", "resolution": "720p", "duration": 5, "aspect_ratio": "16:9", "generate_audio": true }' ``` ### Node.js ```js import { randomUUID } from "node:crypto"; // Generate once per generation. Save and reuse this key when retrying. const idempotencyKey = randomUUID(); const response = await fetch("https://flux1.ai/api/v1/generations", { method: "POST", headers: { Authorization: `Bearer ${process.env.FLUX1_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": idempotencyKey, }, body: JSON.stringify({ "model": "seedance-2-mini", "prompt": "A paper boat drifting across a quiet pond, slow tracking shot", "resolution": "720p", "duration": 5, "aspect_ratio": "16:9", "generate_audio": true }), }); const result = await response.json(); if (!response.ok) throw new Error(result.error?.message ?? "Request failed"); console.log(result.id); ``` ### Python ```python import json import os import uuid import requests # Generate once per generation. Save and reuse this key when retrying. idempotency_key = str(uuid.uuid4()) response = requests.post( "https://flux1.ai/api/v1/generations", headers={ "Authorization": f"Bearer {os.environ['FLUX1_API_KEY']}", "Idempotency-Key": idempotency_key, }, json=json.loads("{\n \"model\": \"seedance-2-mini\",\n \"prompt\": \"A paper boat drifting across a quiet pond, slow tracking shot\",\n \"resolution\": \"720p\",\n \"duration\": 5,\n \"aspect_ratio\": \"16:9\",\n \"generate_audio\": true\n}"), timeout=90, ) response.raise_for_status() print(response.json()["id"]) ``` ### Image to video Replace example.com with your publicly accessible reference image URL. ```json { "model": "seedance-2-mini", "prompt": "Animate this scene with a slow camera movement", "resolution": "720p", "duration": 5, "aspect_ratio": "16:9", "generate_audio": true, "first_frame_url": "https://example.com/reference.png" } ``` ## Response ```json { "id": "gen_example", "status": "queued", "model": "seedance-2-mini", "media_type": "video", "credits": 175, "credits_refunded": false, "input": { "prompt": "A paper boat drifting across a quiet pond, slow tracking shot", "resolution": "720p", "duration": 5, "aspect_ratio": "16:9", "generate_audio": true }, "output": null, "expires_at": null, "content_expired": false, "error": null, "created_at": "2026-09-07T08:00:00.000Z", "completed_at": null } ``` Poll `GET /api/v1/generations/{id}` every 2–3 seconds until `succeeded` or `failed`. Read `output.video.url` on success. Download before expires_at (30 days after storage). Inspect error and credits_refunded on failure. See [Generation lifecycle](https://flux1.ai/api/docs/generations) and [Error reference](https://flux1.ai/api/docs/errors). Use text, one first frame or a first/last-frame pair. The API supports 480p/720p and 4–15 whole seconds. Audio is optional at the same price. Multimodal references, automatic duration and custom callbacks are not accepted. Resolution names are provider tiers, not exact pixel guarantees. A verified 4-second 480p request produced an 864×496 H.264 video lasting about 4.04 seconds. `output.video.duration` records the requested duration; the media file can differ slightly due to frame rounding. Results are stored in Flux R2 and expire 30 days later. Download before `expires_at`; no email reminder is sent. Status or storage interruptions keep the request queued. A retry with the same Idempotency-Key does not generate or charge twice. Provider contract: [KIE Seedance 2 Mini](https://docs.kie.ai/market/bytedance/seedance-2-mini). --- # Veo 3.1 > Veo 3.1 Fast and Quality, with text, frames and Fast reference-image generation. Source: https://flux1.ai/api/docs/video-models/veo-3-1 **POST /api/v1/generations** Authorization: `Bearer $FLUX1_API_KEY`. Requires a completed paid purchase; new generations require enough credits. Content-Type: `application/json`. Send an `Idempotency-Key` unique to this generation and reuse it with the same body on retries. See [Safe retries](https://flux1.ai/api/docs/generations#idempotency). Model: `veo-3-1`. One generated video per request. Pricing: {"type":"mode","credits":{"fast":200,"quality":550}}. per_second prices multiply by duration; mode prices are per generation. Reference images do not add an extra charge. Check credits_refunded to confirm a refund; unresolved submissions may require review. ## Request body Set `model` to `veo-3-1`. Send the following fields alongside `model` at the top level: ### prompt Type: string. Required. Describe the video, including desired audio. Must not be empty after trimming. Maximum length: 2000 characters. ### images Type: string[]. Optional. Public HTTPS image URLs. text: none; frames: one first frame or first/last pair; reference: one to three references. Maximum 2,048 characters per URL. Maximum items: 3. ### mode Type: string. Optional. Fast costs 200 credits per generation; Quality costs 550. The same per-generation price applies to 4, 6 and 8 seconds; it is not a per-second price. Default: `fast`. Allowed values: `fast`, `quality`. ### generation_type Type: string. Optional. Select input behavior explicitly. reference requires Fast mode and an 8-second duration. Default: `text`. Allowed values: `text`, `frames`, `reference`. ### aspect_ratio Type: string. Optional. Landscape or portrait output. Auto cropping is not offered. Default: `16:9`. Allowed values: `16:9`, `9:16`. ### resolution Type: string. Optional. 720p output. Higher-resolution upgrades are not included or exposed. Default: `720p`. Allowed values: `720p`. ### duration Type: number. Optional. Exactly 4, 6 or 8 seconds. reference mode only supports 8. Native audio is enabled by the provider; no audio toggle is exposed. Default: `8`. Range: 4–8; allowed values are specified in the field description. ## Request examples ### cURL ```bash # Set FLUX1_IDEMPOTENCY_KEY once per generation; reuse it on retries. curl --request POST 'https://flux1.ai/api/v1/generations' \ --header "Authorization: Bearer $FLUX1_API_KEY" \ --header 'Content-Type: application/json' \ --header "Idempotency-Key: ${FLUX1_IDEMPOTENCY_KEY:?Set a unique key for this generation}" \ --data '{ "model": "veo-3-1", "prompt": "Ocean waves wash onto a beach at sunrise, gentle surf sounds", "mode": "fast", "generation_type": "text", "aspect_ratio": "16:9", "resolution": "720p", "duration": 8 }' ``` ### Node.js ```js import { randomUUID } from "node:crypto"; // Generate once per generation. Save and reuse this key when retrying. const idempotencyKey = randomUUID(); const response = await fetch("https://flux1.ai/api/v1/generations", { method: "POST", headers: { Authorization: `Bearer ${process.env.FLUX1_API_KEY}`, "Content-Type": "application/json", "Idempotency-Key": idempotencyKey, }, body: JSON.stringify({ "model": "veo-3-1", "prompt": "Ocean waves wash onto a beach at sunrise, gentle surf sounds", "mode": "fast", "generation_type": "text", "aspect_ratio": "16:9", "resolution": "720p", "duration": 8 }), }); const result = await response.json(); if (!response.ok) throw new Error(result.error?.message ?? "Request failed"); console.log(result.id); ``` ### Python ```python import json import os import uuid import requests # Generate once per generation. Save and reuse this key when retrying. idempotency_key = str(uuid.uuid4()) response = requests.post( "https://flux1.ai/api/v1/generations", headers={ "Authorization": f"Bearer {os.environ['FLUX1_API_KEY']}", "Idempotency-Key": idempotency_key, }, json=json.loads("{\n \"model\": \"veo-3-1\",\n \"prompt\": \"Ocean waves wash onto a beach at sunrise, gentle surf sounds\",\n \"mode\": \"fast\",\n \"generation_type\": \"text\",\n \"aspect_ratio\": \"16:9\",\n \"resolution\": \"720p\",\n \"duration\": 8\n}"), timeout=90, ) response.raise_for_status() print(response.json()["id"]) ``` ### Image to video Replace example.com with your publicly accessible reference image URL. ```json { "model": "veo-3-1", "prompt": "Animate this scene with a slow camera movement", "mode": "fast", "generation_type": "frames", "aspect_ratio": "16:9", "resolution": "720p", "duration": 8, "images": [ "https://example.com/reference.png" ] } ``` ## Response ```json { "id": "gen_example", "status": "queued", "model": "veo-3-1", "media_type": "video", "credits": 200, "credits_refunded": false, "input": { "prompt": "Ocean waves wash onto a beach at sunrise, gentle surf sounds", "mode": "fast", "generation_type": "text", "aspect_ratio": "16:9", "resolution": "720p", "duration": 8 }, "output": null, "expires_at": null, "content_expired": false, "error": null, "created_at": "2026-09-07T08:00:00.000Z", "completed_at": null } ``` Poll `GET /api/v1/generations/{id}` every 2–3 seconds until `succeeded` or `failed`. Read `output.video.url` on success. Download before expires_at (30 days after storage). Inspect error and credits_refunded on failure. See [Generation lifecycle](https://flux1.ai/api/docs/generations) and [Error reference](https://flux1.ai/api/docs/errors). ## Model notes * The provider's `veo3` and `veo3_fast` identifiers currently select **Veo 3.1**, so the public ID is `veo-3-1`. This does not claim to serve the original Veo 3 model. * Fast costs 200 credits per generation; Quality costs 550, for 4, 6 or 8 seconds. Prices are per request, not per second. Output is 720p with native audio; higher-resolution upgrades are not included. * `text` requires no images. `frames` requires one first frame or a first/last pair. `reference` requires 1–3 images, Fast mode and 8 seconds. * Provider fallback and automatic prompt translation are disabled. This API does not expose Lite, extension, watermark text, an audio toggle or custom callbacks. * Success is returned after the final video is stored in Flux R2. Download before `expires_at`, 30 days after storage. Refunds restore the original credit buckets, and `credits_refunded` confirms completion. Provider contract: [KIE Veo generation](https://docs.kie.ai/veo3-api/generate-veo-3-video). --- # Generations > Create a generation, poll it, list your history. One request shape for every model. Source: https://flux1.ai/api/docs/generations A generation is one request to one model. Its `id` (prefixed `gen_`) is also returned as the `x-request-id` response header and is what you quote to support. ## Create a generation ```http POST /v1/generations ``` Returns `202 Accepted` and a generation object. Check its `status`, `credits` and `credits_refunded`; a replay can return a completed generation, and a submission that was immediately refunded can already be `failed`. | Field | Type | Required | Notes | | --------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `model` | string | yes | One of the ids from [Models](https://flux1.ai/api/docs/models). | | `prompt` | string | yes | 1–3,000 characters for Seedream 5.0 Lite; 1–5,000 for Nano Banana models. | | `images` | string\[] | no | Reference images for editing, up to the model's `max_images`. Seedream accepts HTTPS URLs; Nano Banana also accepts `data:image/…;base64,` URIs. | | `aspect_ratio` | string | no | Model dependent, e.g. `1:1`, `16:9`, `auto`. Defaults to the model's default. | | `resolution` | string | no | `1K`, `2K` or `4K` where the model supports it; changes the price. | | `quality` | string | no | Seedream 5.0 Lite: `basic` (2K, default), `high` (3K), `ultra` (4K). | | `output_format` | string | no | Seedream 5.0 Lite: `png` (default) or `jpeg`. | All request fields are top-level, alongside `model`. Seedream 5.0 Lite rejects unknown fields; Nano Banana models ignore them. See each [model reference](https://flux1.ai/api/docs/models) for its exact contract. Validation failures return `400 invalid_request` with an `issues` array naming each field. ```bash title="Image editing with a reference image" curl https://flux1.ai/api/v1/generations \ -H "Authorization: Bearer $FLUX1_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: portrait-edit-6ee93274-535c-47da-af94-395ac1b92327" \ -d '{ "model": "nano-banana-pro", "prompt": "replace the background with a quiet forest, keep the person unchanged", "images": ["https://example.com/portrait.jpg"], "aspect_ratio": "4:5", "resolution": "2K" }' ``` ## Retry safely with Idempotency-Key Send an `Idempotency-Key` header when creating a generation. Generate one unique value per intended generation and keep that value and the JSON body unchanged across retries. A UUID works well. The header is optional; requests without it are independent and may each generate an image and spend credits. * Keys contain 1–128 printable ASCII characters without spaces. Each API key has its own namespace; changing your API key starts a separate namespace. * The first reserved request owns the key. Repeated requests return the original generation ID and its **current** state, without another debit or provider submission. `x-request-id` is also the original ID. Concurrent retries can initially see `queued` with `credits: 0` while the first request is preparing its debit. * Reusing a key with a different JSON body returns `409 idempotency_conflict`. Object property order does not matter; array order, prompt whitespace, omitted versus explicit defaults, and otherwise ignored fields do matter. The fingerprint covers the full input, including inline images and prompt text omitted from the usage log. * A recorded pre-debit rejection, such as insufficient credits, keeps its original error and request ID on retry. After fixing that condition, use a new key for a new attempt. Validation failures or concurrency rejection before a reservation do not claim the key. * Keys are retained with request records for at least 180 days. After a terminal record is removed, its key can be treated as new. Pending requests and unresolved recovery records remain protected from cleanup. * Replays still require an active API key and an account that can still use the API, and count toward request rate limits. They do not use an additional concurrent generation slot. On a timeout or `500` / `502` / `503`, retry with the **same** key and body, or query the generation ID if you received one. Do not switch to a new key merely because a response was lost. If provider acceptance cannot be confirmed, the original request remains under review; retries do not resend it to the provider. ## Get a generation ```http GET /v1/generations/{id} ``` Returns the current state. The body has the same shape at every stage. `credits` records the actual debit and stays at that amount after a refund; `credits_refunded` records whether the refund completed. | `status` | Meaning | What to do | | ----------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | `queued` | Submission, generation, persistence recovery, or a refund is still pending. | Poll again in 2–3 s. | | `succeeded` | Done. `output.images[]` holds stable URLs on `r2.flux1.ai`. | Download or display. | | `failed` | Generation failed, submission was refunded, or an unresolved submission needs review. | Read `error.message` and `credits_refunded`. Contact support for unresolved submissions before starting another generation. | | `rejected` | The request never became a job (validation, credits, limits). Nothing was charged. | Fix the request; see `error.code`. | ```json title="Failed generation" { "id": "gen_5Qa9…", "status": "failed", "credits": 10, "credits_refunded": true, "output": null, "error": { "code": "generation_failed", "message": "model error" }, … } ``` `completed_at` is recorded when we observe the result, so it is accurate to within your polling interval. ## List generations ```http GET /v1/generations ``` Your account's requests, newest first, including rejected ones. Cursor-paginated. | Query | Notes | | -------- | ---------------------------------------------------- | | `limit` | 1–100, default 20. | | `cursor` | Opaque `next_cursor` from the previous page. | | `status` | Comma-separated: `queued,succeeded,failed,rejected`. | | `model` | Filter by model id. | ```bash curl "https://flux1.ai/api/v1/generations?limit=20&status=failed" \ -H "Authorization: Bearer $FLUX1_API_KEY" ``` ```json title="Response" { "data": [ { "id": "gen_…", "status": "failed", … } ], "next_cursor": "eyJ0IjoiMjAyNi0wOS0wNlQwMjo1ODowMS4wMDBaIiwiaWQiOiJnZW5f…" } ``` `next_cursor` is `null` on the last page. ## Result retention API results are retained for **30 days after successful storage**. Save your files before `expires_at`; polling, downloading and idempotent replays do not extend this date. This applies to API generations only. | Response field | Meaning | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `expires_at` | UTC expiry timestamp, or `null` while no expiry has been assigned (including legacy results awaiting review). | | `content_expired` | `true` at expiry or after cleanup. `input` and `output` are then `null`; the original ID, terminal status and credit information remain. | Deletion runs daily after expiry, removing the stored result and generation content. Direct image URLs may remain accessible until cleanup and CDN cache purging complete; browser copies already downloaded cannot be recalled. Do not use an image URL as permanent storage. The [API Logs](https://flux1.ai/manage/api-logs) page displays the expiry in your local time. Download your results before that date; we do not send email reminders. Expired generations retain an idempotency stub for the original **180-day request-log period**. Replaying the same request with the same key returns that generation without generating or charging again. After the stub's retention period, the key can be treated as new. --- # Credits > The API spends the same credit balance as the web app. Check it, and know when it moves. Source: https://flux1.ai/api/docs/credits `GET /v1/credits` returns the balance the API will draw from. Subscription credits are spent before one-time credits, exactly as in the app. API access comes with any completed paid credit-pack, monthly subscription or yearly subscription purchase. Free or gifted credits alone do not qualify (`403 payment_required`). New generations require the full quoted balance and otherwise return `402 insufficient_credits`. A zero balance does not block reading already-paid results or replaying the same Idempotency-Key; those operations do not start another generation. ```bash curl https://flux1.ai/api/v1/credits -H "Authorization: Bearer $FLUX1_API_KEY" ``` ```json title="Response" { "credits": 1830, "subscription_credits": 1500, "one_time_credits": 330 } ``` ## When the balance changes | Event | Effect on balance | | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Generation reserved | No debit yet; concurrent retries may briefly see `queued` and `credits: 0`. | | Submission starts | Balance and the request's actual `credits` are updated together, before the provider call. | | Request rejected before debit | Nothing charged by this attempt. A conflicting idempotency key does not undo the original request. | | Provider explicitly rejects the submission | Refund attempted automatically. If it is delayed, the generation stays `queued` with the actual debit and `credits_refunded: false`. Polling and background recovery retry it. | | Refund completes | Balance and the refund marker commit together. The generation becomes `failed` with `credits_refunded: true`; `credits` still shows the original debit. | | Image task fails later | The existing task settlement process refunds once and updates `credits_refunded`. | | Provider acceptance is uncertain | No speculative refund or duplicate submission. Keep the same idempotency key and query the original generation; an unresolved request may require support. | An HTTP error alone does not prove that no credits were spent or that a refund completed. Check the original generation's `credits` and `credits_refunded`, and use the same [Idempotency-Key](https://flux1.ai/api/docs/generations#idempotency) when retrying. For example, `credits: 6, credits_refunded: false` means a six-credit debit is still outstanding; after refund, the same record shows `credits: 6, credits_refunded: true`. Each generation records its actual debit, so `GET /v1/generations` doubles as a usage statement. Top up or change plans on the [pricing page](https://flux1.ai/price); new credits are usable by the API the moment the payment settles. --- # Errors > Error codes, safe retries, and how to confirm credit refunds. Source: https://flux1.ai/api/docs/errors Errors use one envelope. `request_id` matches the `x-request-id` header; validation failures add an `issues` array. ```http HTTP/1.1 402 Payment Required x-request-id: gen_9Lm3… { "error": { "code": "insufficient_credits", "message": "Insufficient credits", "request_id": "gen_9Lm3…" } } ``` ```json title="Validation error" { "error": { "code": "invalid_request", "message": "Invalid request body", "request_id": "gen_2Zt0…", "issues": [ { "path": "resolution", "message": "resolution must be one of 1K, 2K, 4K" } ] } } ``` ## Error codes | error.code | HTTP | When | Charged? | | --- | --- | --- | --- | | `unauthorized` | 401 | Missing, malformed, unknown or revoked key. | No | | `api_access_disabled` | 403 | API access was disabled for the account by support. | No | | `payment_required` | 403 | No completed paid credit-pack or subscription purchase. Free or gifted credits alone do not enable API access. | No | | `invalid_request` | 400 | Body is not JSON, a field fails validation, or Idempotency-Key has an invalid format. Validation errors include `issues`. | No | | `model_not_found` | 404 | `model` is missing or not in `/v1/models`. | No | | `insufficient_credits` | 402 | Balance is below the price of this request. | No | | `rate_limited` | 429 | Per-key request rate exceeded. Honour `retry-after`. | No | | `concurrency_limited` | 429 | More than 10 generations still queued for the account. | No | | `provider_error` | 502 | The provider could not accept the request. If submission had already started, read the generation's credits and credits_refunded fields. | Check generation | | `idempotency_conflict` | 409 | The same Idempotency-Key was used with a different body. Use a new key for a new generation. | No additional charge | | `submission_pending` | 503 | The submission outcome could not be confirmed. Retry with the SAME Idempotency-Key or query request_id; do not create a new submission. | May be charged; check generation | | `not_found` | 404 | The generation id does not exist or belongs to another account. | No | | `internal_error` | 500 | Something on our side. Retry with the same Idempotency-Key and backoff; contact support with request_id if it persists. | Check generation; never assume a refund | ## Handling advice * Fix invalid input, authentication, account access, or balance errors before making a new attempt. A reserved request that was rejected before debit keeps its original response on idempotent replay; use a new key after fixing the cause. * `409 idempotency_conflict` means the key already belongs to a different body. Use the original body to retrieve that generation; use a new key only when you intend to create another generation. * Retry `429` after `retry-after`. For timeouts and `500` / `502` / `503`, back off and reuse the **same Idempotency-Key and body**. `503 submission_pending` means the submission state could not be confirmed; query its request ID or retry with that key. * A `202` response is a generation object, which can already be `failed` after a completed refund or an idempotent replay. Read `status`, `error`, `credits`, and `credits_refunded`. A refund awaiting recovery remains `queued`; an HTTP error alone is not proof of a refund. * Keep the generation or `request_id` from unexpected responses so support can trace the request. --- # Rate limits > Per-key request limits, a per-account cap on in-flight generations, and the headers that tell you where you stand. Source: https://flux1.ai/api/docs/rate-limits | Limit | Value | Scope | | --- | --- | --- | | Submissions | 30 / minute | per key | | Reads (poll, list, models, credits) | 300 / minute | per key | | In-flight generations | 10 queued at once | per account (all queued tasks) | | Failed authentications | 20 / minute | per IP | Every authenticated response carries `x-ratelimit-limit`, `x-ratelimit-remaining` and `x-ratelimit-reset` (Unix seconds). A `429` adds `retry-after` in seconds. ## Two kinds of 429 * `rate_limited` means the per-key request rate for this window is used up. Wait for `retry-after` and continue. * `concurrency_limited` means 10 of your generations are still `queued`. Poll and let them finish before submitting more. All queued tasks count, including older tasks. Concurrent submissions reserve capacity before billable work starts. Neither is charged. Need more? [Contact us](mailto:support@flux1.ai) with your use case and expected volume. --- # Logs and retention > Every request is logged with its input, output, credits and timing, and kept for a fixed period. Source: https://flux1.ai/api/docs/logs Every submission, including rejected ones, is visible under [Settings → API Logs](https://flux1.ai/manage/api-logs) with its request id, input, output, credits and timing. The same data is available programmatically through [`GET /v1/generations`](https://flux1.ai/api/docs/generations#list-generations). ## What is stored * The request `input` with prompts truncated to 2,000 characters. * Inline `data:` images in your request are uploaded to our storage and the log stores the resulting URLs, not the base64 payload. * The `output` URLs, the `credits` charged, whether they were refunded, and how long the generation took. * The key that made the request, so a leaked key can be traced and revoked. ## Retention Completed and rejected request records become eligible for daily cleanup after 180 days. Pending generations and requests awaiting a billing review are retained until resolved. This cleanup removes request records; it does not delete generated files from your account library. ## Content expires after 30 days Download API results from [API Logs](https://flux1.ai/manage/api-logs) before the expiry shown in request details. Expired input and output are hidden immediately; daily maintenance removes files and generation content. The request ID, status and credit history remain for the 180-day log period. Web generations are unaffected. See [result retention](https://flux1.ai/api/docs/generations#result-retention) for fields and timing. --- # Roadmap > What is coming next to the API, in order. Source: https://flux1.ai/api/docs/roadmap * **Available now:** [Seedream 5.0 Lite](https://flux1.ai/api/docs/image-models/seedream-5) and the five Nano Banana image models, including [Nano Banana 2.1](https://flux1.ai/api/docs/image-models/nano-banana-2-1). * **Video models:** [Seedance 2.0](https://flux1.ai/api/docs/video-models/seedance-2), Fast, Mini and [Veo 3.1](https://flux1.ai/api/docs/video-models/veo-3-1) use the same endpoint with `media_type: "video"` and `output.video.url`. Veo Lite remains a future addition. * **Seedream 5.0 Pro** will join as a separate image model after its generation and refund flow is integrated. * **Available now:** [Idempotency-Key](https://flux1.ai/api/docs/generations#idempotency) for safe retries of `POST /v1/generations`. * **More models** from the app catalog, one request shape throughout. Questions or a model you need first? Write to [support@flux1.ai](mailto:support@flux1.ai) with your request id.