Black Forest Labs Flux 3 Start End To Video API Documentation

Black Forest Labs Flux 3 Start End To Video API Documentation

Playground

FLUX 3 Start-End-to-Video generates 5-20 second transition videos between required start and end images, using prompt guidance to control action, camera movement, visual style, motion continuity, and optional synchronized audio at 720P / 1080P output. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

FLUX 3 Start-End-to-Video generates a video transition between a required starting image and a required ending image. Use the prompt to define the action, transformation, camera movement, pacing, and visual style that connect the two keyframes, with optional synchronized audio.

Key Capabilities

• Generate a controlled transition between a start image and an end image.
• Use prompts to define the subject movement, transformation, camera path, environment, and visual style between keyframes.
• Generate optional synchronized audio for the transition.
• Choose 720p or 1080p output and a duration from 5 to 20 seconds.
• Support landscape, portrait, square, and cinematic aspect ratios.

Parameters

How to Use

1. Provide the image that should appear at the beginning of the video.
2. Provide the image that should appear at the end of the video.
3. Describe the movement, transformation, camera path, and pacing that should connect the two keyframes.
4. Choose the aspect ratio, resolution, duration, and whether synchronized audio should be generated.
5. Submit the request and download the generated transition after processing is complete.

Prompting Tips

• Describe the intended visual path from the start image to the end image rather than listing unrelated scenes.
• Explain what moves, transforms, appears, disappears, or changes between the keyframes.
• Use camera directions such as dolly-in, pull-back, orbit, tracking shot, or crane movement to shape the transition.
• Specify how quickly the transition should happen and which visual details must remain stable.

Pricing

Pricing is calculated by billed video duration and output resolution.

Billing Rules

• The billed duration is rounded up to the next whole second.
• The API accepts durations from 5 to 20 seconds.
• The maximum billed duration is 20 seconds.
• Audio generation does not add a separate charge in the current pricing formula.
• Example: a 10-second 720p video costs $1.70.
• Example: a 10-second 1080p video costs $2.90.

Best Use Cases

• Product reveals, logo transitions, and before-and-after presentations.
• Character transformations and outfit or environment changes.
• Keyframe-based story moments, advertisements, and social media transitions.
• Creative experiments that need a defined beginning and ending state.

Notes

• Prompt, image, and last_image are required.
• Use visually compatible start and end images when you want a smooth transition.
• Generated motion and audio may vary depending on the distance between the two keyframes and the prompt detail.

Related Models

• FLUX 3 Start-End-to-Video — Generate video using both a starting frame and an ending frame.
• FLUX 3 Image-to-Video — Animate a reference image into a video.
• FLUX 3 Video Extend — Extend an existing video with new generated footage.
• FLUX 3 Text-to-Video — Generate video directly from a text prompt.

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",
  "image": "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg",
  "last_image": "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg",
  "aspect_ratio": "21:9",
  "resolution": "720p",
  "duration": 5,
  "generate_audio": true
}
JSON
)

# 1. Submit the prediction once. Never retry this request automatically:
# a retry after an unclear failure can create a second, billed task.
CHECK='The task may already exist. Check History or the predictions list before submitting again.'
if ! SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --connect-timeout 10 --max-time 60 \
  -X POST "https://api.wavespeed.ai/api/v3/black-forest-labs/flux-3/start-end-to-video" \
  -H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}"); then
  printf 'Submit failed. %s\n' "${CHECK}" >&2
  exit 1
fi

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. %s\n' "${CHECK}" >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

# 2. Poll until the prediction reaches a final status.
BODY_FILE=$(mktemp)
trap 'rm -f "${BODY_FILE}"' EXIT
while true; do
  # Transient errors (429, 5xx) are retried, honoring Retry-After.
  HTTP_CODE=$(curl --silent --show-error --fail-with-body \
    --connect-timeout 10 --max-time 60 --retry 5 --retry-delay 2 \
    --output "${BODY_FILE}" --write-out '%{http_code}' \
    "${RESULT_URL}" \
    -H "Authorization: Bearer ${WAVESPEED_API_KEY}" || true)
  case "${HTTP_CODE}" in
    2??) ;;
    000|429|5??)  # dropped connection or temporary error: keep polling
      printf 'Task %s: HTTP %s, polling again in 10s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
      sleep 10; continue ;;
    *) printf 'Task %s: HTTP %s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
      cat "${BODY_FILE}" >&2; exit 1 ;;
  esac
  RESULT=$(jq 'if type == "object" and has("data") then .data else . end' "${BODY_FILE}")
  STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')

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

Parameters

Task Submission Parameters

Request Parameters

Every model also accepts the global request options enable_sync_mode and enable_base64_output; see their pages for details.

Response Parameters

Result Request Parameters

Result Response Parameters