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? Create a free account → New here? Start with the Quickstart guide →

Authentication

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

Header

Authorization: Bearer fp_your_api_key

Generate API keys in your dashboard → Settings → API Keys. See the Authentication guide for key rotation and scoping.

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.
n	integer	No	1	Number of images. Max 4.
negative_prompt	string	No	""	What to exclude from the image.
steps	integer	No	Model default	Inference steps. Higher = more detail, slower.
guidance_scale	float	No	Model default	Prompt adherence strength. Typically 1.0–20.0.
seed	integer	No	Random	Reproducibility seed.
response_format	string	No	"url"	"url" or "b64_json".

Example Request

from openai import OpenAI

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

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

print(response.data[0].url)

curl -X POST https://api.fluxpool.ai/v1/images/generations \
  -H "Authorization: Bearer fp_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-1.1-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_your_api_key",
});

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

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

Response

JSON

{
  "created": 1719000000,
  "data": [
    {
      "url": "https://cdn.fluxpool.ai/generations/abc123/output.png",
      "revised_prompt": null
    }
  ],
  "model": "flux-1.1-pro",
  "usage": {
    "credits_used": 3
  }
}

Response Fields

Field	Type	Description
created	integer	Unix timestamp of generation.
data	array	Array of generated image objects.
data[].url	string	URL of the generated image. Valid for 24 hours.
data[].b64_json	string	Base64-encoded image (if response_format is "b64_json").
data[].revised_prompt	string	Model-revised prompt, if applicable. May be null.
model	string	Model used for generation.
usage.credits_used	integer	Credits consumed by this generation.

Supported Image Models

flux-1.1-pro qwen-image-3-6-plus sdxl-1.0 ideogram-2.0 playground-v3

Model-specific parameters and resolution limits: see individual model pages →

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	rate_limit_exceeded	Too many requests. See rate limits.
500	server_error	Internal error. Retry or contact support.

GET `/v1/images/generations/{id}`

Retrieve a previously generated image by its generation ID.

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	The generation ID.

Example Request

import requests

response = requests.get(
    "https://api.fluxpool.ai/v1/images/generations/gen_abc123",
    headers={"Authorization": "Bearer fp_your_api_key"}
)

print(response.json())

curl https://api.fluxpool.ai/v1/images/generations/gen_abc123 \
  -H "Authorization: Bearer fp_your_api_key"

Response

JSON

{
  "id": "gen_abc123",
  "status": "completed",
  "created": 1719000000,
  "model": "flux-1.1-pro",
  "prompt": "A dragon perched on a neon-lit Tokyo rooftop at midnight, cinematic lighting, 8K",
  "data": [
    {
      "url": "https://cdn.fluxpool.ai/generations/abc123/output.png"
    }
  ],
  "usage": {
    "credits_used": 3
  }
}

Response Fields

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.
webhook_url	string	No	null	URL to receive POST callback when generation completes. See webhooks.

Example Request

import requests

response = requests.post(
    "https://api.fluxpool.ai/v1/videos/generations",
    headers={
        "Authorization": "Bearer fp_your_api_key",
        "Content-Type": "application/json"
    },
    json={
        "model": "wan-video-2.1",
        "prompt": "A koi fish transforming into a phoenix, slow motion, cinematic",
        "resolution": "720p",
        "duration": 4.0,
        "webhook_url": "https://your-app.com/webhook/fluxpool"
    }
)

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_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan-video-2.1",
    "prompt": "A koi fish transforming into a phoenix, slow motion, cinematic",
    "resolution": "720p",
    "duration": 4.0,
    "webhook_url": "https://your-app.com/webhook/fluxpool"
  }'

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

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

Response (Initial — Async)

JSON

{
  "id": "gen_vid_xyz789",
  "status": "pending",
  "created": 1719000000,
  "model": "wan-video-2.1",
  "prompt": "A koi fish transforming into a phoenix, slow motion, cinematic",
  "estimated_time": 45,
  "usage": {
    "credits_used": 15
  }
}

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.
estimated_time	integer	Estimated seconds until completion.
usage.credits_used	integer	Credits consumed (charged at creation, refunded if failed).

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

Webhook Payload Webhook

Sent when generation completes:

JSON — Webhook POST body

{
  "event": "generation.completed",
  "id": "gen_vid_xyz789",
  "status": "completed",
  "data": {
    "url": "https://cdn.fluxpool.ai/generations/vid_xyz789/output.mp4",
    "duration": 4.0,
    "resolution": "720p",
    "fps": 24
  },
  "model": "wan-video-2.1",
  "created": 1719000000,
  "completed": 1719000045
}

Full webhook setup and signature verification: see Webhooks guide →

Supported Video Models

wan-video-2.1 kling-v2 runway-gen3 hunyuan-video luma-dream

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	rate_limit_exceeded	Too many requests. See rate limits.
500	server_error	Internal error. Retry or contact support.

GET `/v1/videos/generations/{id}`

Check the status of a video generation or retrieve the completed video.

Poll this endpoint to check generation progress. Recommended interval: every 5 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/videos/generations/{generation_id}",
        headers={"Authorization": "Bearer fp_your_api_key"}
    )
    result = response.json()

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

    time.sleep(5)

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

Response (Completed)

JSON

{
  "id": "gen_vid_xyz789",
  "status": "completed",
  "created": 1719000000,
  "completed": 1719000045,
  "model": "wan-video-2.1",
  "prompt": "A koi fish transforming into a phoenix, slow motion, cinematic",
  "data": {
    "url": "https://cdn.fluxpool.ai/generations/vid_xyz789/output.mp4",
    "duration": 4.0,
    "resolution": "720p",
    "fps": 24
  },
  "usage": {
    "credits_used": 15
  }
}

