Skip to content

About

FLUX 3 API — Python wrapper for FLUX 3 (video and image) on WaveSpeedAI: text-to-video, image-to-video, video editing, video extension, video upscaling, text-to-image.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

FLUX 3 API — Python wrapper

Call FLUX 3 (video and image) from Python with one function per endpoint: text-to-video, image-to-video, video editing, video extension, video upscaling, text-to-image, image editing. Built on the official wavespeed SDK and the WaveSpeedAI hosted API — no GPU, pay per generation.

FLUX 3 API Try in browser

Quick start

pip install git+https://github.com/WaveSpeedAI/flux-3-api.git
export WAVESPEED_API_KEY="your-api-key"   # https://wavespeed.ai/accesskey
import flux_api

urls = flux_api.text_to_video(
    prompt="A slow cinematic dolly shot through a rain-soaked neon night market, reflections on the pavement",
)
print(urls[0])

Every function waits for the generation to finish and returns a list of output URLs. Optional arguments you leave out are not sent, so the API defaults apply. Inputs such as images, videos and audio are passed as URLs; use flux_api.upload("local-file") to get a URL for a local file.

Endpoints

Function Model Type
text_to_video() black-forest-labs/flux-3/text-to-video text-to-video
image_to_video() black-forest-labs/flux-3/image-to-video image-to-video
start_end_to_video() black-forest-labs/flux-3/start-end-to-video image-to-video
video_edit() black-forest-labs/flux-3/video-edit video-to-video
video_extend() black-forest-labs/flux-3/video-extend video-extend
video_upscale() black-forest-labs/flux-3/video-upscale upscale-video
text_to_image() black-forest-labs/flux-3/text-to-image text-to-image
image_edit() black-forest-labs/flux-3/image-edit image-to-image

Each model page has a playground, live pricing and copy-paste API snippets. Prices are per generation and depend on the settings you choose; check a request before running it with wavespeed price <model> from the CLI.

Parameters

text_to_video

black-forest-labs/flux-3/text-to-video — Text-to-image generation with FLUX.3 is Black Forest Labs' frontier video model. This endpoint generates video directly from a text prompt, translating a written description into motion, composition, and scene. .

Parameter Type Required Default Allowed Description
prompt str yes The text prompt describing the video you want to generate.
aspect_ratio str "9:16" 21:9, 2:1, 16:9, 4:3, 1:1, 3:4, 9:16 The aspect ratio of the generated media.
resolution str "720p" 720p, 1080p Resolution of the generated video.
duration int 5 5–20 Video length in seconds (5-20).
generate_audio bool true Whether to generate audio for the video.

image_to_video

black-forest-labs/flux-3/image-to-video — Text-to-image generation with FLUX.3 is Black Forest Labs' frontier video model. This endpoint generates video directly from a text prompt, translating a written description into motion, composition, and scene. .

Parameter Type Required Default Allowed Description
prompt str yes The text prompt describing the video you want to generate.
image str yes URL of the image the video starts from (PNG, JPEG, or WebP)..
aspect_ratio str 21:9, 2:1, 16:9, 4:3, 1:1, 3:4, 9:16 The aspect ratio of the generated media.
resolution str "720p" 720p, 1080p Resolution of the generated video.
duration int 5 5–20 Video length in seconds (5-20).
generate_audio bool true Whether to generate audio for the video.

start_end_to_video

black-forest-labs/flux-3/start-end-to-video — Text-to-image generation with FLUX.3 is Black Forest Labs' frontier video model. This endpoint generates video directly from a text prompt, translating a written description into motion, composition, and scene. .

Parameter Type Required Default Allowed Description
prompt str yes The text prompt describing the video you want to generate.
image str yes Optional image used as the edited video's first frame.
last_image str yes Optional image used as the edited video's first frame.
aspect_ratio str 21:9, 2:1, 16:9, 4:3, 1:1, 3:4, 9:16 The aspect ratio of the generated media.
resolution str "720p" 720p, 1080p Resolution of the generated video.
duration int 5 5–20 Video length in seconds (5-20).
generate_audio bool true Whether to generate audio for the video.

video_edit

black-forest-labs/flux-3/video-edit — FLUX 3 Video Edit applies prompt-guided changes to an existing video while preserving its motion, timing, and framing.

Parameter Type Required Default Allowed Description
video str yes URL of the input MP4 video. The video must be under 50 MB and under 15 seconds.
prompt str yes Describe how to edit the input video. The clip is re-rendered while preserving its motion, timing, and framing. Maximum 4096 characters.

