Black Forest Labs Flux 3 Text To Video Draft API Documentation

Black Forest Labs Flux 3 Text To Video Draft API Documentation

Playground

FLUX 3 Text-to-Video Draft generates short draft videos from text prompts with coherent motion, prompt-guided camera direction, optional synchronized audio, and pricing optimized for rapid iteration.

Features

FLUX 3 Draft Text-to-Video turns a written prompt into a fast draft video preview with coherent motion and prompt-guided scene composition. It is designed for rapid ideation, storyboarding, prompt iteration, and testing creative directions before moving to a final-quality workflow.

Why Choose This?

• Text-to-video draft generation
  Generate draft videos directly from natural-language prompts.

• Fast creative testing
  Explore subject behavior, scene structure, camera movement, lighting, pacing, and visual style quickly.

• Prompt-guided motion
  Describe action, timing, camera direction, environment, mood, and style in one prompt.

• Optional synchronized audio
  Generate matching audio for early ambience, effects, music, or dialogue tests.

• Flexible duration
  Choose a draft video duration from 5 to 20 seconds.

• Multiple aspect ratios
  Supports landscape, portrait, square, and cinematic formats.

Parameters

How to Use

1. Write the prompt — Describe the subject, action, setting, camera movement, timing, lighting, mood, and visual style.
2. Choose aspect ratio — Select the output format that matches your target use case.
3. Set duration — Choose a draft duration from 5 to 20 seconds.
4. Configure audio optional — Enable generate_audio when you want to test ambience, effects, music, or dialogue.
5. Generate variations — Compare motion, composition, and pacing across multiple drafts.
6. Refine the prompt — Adjust the scene direction before moving to a final-quality workflow.

Pricing

Pricing is based on billed video duration.

Billed duration is rounded up to the next whole second and capped at 20 seconds. The API accepts durations from 5 to 20 seconds. Audio generation does not add a separate charge.

Example Costs

Best Use Cases

• Rapid prompt testing — Test different scene ideas, actions, and visual styles quickly.
• Storyboarding — Turn written concepts into motion previews for planning and review.
• Pre-visualization — Explore camera movement, pacing, and scene composition before production.
• Social video concepts — Draft vertical, square, landscape, or cinematic content ideas.
• Advertising drafts — Test early product-video, brand, or campaign directions.
• Motion comparison — Compare multiple camera paths or timing choices from the same concept.

Pro Tips

• Start with one clear action so the draft has a focused motion target.
• Include the subject, setting, action, camera movement, lighting, mood, and style.
• Add camera instructions such as tracking shot, dolly-in, orbit, zoom, tilt, or locked-off frame.
• Use short timing cues when the scene has multiple beats.
• Keep the first prompt simple, then add more secondary details after the motion direction is stable.
• Use shorter durations for quick iteration and longer durations when the scene needs more time to unfold.

Related Models

• FLUX 3 Draft Start-End-to-Video — Generate a draft transition between a start image and an end image.
• FLUX 3 Draft Image-to-Video — Animate a reference image into a draft video.
• FLUX 3 Draft Video Extend — Extend an existing video with a new draft continuation.

Authentication

For authentication details, please refer to the Authentication Guide.

API Endpoints

Submit Task & Query Result

set -euo pipefail

export WAVESPEED_API_KEY="your-api-key"

REQUEST_BODY=$(cat <<'JSON'
{
  "prompt": "A cinematic ocean wave at sunrise, highly detailed",
  "aspect_ratio": "16:9",
  "duration": 5,
  "generate_audio": true
}
JSON
)

# 1. Submit the prediction.
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  -X POST "https://api.wavespeed.ai/api/v3/black-forest-labs/flux-3/text-to-video-draft" \
  -H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}")

TASK=$(printf '%s' "${SUBMIT_RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
PREDICTION_ID=$(printf '%s' "${TASK}" | jq -r '.id // empty')
if [ -z "${PREDICTION_ID}" ]; then
  printf 'Submission response did not contain a prediction id
' >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

# 2. Poll until the prediction finishes.
while true; do
  RESPONSE=$(curl --silent --show-error --fail-with-body \
    "${RESULT_URL}" \
    -H "Authorization: Bearer ${WAVESPEED_API_KEY}")
  RESULT=$(printf '%s' "${RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
  STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')

  case "${STATUS}" in
    completed) printf '%s\n' "${RESULT}" | jq '.outputs'; break ;;
    failed|cancelled|timeout|deleted) printf '%s\n' "${RESULT}" | jq . >&2; exit 1 ;;
    *) sleep 2 ;;
  esac
done

Parameters

Task Submission Parameters

Request Parameters

Response Parameters

Result Request Parameters

Result Response Parameters