Response (Still Processing)

JSON

{
  "id": "gen_vid_xyz789",
  "status": "processing",
  "created": 1719000000,
  "model": "wan-video-2.1",
  "prompt": "A koi fish transforming into a phoenix, slow motion, cinematic",
  "progress": 0.65,
  "estimated_remaining": 16,
  "usage": {
    "credits_used": 15
  }
}

Additional Response Fields

Field	Type	Description
completed	integer	Unix timestamp of completion. Null if pending.
progress	float	0.0 to 1.0 progress estimate. Available during "processing".
estimated_remaining	integer	Estimated seconds remaining.
data.url	string	Video URL. Available when status is "completed". Valid for 24 hours.
data.duration	float	Actual video duration in seconds.
data.resolution	string	Actual output resolution.
data.fps	integer	Actual frames per second.
error	object	Error details if status is "failed".

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_your_api_key"
)

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

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

Response

JSON (truncated)

{
  "object": "list",
  "data": [
    {
      "id": "flux-1.1-pro",
      "object": "model",
      "type": "image",
      "name": "Flux 1.1 Pro",
      "provider": "Black Forest Labs",
      "description": "Best-in-class image generation. Exceptional prompt adherence.",
      "max_resolution": "2048x2048",
      "cost_per_generation": 0.03,
      "avg_speed_seconds": 3
    },
    {
      "id": "wan-video-2.1",
      "object": "model",
      "type": "video",
      "name": "Wan Video 2.1",
      "provider": "Alibaba",
      "description": "High-quality video from text or image. Cinematic output.",
      "max_resolution": "1280x720",
      "cost_per_generation": 0.15,
      "avg_speed_seconds": 45
    }
  ]
}

Browse models with sample outputs: Models Hub →

GET `/v1/models/{model_id}`

Get details for a specific model.

Path Parameters

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

Example Request

cURL

curl https://api.fluxpool.ai/v1/models/flux-1.1-pro \
  -H "Authorization: Bearer fp_your_api_key"

Response

JSON

{
  "id": "flux-1.1-pro",
  "object": "model",
  "type": "image",
  "name": "Flux 1.1 Pro",
  "provider": "Black Forest Labs",
  "description": "Best-in-class image generation. Exceptional prompt adherence and photorealism.",
  "max_resolution": "2048x2048",
  "supported_sizes": ["512x512", "768x768", "1024x1024", "1536x1536", "2048x2048"],
  "cost_per_generation": 0.03,
  "avg_speed_seconds": 3,
  "parameters": {
    "steps": { "type": "integer", "default": 28, "min": 1, "max": 50 },
    "guidance_scale": { "type": "float", "default": 7.5, "min": 1.0, "max": 20.0 },
    "negative_prompt": { "type": "string", "default": "" },
    "seed": { "type": "integer", "default": null }
  }
}

The parameters object lists all tunable parameters and their valid ranges for this model.

Account

GET `/v1/account/credits`

Check your current credit balance.

Example Request

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

import requests

response = requests.get(
    "https://api.fluxpool.ai/v1/account/credits",
    headers={"Authorization": "Bearer fp_your_api_key"}
)

balance = response.json()
print(f"Credits remaining: {balance['credits']}")

Response

JSON

{
  "credits": 142,
  "currency": "USD",
  "credits_value_usd": 14.20,
  "plan": "pay_as_you_go",
  "auto_topup": false
}

Response Fields

Field	Type	Description
credits	integer	Remaining credits.
currency	string	Account currency.
credits_value_usd	float	Approximate USD value of remaining credits.
plan	string	"free", "pay_as_you_go", or "enterprise".
auto_topup	boolean	Whether auto-topup is enabled.

Top up credits or enable auto-topup: Pricing →

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	rate_limit_exceeded	rate_limit	Too many requests. Retry after the Retry-After header.
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. Check status.fluxpool.ai.

For 429 errors, respect the Retry-After header. For 5xx errors, retry with exponential backoff (initial delay 1s, max 30s).

Check system status: status.fluxpool.ai →

Rate Limits

Rate limits are per API key. Limits vary by plan tier.

Plan	Requests/minute	Concurrent generations	Burst limit
Free	10	2	5 in 10s
Pay as you go	60	10	20 in 10s
Enterprise	Custom	Custom	Custom

Rate limit information is included in response headers.

Header	Description
X-RateLimit-Limit	Maximum requests per minute.
X-RateLimit-Remaining	Remaining requests in current window.
X-RateLimit-Reset	Unix timestamp when the window resets.
Retry-After	Seconds to wait (on 429 responses only).

Need higher limits? Contact us about enterprise plans →

API Reference

Authentication

Images

POST /v1/images/generations

Request Body

Example Request

Response

Response Fields

Supported Image Models

Errors

GET /v1/images/generations/{id}

Path Parameters

Example Request

Response

Response Fields

Videos

POST /v1/videos/generations

Request Body

Example Request

Response (Initial — Async)

Response Fields

Webhook Payload Webhook

Supported Video Models

Errors

GET /v1/videos/generations/{id}

Path Parameters

Example Request (Polling)

Response (Completed)

Response (Still Processing)

Additional Response Fields

Models

GET /v1/models

Query Parameters

Example Request

Response

GET /v1/models/{model_id}

Path Parameters

Example Request

Response

Account

GET /v1/account/credits

Example Request

Response

Response Fields

Error Codes

Rate Limits

Ready to build?

POST `/v1/images/generations`

GET `/v1/images/generations/{id}`

POST `/v1/videos/generations`

GET `/v1/videos/generations/{id}`

GET `/v1/models`

GET `/v1/models/{model_id}`

GET `/v1/account/credits`