video_extend

black-forest-labs/flux-3/video-extend — Text-to-image generation with FLUX.3 is Black Forest Labs' frontier video model. This endpoint generates video directly from a text prompt, translating a written description into motion, composition, and scene. .

Parameter Type Required Default Allowed Description
prompt str yes The text prompt describing the video you want to generate.
video str yes URL of the input video. MP4, under 50 MB and under 15 seconds.
aspect_ratio str 21:9, 2:1, 16:9, 4:3, 1:1, 3:4, 9:16 The aspect ratio of the generated media.
resolution str "720p" 720p, 1080p Resolution of the generated video.
duration int 5 5–20 Video length in seconds (5-20).
generate_audio bool true Whether to generate audio for the video.

video_upscale

black-forest-labs/flux-3/video-upscale — FLUX Video Upscale enhances an input video with source-faithful or creative detail reconstruction while preserving its aspect ratio.

Parameter Type Required Default Allowed Description
video str yes MP4 video to upscale. Maximum duration: 20 seconds. Maximum file size: 50 MB.
prompt str Optional description used to guide creative detail enhancement. Leave empty for a neutral upscale.
upscale_factor float 2 1.5–3 Output scaling factor. The source aspect ratio is preserved.
creativity int 1 0–1 Use 0 for a source-faithful upscale or 1 for creative detail enhancement.

text_to_image

black-forest-labs/flux-3/text-to-image — Generate images from text with detailed composition, typography, and 1K, 2K, or 4K output.

Parameter Type Required Default Allowed Description
prompt str yes Describe the subject, composition, lighting, style, and any text to include.
aspect_ratio str "1:1" 21:9, 2:1, 16:9, 3:2, 7:5, 4:3, 5:4, 1:1, 4:5, 3:4, 5:7, 2:3, 9:16, 1:2 The aspect ratio of the generated image. Defaults to 1:1.
resolution str "1k" 1k, 2k, 4k Output resolution tier. Higher tiers cost more; 4K can take several minutes.
output_format str "jpeg" jpeg, png The format of the generated image.

image_edit

black-forest-labs/flux-3/image-edit — Edit images with natural-language instructions and combine up to ten input images. Choose 1K, 2K, or 4K output.

Parameter Type Required Default Allowed Description
prompt str yes Describe the changes. Refer to input images by their order, such as image 1 or image 2.
images List[str] yes 1–10 items Upload 1-10 input images in reference order. Each must be at least 256 pixels per dimension and at most 4 megapixels. Omit aspect_ratio to follow the first image.
aspect_ratio str 21:9, 2:1, 16:9, 3:2, 7:5, 4:3, 5:4, 1:1, 4:5, 3:4, 5:7, 2:3, 9:16, 1:2 The aspect ratio of the generated image. If not specified, it is determined automatically from the input image.
resolution str "1k" 1k, 2k, 4k Output resolution tier. Higher tiers cost more; 4K can take several minutes.
output_format str "jpeg" jpeg, png The format of the generated image.

REST and CLI

The wrapper is a thin layer over the REST API: submit, then poll for the result.

curl -s -X POST "https://api.wavespeed.ai/api/v3/black-forest-labs/flux-3/text-to-video" \
  -H "Authorization: Bearer $WAVESPEED_API_KEY" -H "Content-Type: application/json" \
  -d '{"prompt": "A slow cinematic dolly shot through a rain-soaked neon night market, reflections on the pavement"}'
# -> {"data": {"id": "<prediction_id>"}}

curl -s "https://api.wavespeed.ai/api/v3/predictions/<prediction_id>/result" \
  -H "Authorization: Bearer $WAVESPEED_API_KEY"
# -> status: completed, outputs: ["<url>"]
npm i -g @wavespeed/cli && wavespeed login
wavespeed run black-forest-labs/flux-3/text-to-video -p "your prompt"

Related

Notes

  • FLUX 3 is a model by Black Forest Labs. This repository is maintained by WaveSpeedAI and wraps the WaveSpeedAI hosted API for it.
  • Function signatures and the tables above are generated from the live model schemas (last generated 2026-11-22). The model pages are the source of truth if an endpoint changes.
  • Issues and pull requests are welcome. License: MIT.

About

FLUX 3 API — Python wrapper for FLUX 3 (video and image) on WaveSpeedAI: text-to-video, image-to-video, video editing, video extension, video upscaling, text-to-image.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages