Black Forest Labs Flux 3 Edit API Documentation

Black Forest Labs Flux 3 Edit API Documentation

Playground

FLUX 3 Image Edit transforms and combines up to 10 input images using natural-language instructions, with flexible 1K / 2K / 4K output for multi-image composition, visual refinements, creative edits, marketing assets, and production workflows. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

FLUX 3 Image Edit transforms and combines existing images using natural-language instructions. Provide between 1 and 10 input images, explain the role of each reference in the prompt, and generate a new composition at up to 4K resolution.

Use it for subject-guided edits, product compositions, style changes, typography, advertising creatives, and multi-reference workflows where elements from several images need to be combined into one result.

Why Choose This?

• Multi-image editing
  Combine up to 10 input images in a single generation.

• Reference-guided composition
  Assign different roles to each image, such as taking a subject from one reference and placing it into the scene from another.

• Up to 4K output
  Choose 1K, 2K, or 4K depending on your quality and production requirements.

• Typography and layout control
  Describe exact text, placement, hierarchy, and composition directly in the prompt.

• Flexible aspect ratios
  Choose from a wide range of landscape, portrait, square, and ultrawide layouts.

• Prompt expansion
  Enable automatic prompt expansion when additional interpretation is useful.

Parameters

How to Use

1. Upload the source images — Provide between 1 and 10 images in the order you want to reference them.
2. Write the edit instruction — Describe what should change and explain the role of each image.
3. Choose aspect ratio optional — Select an output layout or leave it empty to follow the first input image.
4. Choose resolution — Select 1k, 2k, or 4k.
5. Configure prompt expansion optional — Enable it when you want the prompt expanded automatically.
6. Choose output format — Select jpeg or png.
7. Submit — Generate and retrieve the edited image.

Pricing

Pricing is based only on the selected resolution.

Best Use Cases

• Multi-reference compositions — Combine subjects, products, environments, or visual elements from several source images.
• Product imagery — Place products into new scenes or combine product references with campaign visuals.
• Advertising creatives — Build commercial concepts from multiple visual references.
• Subject-guided editing — Use one image to guide a person, object, or other subject in another composition.
• Style transformation — Change materials, lighting, colors, or overall visual direction.
• Typography and poster design — Modify or create compositions containing text and structured layouts.
• Editorial and social content — Produce new visuals from existing assets for publishing and social media.

Pro Tips

• Refer to each input clearly as image 1, image 2, and so on.
• Explain the role of every important reference instead of simply uploading multiple images without instructions.
• State both what should change and what should remain unchanged when precision matters.
• Put exact text that should appear in the output inside quotation marks.
• Describe where subjects, products, or text should appear in the final composition.
• Use 1k for lower-cost iteration before moving to 2k or 4k.
• Use fewer references when several images provide conflicting visual guidance.
• Choose png when you want to avoid additional JPEG compression.

Related Models

• FLUX 3 Text-to-Image — Generate images directly from text prompts with resolutions up to 4K.
• FLUX 3 Edit — Edit and combine up to ten input images with natural-language instructions.

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",
  "images": [
    "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg"
  ],
  "aspect_ratio": "21:9",
  "resolution": "1k",
  "output_format": "jpeg",
  "enable_prompt_expansion": false
}
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/edit" \
  -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