FLUX 3 Max Keyframes to Video API

blackforestlabs/flux-3-max/keyframes-to-video

720p / 1080p · 5–20 sec

FLUX 3 Max Keyframes to Video turns 1–10 images pinned to exact frames into a single 5–20 second 720p or 1080p clip with native audio. Each image appears at the frame_index you set on a 24 fps timeline, so the story beats land where you planned them.

Input

Prompt441

Keyframes

Drag and drop files, paste from clipboard, or provide a URL. Required. Add 1–10 JPEG, PNG or WebP images, then set each Frame Index on the 24 fps timeline.

3/10 files added

Keyframe 1Frame Index

Keyframe 2Frame Index

Keyframe 3Frame Index

Each Frame Index is a unique whole number from 0 to 192 (duration × 24).

Duration

Resolution

Aspect Ratio

Sound

OutputExample

Continue with

FLUX 3 Max Text to Video FLUX 3 Max Image to Video FLUX 3 Keyframes to Video

REST API

Quick Start

Make your first FLUX 3 Max Keyframes to Video request in three steps. The example pins three images to frames 0, 96 and 192 of an 8-second clip and returns a task_id.

Connect to the Vidgo API

Create an API key, keep it on your server, and send it in the Authorization header as a Bearer token.

Endpoint: POSThttps://api.vidgo.ai/api/generate/submit
Authentication: Authorization: Bearer VIDGO_API_KEY

Submit one generation task

Run the short example with a prompt and at least one keyframe.

Submit request

curl --request POST \
  --url "https://api.vidgo.ai/api/generate/submit" \
  --header "Authorization: Bearer $VIDGO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "blackforestlabs/flux-3-max/keyframes-to-video",
  "input": {
    "prompt": "A paper lantern festival on a quiet river at night, filmed as one smooth drifting shot. Follow the three keyframes in order: a single lantern being lit on the bank, the lantern floating among many others mid-river, then a wide view of hundreds of lanterns passing under a stone bridge. Keep the water calm and the lantern colours warm. Native audio: soft water lapping, faint crowd murmur, wooden boat creak. No text, no logos, no watermark.",
    "duration": 8,
    "resolution": "720p",
    "aspect_ratio": "auto",
    "sound": true,
    "keyframes": [
      {
        "image_url": "https://cdn.vidgo.ai/apis/models/blackforestlabs/flux-3-max/keyframes-to-video/v1/01/input-keyframe-01.webp",
        "frame_index": 0
      },
      {
        "image_url": "https://cdn.vidgo.ai/apis/models/blackforestlabs/flux-3-max/keyframes-to-video/v1/01/input-keyframe-02.webp",
        "frame_index": 96
      },
      {
        "image_url": "https://cdn.vidgo.ai/apis/models/blackforestlabs/flux-3-max/keyframes-to-video/v1/01/input-keyframe-03.webp",
        "frame_index": 192
      }
    ]
  }
}'

Wait for the result

Use the returned task_id to check the same task until it reaches finished or failed. On success, read data.files[].file_url.

Track status

GET https://api.vidgo.ai/api/generate/status/{task_id}

Poll every few seconds while the status is not_started or running, and stop on finished or failed. On success, read data.files[].file_url. For longer clips, lengthen the interval gradually or add callback_url to the submit request.

not_startedrunningfinishedfailed

Submit response

{
  "code": 200,
  "data": {
    "task_id": "PLO2R6GLU1NN669K",
    "status": "not_started",
    "created_time": "2026-11-05T07:04:46"
  }
}

Finished response

{
  "code": 200,
  "data": {
    "task_id": "PLO2R6GLU1NN669K",
    "status": "finished",
    "files": [
      {
        "file_url": "https://cdn.vidgo.ai/apis/models/blackforestlabs/flux-3-max/keyframes-to-video/v2/01/output-01.mp4",
        "file_type": "video"
      }
    ],
    "created_time": "2026-11-05T07:04:46",
    "error_message": null,
    "progress": 100
  }
}

Complete runnable example

Open this after the three-step flow is clear. It combines submission, polling, terminal-state handling and result extraction in one script.

Complete runnable example

set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"

REQUEST_BODY=$(cat <<'JSON'
{
  "model": "blackforestlabs/flux-3-max/keyframes-to-video",
  "input": {
    "prompt": "A paper lantern festival on a quiet river at night, filmed as one smooth drifting shot. Follow the three keyframes in order: a single lantern being lit on the bank, the lantern floating among many others mid-river, then a wide view of hundreds of lanterns passing under a stone bridge. Keep the water calm and the lantern colours warm. Native audio: soft water lapping, faint crowd murmur, wooden boat creak. No text, no logos, no watermark.",
    "duration": 8,
    "resolution": "720p",
    "aspect_ratio": "auto",
    "sound": true,
    "keyframes": [
      {
        "image_url": "https://cdn.vidgo.ai/apis/models/blackforestlabs/flux-3-max/keyframes-to-video/v1/01/input-keyframe-01.webp",
        "frame_index": 0
      },
      {
        "image_url": "https://cdn.vidgo.ai/apis/models/blackforestlabs/flux-3-max/keyframes-to-video/v1/01/input-keyframe-02.webp",
        "frame_index": 96
      },
      {
        "image_url": "https://cdn.vidgo.ai/apis/models/blackforestlabs/flux-3-max/keyframes-to-video/v1/01/input-keyframe-03.webp",
        "frame_index": 192
      }
    ]
  }
}
JSON
)

SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --request POST \
  --url "https://api.vidgo.ai/api/generate/submit" \
  --header "Authorization: Bearer $VIDGO_API_KEY" \
  --header "Content-Type: application/json" \
  --data "$REQUEST_BODY")

TASK_ID=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.data.task_id // .task_id // empty')
if [ -z "$TASK_ID" ]; then
  printf 'Submit response did not include task_id:
%s
' "$SUBMIT_RESPONSE" >&2
  exit 1
fi

while true; do
  STATUS_RESPONSE=$(curl --silent --show-error --fail-with-body \
    --url "https://api.vidgo.ai/api/generate/status/$TASK_ID" \
    --header "Authorization: Bearer $VIDGO_API_KEY")
  STATUS=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.data.status // .status // empty')

  case "$STATUS" in
    finished)
      printf '%s' "$STATUS_RESPONSE" | jq -r '(.data.files // .files // [])[]?.file_url'
      break
      ;;
    failed)
      printf '%s' "$STATUS_RESPONSE" | jq -r '.data.error_message // .error_message // "Generation failed"' >&2
      exit 1
      ;;
    not_started|running)
      sleep 2
      ;;
    *)
      printf 'Unexpected task status: %s
' "$STATUS" >&2
      exit 1
      ;;
  esac
done

Request Parameters

model and callback_url belong at the request root; generation parameters belong inside input.

Field	Type	Required	Default	Description
model	string	Yes	—	Fixed to blackforestlabs/flux-3-max/keyframes-to-video.
callback_url	string (URL)	No	—	A public HTTP(S) URL that receives the task result when it finishes.
input	object	Yes	—	Generation parameters: a prompt and 1–10 keyframes, plus optional duration, resolution, aspect_ratio and sound.
input.prompt	string	Yes	—	Text prompt for the shot, including audio cues when sound is on.
input.keyframes	object[]	Yes	—	1–10 items of {image_url, frame_index}; frame_index unique, 0 to duration × 24.
input.duration	integer	No	5	Whole seconds, 5–20.
input.resolution	string	No	720p	720p or 1080p.
input.aspect_ratio	string	No	auto	auto, 21:9, 2:1, 16:9, 4:3, 1:1, 3:4, 9:16.
input.sound	boolean	No	true	Native audio on or off; does not change the price.

Response Fields

Submission returns the task identity immediately. Status responses add progress, output files or a failure message as the task advances.

Field	Type	Description
code	integer	Application result code. Successful responses use 0 or 200.
message	string	Human-readable response or error message when present.
data.task_id	string	Task identifier used in the status endpoint path.
data.status	string	Current state: not_started, running, finished or failed.
data.created_time	string	Task creation time in date-time format.
data.progress	number	Completion percentage when the provider reports progress.
data.files[]	array	Generated output files returned after a successful task.
data.files[].file_url	string	Public URL of the generated video.
data.files[].file_type	string	Generated file type, such as video.
data.files[].watermark_url	string \| null	Watermarked output URL when one is available.
data.error_message	string \| null	Failure detail when status is failed.

Task Lifecycle

Treat not_started and running as non-terminal states. finished and failed are terminal; stop polling when either is returned.

not_started
The task has been accepted and is queued to start.
running
The video is being generated. Keep polling the status endpoint.
finished
The task is complete. Read the video URL from data.files[].file_url.
failed
Generation failed. Read data.error_message for details and stop polling.

Polling and Errors

Authentication401 means the Bearer API key is missing or invalid. Check your key in the dashboard before retrying.
Validation400 means a request field is invalid or belongs to another endpoint. Check each keyframes item and its frame_index range.
Polling intervalPoll every few seconds while the task runs, and lengthen the interval gradually for longer clips.
Terminal statesPoll only while the status is not_started or running. Stop on finished or failed.
Callback optionAdd callback_url at the request root to receive the final result without continuous polling.

Model Specifications

Specification	Value	Description
Model	blackforestlabs/flux-3-max/keyframes-to-video	Model identifier for asynchronous keyframe-guided video generation.
Duration	5–20	Whole seconds; defaults to 5.
Resolution	720p \| 1080p	Defaults to 720p.
Aspect ratio	auto \| 21:9 \| 2:1 \| 16:9 \| 4:3 \| 1:1 \| 3:4 \| 9:16	Defaults to auto.
Pricing	34 / 58 credits/s	720p / 1080p, per output second; audio is included.

View the FLUX 3 Max Keyframes to Video API documentation

FLUX 3 Max Keyframes to Video

FLUX 3 Max, post-trained by fal with Black Forest Labs on the FLUX 3 video base, can follow a timeline of images instead of a single frame. Keyframes to Video places each image at a frame position, 24 frames per second, and generates continuous motion and sound between them. It is built for animatics, product sequences and transitions where several moments must appear in a fixed order and timing.

Why choose the FLUX 3 Max Keyframes to Video API?

Frame-accurate placementSet frame_index on a 24 fps timeline: frame 48 is the 2-second mark, frame 120 the 5-second mark.
Up to ten images in one shotChain a sequence of story beats into one continuous clip instead of stitching separate generations.
Audio across the whole sequenceNative sound runs through the clip, carrying ambience and effects across each keyframe.
Same rate as text promptsKeyframes add no surcharge: 34 credits per second at 720p and 58 at 1080p.

Parameters

Parameter	Requirement	Description
prompt	Required	Describe the subject, action, camera movement, lighting and the sound you want. Leading and trailing spaces are trimmed; the text must not be empty. Default`—`
keyframes	Required	1–10 objects, each exactly {image_url, frame_index}. frame_index is a unique whole number from 0 to duration × 24 (0–120 for 5 seconds). Default`—`
duration	Optional	Output length in whole seconds, from 5 to 20. Default`5`
resolution	Optional	720p or 1080p. The resolution sets the per-second rate. Default`720p`
aspect_ratio	Optional	auto, 21:9, 2:1, 16:9, 4:3, 1:1, 3:4 or 9:16. auto follows the first keyframe image. Default`auto`
sound	Optional	Generate a native audio track in the same pass. Set false for silent footage; the price stays the same. Default`true`

How to Use

Plan the timelinePick a duration, then convert each moment to a frame: seconds × 24. A 5-second clip runs from frame 0 to 120.
Prepare matching imagesUse images with consistent style and subject so the model can move smoothly between them.
Describe the journeyWrite how the scene moves from one keyframe to the next, plus the sounds that carry it.
Submit and collect the videoSend keyframes with unique frame_index values, then poll with the task_id or wait for callback_url.

Usage and billing

FLUX 3 Max Keyframes to Video is billed per output second at the selected resolution, whatever the number of keyframes. Sound is included.

Usage	Rate	Details
720p	34 credits / second	$0.17 / second. A 5-second clip costs 170 credits ($0.85); 20 seconds costs 680 credits ($3.40).
1080p	58 credits / second	$0.29 / second. A 10-second clip costs 580 credits ($2.90); 20 seconds costs 1,160 credits ($5.80).

Best Use Cases

Animatics from storyboardsPlace storyboard panels at their planned times to preview pacing with motion and sound.
Product sequencesWalk through angles or states of a product in a set order within one clip.
Day-to-night and seasonal changesPin images of the same place at different times and let the model fill the change.
Music-timed visualsLand key images on beats by converting beat times to frame indexes.

Pro Tips

Start the first keyframe at frame 0 so the clip opens on a known image.
Leave at least a second (24 frames) between keyframes so motion has room to develop.
Raise duration before adding later frames: the highest valid frame_index is duration × 24.
Keep camera angle and lighting consistent across images to avoid abrupt jumps.

Notes

Each keyframes item contains exactly image_url and frame_index; frame_index values are unique whole numbers.
frame_index runs from 0 to duration × 24, for example 0–240 for a 10-second clip.
With auto, the output follows the first keyframe image's aspect ratio.
Credits are duration × the resolution rate and are reserved when the task is submitted.

Related Models

PixVerse V6 Max Text to VideoPixVerse V6 Max Text to Video turns a prompt into 1–15 second videos at 360p to 1080p, with eight aspect ratios and an optional native audio track for dialogue, effects and music. Describe subjects, actions and sound in one prompt, then pick the length and format for each placement.

PixVerse V6 Max Image to VideoPixVerse V6 Max Image to Video animates one JPEG, PNG or WebP image into a 1–15 second video at 360p to 1080p, with an optional native audio track. The image sets the subject and framing, and a prompt of up to 2,048 characters directs motion, camera and sound.

OmniHuman 2.0 Audio to VideoOmniHuman 2.0 Audio to Video turns one character image and 4–300 seconds of speech or music into a 720p video, with lips, expression and gestures following the audio. The image keeps the character's look and framing, while an optional prompt adds camera moves and actions.

FLUX 3 Max Text to VideoFLUX 3 Max Text to Video turns a written shot into a 5–20 second 720p or 1080p video with native audio and eight aspect ratios. It follows the camera moves, lighting and sound cues you describe, so one prompt returns picture and audio together.

FLUX 3 Max Image to VideoFLUX 3 Max Image to Video animates a start image into a 5–20 second 720p or 1080p clip with native audio, optionally landing on an end frame you supply. It keeps the composition, subject and palette of your images while adding the motion and sound in the prompt.

Kling 4.0 Text to VideoKling 4.0 Text to Video turns a prompt or multi-shot script into one 3–30 second 720p or 1080p video with stereo audio and five aspect ratios. It keeps scenes coherent across long takes and shot changes while following your camera, dialogue and sound directions.

Kling 4.0 Image to VideoKling 4.0 Image to Video animates a start image into a 3–30 second 720p or 1080p video with stereo audio, optionally finishing on an end frame you choose. It keeps the subject, framing and look of your image while adding the motion, camera work and sound in your prompt.

Kling 4.0 Reference to VideoKling 4.0 Reference to Video turns reference images, videos and reusable elements into a 3–30 second 720p or 1080p video with stereo audio, cited as @Image1, @Video1 or @Element1. It keeps characters, products and settings consistent with your references inside the new scene you describe.

Kling 4.0 Video EditKling 4.0 Video Edit transforms an existing 3–30 second video from a written instruction, restyling scenes, swapping objects or adding elements at 720p or 1080p. It keeps the original timing, people and camera path that you ask to preserve while applying the change across every frame.

Vidu Q4 Image to VideoVidu Q4 Image to Video turns one start image and an optional motion prompt into a 3–16 second clip at 540p up to 4K. Your image sets the opening frame, so subject, setting and aspect ratio carry through while the prompt directs movement and camera.

Vidu Q4 Reference to VideoVidu Q4 Reference to Video combines a prompt with up to 12 reference images and 3 voice clips into 3–16 second videos at up to 4K. Tag each reference in the prompt to keep characters, products and places recognisable, with optional generated audio at no extra cost.

Gemini Omni 1.1 Flash Text-to-Video preview

Gemini Omni 1.1 Flash Text-to-VideoGemini Omni 1.1 Flash Text-to-Video. Create 4–10 second videos with native audio from text, directing camera, lighting, and sound.

Gemini Omni 1.1 Flash Image-to-Video preview

Gemini Omni 1.1 Flash Image-to-VideoGemini Omni 1.1 Flash Image-to-Video. Animate a start image with native audio and add an optional end frame to guide the closing shot.

Gemini Omni 1.1 Flash Reference-to-Video preview

Gemini Omni 1.1 Flash Reference-to-VideoGemini Omni 1.1 Flash Reference-to-Video. Use 1–7 images to guide characters, products, and style in new video scenes with sound.

Gemini Omni 1.1 Flash Video Edit preview

Gemini Omni 1.1 Flash Video EditGemini Omni 1.1 Flash Video Edit. Edit 3–10 second videos through natural language with up to 5 reference images for visual guidance.

MiniMax H3 Max Turbo Text to Video preview

MiniMax H3 Max Turbo Text to VideoMiniMax H3 Max Turbo Text to Video turns text into coherent 5–15 second videos with synchronized native stereo audio and fast generation. It follows physical motion while rendering subtle changes in light and shadow.

FLUX 3 Max Keyframes to Video API FAQ

What is the FLUX 3 Max Keyframes to Video API?

FLUX 3 Max Keyframes to Video is a video model post-trained by fal in collaboration with Black Forest Labs for generating video from timed keyframes. It turns 1–10 images pinned to frame positions into one 5–20 second 720p or 1080p clip with native audio. Built on the FLUX 3 video base, it holds each image at its frame on a 24 fps timeline while generating continuous motion and sound between them. You can call it programmatically or try it from the playground above.

How do I calculate frame_index for FLUX 3 Max Keyframes to Video?

Multiply the time in seconds by 24. For a 5-second clip, frames 0, 60 and 120 mark the start, middle and end; for 10 seconds the last frame is 240. Each value must be unique.

How many keyframes can FLUX 3 Max Keyframes to Video take?

Send 1 to 10 keyframes. Each item contains only image_url and frame_index, and the frames can be in any position up to duration × 24.

What happens when a FLUX 3 Max keyframe sits beyond the clip length?

The request is rejected with a 400 error that names the keyframe. Increase duration or move the frame so frame_index stays within 0 to duration × 24.

Which aspect ratio does FLUX 3 Max Keyframes to Video use?

With aspect_ratio on auto, the output follows the first keyframe image. Pick one of the seven fixed ratios to frame the sequence for a specific platform.

Does the number of keyframes change the FLUX 3 Max price?

No. FLUX 3 Max Keyframes to Video costs 34 credits per output second at 720p and 58 at 1080p, so an 8-second 720p clip is 272 credits with one keyframe or ten.

How do FLUX 3 Max keyframes compare with start and end frames?

FLUX 3 Max Image to Video fixes only the opening and closing frames. Keyframes to Video adds intermediate images at exact times, which gives more control over pacing and the order of events.