API Reference

v1

OpenAI-compatible REST API for image and video generation.

Base URL

https://api.fluxpool.ai/v1

The Fluxpool API follows the OpenAI API format. If you're using the OpenAI SDK, change the base URL and API key — everything else works.

Need an API key? Start your 1-month trial → New here? Start with the Quickstart guide →

Use from an AI agent (MCP)

Agent-native

Skip the REST wiring — give your Claude, Cursor, or any Model Context Protocol agent direct access to Fluxpool tools. Ask the agent to run the two commands below and you're done.

Using Claude? Add https://mcp.fluxpool.ai/mcp as a custom connector and sign in with your Fluxpool account. No API key and nothing to install.

1

Install the MCP server

Tell your agent — run this yourself, or paste to your agent to run for you:

bash

npx -y @fluxpool/mcp-server

2

Add your API key

Grab a key from the API / MCP Access page in the app, then drop it into your MCP client's config:

claude_desktop_config.json

{
  "mcpServers": {
    "fluxpool": {
      "command": "npx",
      "args": ["-y", "@fluxpool/mcp-server"],
      "env": {
        "FLUXPOOL_API_KEY": "fp_live_YOUR_KEY_HERE"
      }
    }
  }
}

3

Ask the agent to generate

Restart the client, then just ask:

"Generate an image of a red panda skateboarding at sunset with Fluxpool. Use flux-2-pro."

Six tools become callable from the agent: list_models, create_generation, check_generation, get_generation_details, list_library, get_balance.

Full MCP guide — Claude web, Cursor, other clients →

Authentication

All requests require an API key passed in the Authorization header.

Header

Authorization: Bearer fp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys look like fp_live_ followed by 40 hex characters. Generate them in the app on the API / MCP Access page. See the Authentication guide for details.

Images

Image Generation

POST `/v1/images/generations`

Try in Playground →

Generate an image from a text prompt.

Request Body

Parameter	Type	Required	Default	Description
model	string	Yes	—	Model ID. See available models.
prompt	string	Yes	—	Text description of the image to generate.
size	string	No	"1024x1024"	Output dimensions. Options vary by model.
parameters.aspect_ratio	string	No	null	Explicit aspect ratio override (e.g. "16:9"). Overrides `size`.
parameters.negative_prompt	string	No	null	What to exclude from the image. Passed through to models that support it.
parameters.seed	integer	No	Random	Reproducibility seed (model-dependent).
inputs	object[]	No	null	Preferred shape for reference inputs. Each item is `{type, source, value}` where `type` is `"image"`, `"video"`, or `"audio"`, and `source` is `"url"` (https:// pass-through) or `"data"` (base64 data-URI, uploaded inline; ~4.5MB decoded cap). See Image-to-Image.
input_images	string[]	No	null	Legacy. Prefer `inputs`. Array of https:// URLs for image-to-image; kept for backwards compatibility with existing callers.
edit_mode	string	No	null	Editing-mode flag for supported edit-capable models.

Example Request

from openai import OpenAI

client = OpenAI(
    base_url="https://api.fluxpool.ai/v1",
    api_key="fp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
)

response = client.images.generate(
    model="flux-2-pro",
    prompt="A dragon perched on a neon-lit Tokyo rooftop at midnight, cinematic lighting, 8K",
    size="1024x1024"
)

print(response.data[0].url)

curl -X POST https://api.fluxpool.ai/v1/images/generations \
  -H "Authorization: Bearer fp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-2-pro",
    "prompt": "A dragon perched on a neon-lit Tokyo rooftop at midnight, cinematic lighting, 8K",
    "size": "1024x1024",
    "n": 1
  }'

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.fluxpool.ai/v1",
  apiKey: "fp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
});

const response = await client.images.generate({
  model: "flux-2-pro",
  prompt: "A dragon perched on a neon-lit Tokyo rooftop at midnight, cinematic lighting, 8K",
  size: "1024x1024",
});

console.log(response.data[0].url);

Response

JSON

{
  "created": 1785845810,
  "id": "6dcc89ce-964e-466e-8100-ba2bdfb6d07c",
  "status": "pending",
  "model": "flux-2-pro",
  "type": "image",
  "data": [
    {
      "url": "https://fluxpool-output.s3.ap-southeast-1.amazonaws.com/...?X-Amz-...",
      "generation_id": "6dcc89ce-964e-466e-8100-ba2bdfb6d07c",
      "status": "pending",
      "model": "flux-2-pro",
      "revised_prompt": null
    }
  ]
}

Response Fields

Field	Type	Description
id	string	Generation ID. Use to poll `GET /v1/generations/{id}`.
status	string	One of `pending`, `processing`, `completed`, `failed`.
created	integer	Unix timestamp the request was accepted.
type	string	`"image"` for this endpoint.
data[].url	string	Presigned S3 URL. Becomes fetchable once the generation completes; expires 1 hour after issue.
data[].revised_prompt	string	Model-revised prompt, if applicable. Usually `null`.
model	string	Model used for generation.

Supported Image Models

seedream-5.0seedream-5.0-flashflux-2-maxflux-2-proflux-2-kleinqwen-image-2.0-proqwen-image-max

Live catalog: GET /v1/models. See the Models Reference →

Errors

Status	Code	Description
400	invalid_request	Missing or invalid parameters.
401	authentication_error	Invalid or missing API key.
402	insufficient_credits	Not enough credits. Top up →
404	model_not_found	Requested model does not exist.
429	CONCURRENCY_LIMIT_REACHED	All of your plan's generations are running. See limits.
500	server_error	Internal error. Retry or contact support.

Polling image generations

Images and videos share the same status endpoint: GET /v1/generations/{id}. Or poll the presigned S3 URL from data[0].url directly with a byte-range GET.

Field	Type	Description
id	string	Unique generation ID.
status	string	"pending", "processing", "completed", or "failed".
created	integer	Unix timestamp.
model	string	Model used.
prompt	string	Original prompt.
data	array	Array of output objects (same as creation response).
usage.credits_used	integer	Credits consumed.

Videos

Video Generation

POST `/v1/videos/generations`

Try in Playground →

Generate a video from a text prompt. Videos are generated asynchronously.

⚡ Async generation. The initial response returns a generation ID with status "pending". Poll the GET endpoint or use webhooks to receive the completed video.

Request Body

Parameter	Type	Required	Default	Description
model	string	Yes	—	Model ID. See available video models.
prompt	string	Yes	—	Text description of the video to generate.
resolution	string	No	"720p"	Output resolution. Options: "480p", "720p", "1080p". Varies by model.
duration	float	No	4.0	Video length in seconds. Max varies by model (4–10s).
fps	integer	No	24	Frames per second. Options: 12, 24, 30.
image_url	string	No	null	Input image URL for image-to-video generation.
negative_prompt	string	No	""	What to exclude.
seed	integer	No	Random	Reproducibility seed.
input_images	string[]	No	null	Array of URLs to reference images for image-to-video workflows (model-dependent).

Example Request

import requests

response = requests.post(
    "https://api.fluxpool.ai/v1/videos/generations",
    headers={
        "Authorization": "Bearer fp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "Content-Type": "application/json"
    },
    json={
        "model": "seedance-v2",
        "prompt": "A koi fish transforming into a phoenix, slow motion, cinematic",
        "resolution": "720p",
        "duration": 4.0
    }
)

generation = response.json()
print(generation["id"])       # gen_vid_xyz789
print(generation["status"])   # "pending"

curl -X POST https://api.fluxpool.ai/v1/videos/generations \
  -H "Authorization: Bearer fp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "seedance-v2",
    "prompt": "A koi fish transforming into a phoenix, slow motion, cinematic",
    "resolution": "720p",
    "duration": 4.0
  }'

const response = await fetch("https://api.fluxpool.ai/v1/videos/generations", {
  method: "POST",
  headers: {
    "Authorization": "Bearer fp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "seedance-v2",
    prompt: "A koi fish transforming into a phoenix, slow motion, cinematic",
    resolution: "720p",
    duration: 4.0,
  }),
});

const generation = await response.json();
console.log(generation.id);     // gen_vid_xyz789
console.log(generation.status); // "pending"

Response (Initial — Async)

JSON

{
  "created": 1785845810,
  "id": "6dcc89ce-964e-466e-8100-ba2bdfb6d07c",
  "status": "pending",
  "model": "seedance-v2",
  "type": "video",
  "data": [
    {
      "url": "https://fluxpool-output.s3.ap-southeast-1.amazonaws.com/...?X-Amz-...",
      "generation_id": "6dcc89ce-964e-466e-8100-ba2bdfb6d07c",
      "status": "pending",
      "model": "seedance-v2",
      "revised_prompt": null
    }
  ]
}

Response Fields

Field	Type	Description
id	string	Unique generation ID. Use to poll for completion.
status	string	"pending" initially. Becomes "processing", "completed", or "failed".
created	integer	Unix timestamp.
model	string	Model used.
type	string	`"video"` for this endpoint.
data[0].url	string	Presigned S3 URL. Becomes fetchable once the generation completes; expires 1 hour after issue.

Credits are charged when the generation is created. If the generation fails, credits are automatically refunded.

Polling patterns (and upcoming webhook delivery): see Async & Polling →

Supported Video Models

seedance-v2.5seedance-v2seedance-v2-fastseedance-v2-miniwan3.0-video-primewan3.0-videowan2.7-t2vwan2.7-r2vrunway-gen4.5

Live catalog: GET /v1/models.

Errors

Status	Code	Description
400	invalid_request	Missing or invalid parameters.
401	authentication_error	Invalid or missing API key.
402	insufficient_credits	Not enough credits. Top up →
404	model_not_found	Requested model does not exist.
422	unsupported_parameter	Parameter not supported by this model.
429	CONCURRENCY_LIMIT_REACHED	All of your plan's generations are running. See limits.
500	server_error	Internal error. Retry or contact support.

GET `/v1/generations/{id}`

Retrieve the status of any generation (image or video) by its id.

Poll this endpoint to check progress. Recommended interval: every 3 seconds.

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The generation ID.

Example Request (Polling)

import requests
import time

generation_id = "gen_vid_xyz789"

while True:
    response = requests.get(
        f"https://api.fluxpool.ai/v1/generations/{generation_id}",
        headers={"Authorization": "Bearer fp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}
    )
    result = response.json()

    if result["status"] == "completed":
        print(result["data"][0]["url"])
        break
    elif result["status"] == "failed":
        print("Generation failed:", result["error"])
        break

    time.sleep(5)

curl https://api.fluxpool.ai/v1/generations/gen_vid_xyz789 \
  -H "Authorization: Bearer fp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

Mirrors the shape returned by the original POST — the presigned URL in data[0].url becomes fetchable once status is "completed".

JSON — Completed

{
  "created": 1785845810,
  "id": "6dcc89ce-964e-466e-8100-ba2bdfb6d07c",
  "status": "completed",
  "model": "seedance-v2",
  "type": "video",
  "data": [
    {
      "url": "https://fluxpool-output.s3.ap-southeast-1.amazonaws.com/...?X-Amz-...",
      "generation_id": "6dcc89ce-964e-466e-8100-ba2bdfb6d07c",
      "status": "completed",
      "model": "seedance-v2",
      "revised_prompt": null
    }
  ]
}

While pending or processing, status reflects the current state and data[0].url is a presigned URL that will start returning bytes once the file is written. Presigned URLs expire 1 hour after the generation was created.

Models

GET `/v1/models`

List all available models.

Query Parameters

Parameter	Type	Required	Default	Description
type	string	No	"all"	Filter: "image", "video", or "all".

Example Request

from openai import OpenAI

client = OpenAI(
    base_url="https://api.fluxpool.ai/v1",
    api_key="fp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
)

models = client.models.list()
for model in models.data:
    print(model.id)

curl https://api.fluxpool.ai/v1/models \
  -H "Authorization: Bearer fp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

JSON (truncated)

{
  "object": "list",
  "data": [
    {
      "id": "flux-2-pro",
      "object": "model",
      "type": "image",
      "name": "Flux 2 Pro",
      "provider": "Black Forest Labs",
      "description": "Best-in-class image generation. Exceptional prompt adherence.",
      "max_resolution": "2048x2048",
      "avg_speed_seconds": 3
    },
    {
      "id": "seedance-v2",
      "object": "model",
      "type": "video",
      "name": "Seedance 2.0",
      "provider": "ByteDance",
      "description": "Multi-shot video up to 15s with sound and reference media.",
      "max_resolution": "1920x1080",
      "avg_speed_seconds": 45
    }
  ]
}

Browse models with sample outputs: Models Hub →

Parameter	Type	Required	Description
model_id	string	Yes	The model ID (e.g., "flux-2-pro").

Credits

Check your remaining credit balance and usage. Same API key you use for generations. Useful for monitoring spend in automation.

GET `/v1/credits/balance`

Returns the caller's current credit balance. It is one balance: credits from plans, packs, vouchers and bonuses are the same credits, and they never expire.

Example Request

curl https://api.fluxpool.ai/v1/credits/balance \
  -H "Authorization: Bearer fp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

import requests

r = requests.get(
    "https://api.fluxpool.ai/v1/credits/balance",
    headers={"Authorization": "Bearer fp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"},
)
balance = r.json()
print(f"Credits remaining: {balance['balance']}")

Response

JSON

{
  "object": "credit_balance",
  "balance": 142,
  "subscription_active": true,
  "lifetime_purchased": 500,
  "lifetime_used": 358
}

Response Fields

Field	Type	Description
balance	integer	Credits available to spend.
subscription_active	boolean	Whether the account has an active paid subscription.
lifetime_purchased	integer	Total credits purchased over the account's lifetime.
lifetime_used	integer	Total credits spent over the account's lifetime.

Top up or enable auto-topup: Pricing →

GET `/v1/credits/summary`

Same balance as /v1/credits/balance, plus a usage breakdown for the last 30 days (per-model and per-media-type totals). Heavier query — use /v1/credits/balance for hot-path polling.

Example Request

curl https://api.fluxpool.ai/v1/credits/summary \
  -H "Authorization: Bearer fp_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response (shape)

{
  "object": "credit_summary",
  "balance": 142,
  "period_start": "2026-07-19T00:00:00Z",
  "period_end": "2026-08-18T00:00:00Z",
  "period_used": 85,
  "by_media_type": {
    "image": 40,
    "video": 45
  },
  "by_model": [
    { "model": "flux-2-pro",    "credits_used": 30 },
    { "model": "seedance-v2.5", "credits_used": 45 }
  ]
}

The by_model and by_media_type breakdowns reflect activity in the last 30 days, not the full account lifetime.

Error Codes

All errors follow a consistent format.

Error Response Format

{
  "error": {
    "code": "insufficient_credits",
    "message": "Your account has 2 credits remaining. This generation requires 15 credits.",
    "type": "billing_error",
    "param": null
  }
}

HTTP Status	Code	Type	Description
400	invalid_request	invalid_request	The request body is malformed or missing required fields.
400	invalid_parameter	invalid_request	A parameter value is out of range or unsupported.
401	authentication_error	auth_error	API key is missing, invalid, or revoked.
402	insufficient_credits	billing_error	Not enough credits for this generation.
403	forbidden	auth_error	API key doesn't have permission for this action.
404	model_not_found	not_found	The specified model ID does not exist.
404	generation_not_found	not_found	The specified generation ID does not exist.
409	generation_in_progress	conflict	A conflicting generation is already running.
413	payload_too_large	invalid_request	Request body exceeds size limit (e.g., image_url).
422	unsupported_parameter	invalid_request	Parameter not supported by the selected model.
429	CONCURRENCY_LIMIT_REACHED	invalid_request_error	All of your plan's generations are running. Wait for one to finish, then retry with backoff.
429	CONNECTION_LIMIT_REACHED	invalid_request_error	A connected app (MCP via OAuth) would go over its daily credit limit.
403	CONNECTION_PAUSED	invalid_request_error	The connected app is paused.
500	server_error	server_error	Internal server error. Retry with exponential backoff.
502	model_unavailable	server_error	Upstream model provider is temporarily unavailable.
503	service_unavailable	server_error	Service is under maintenance. Retry with exponential backoff.

For a CONCURRENCY_LIMIT_REACHED 429, wait for a generation to finish and retry with exponential backoff. For 5xx errors, retry with exponential backoff (initial delay 1s, max 30s).

Limits

Generations running at once. Each plan sets how many generations can be in progress at the same time for your account, whether they come from the app, the API or an MCP client. Without an active plan, your credits still work, at the lowest plan's limit.

Plan	Concurrent generations
1-month Trial	10
Base	10
Pro	15
Growth	20
Hero	25
Enterprise	Custom

Connected apps. An app or agent you connect through the MCP connector (OAuth) has its own daily credit limit, 500 by default, over a rolling 24 hours. Change it or pause the connection in the app under API / MCP Access, Connected apps. API keys have no daily limit.

Status	Code	When
429	CONCURRENCY_LIMIT_REACHED	Your plan's generations are all running. Wait for one to finish.
429	CONNECTION_LIMIT_REACHED	This connected app would go over its daily credit limit. The message says how much it has used and what the generation needs.
403	CONNECTION_PAUSED	This connected app is paused. Resume it to generate again.

Every error uses the same body. Branch on error.code; the message is for people and may change.

429 response body

{
  "error": {
    "message": "You have 10 generations running and your plan allows 10 at once. Wait for one to finish, or upgrade for more.",
    "type": "invalid_request_error",
    "param": null,
    "code": "CONCURRENCY_LIMIT_REACHED"
  }
}

Through the MCP server, the same object comes back as the text of the create_generation tool result. The API does not send rate-limit headers.

Need higher limits? Contact us about enterprise plans →

API Reference

Use from an AI agent (MCP)

Install the MCP server

Add your API key

Ask the agent to generate

Authentication

Images

POST /v1/images/generations

Request Body

Example Request

Response

Response Fields

Supported Image Models

Errors

Polling image generations

Videos

POST /v1/videos/generations

Request Body

Example Request

Response (Initial — Async)

Response Fields

Supported Video Models

Errors

GET /v1/generations/{id}

Path Parameters

Example Request (Polling)

Response

Models

GET /v1/models

Query Parameters

Example Request

Response

Credits

GET /v1/credits/balance

Example Request

Response

Response Fields

GET /v1/credits/summary

Example Request

Response (shape)

Error Codes

Limits

Ready to build?

POST `/v1/images/generations`

POST `/v1/videos/generations`

GET `/v1/generations/{id}`

GET `/v1/models`

GET `/v1/credits/balance`

GET `/v1/credits/summary`