Black Forest Labs Flux 3 Text To Image API Documentation

Black Forest Labs Flux 3 Text To Image API Documentation

Playground

FLUX 3 Text-to-Image generates high-quality images from text prompts with detailed composition, strong typography, and flexible 1K / 2K / 4K output for creative visuals, marketing assets, product imagery, and production workflows. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

FLUX 3 Text-to-Image generates detailed images directly from text prompts with strong composition control, typography support, and output resolutions up to 4K. Describe the subject, layout, lighting, materials, visual style, and any text that should appear in the image, then choose the aspect ratio and resolution that fit your workflow.

It is designed for advertising concepts, product visuals, posters, editorial artwork, social content, and other image-generation tasks where composition and text placement matter.

Why Choose This?

• Detailed text-to-image generation
  Create high-quality images directly from natural-language descriptions.

• 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 surrounding composition in the prompt.

• Flexible aspect ratios
  Generate square, portrait, landscape, widescreen, and ultrawide compositions.

• Prompt expansion
  Enable automatic prompt expansion when you want additional interpretation while preserving the intended content.

• JPEG and PNG output
  Choose the output format that fits your publishing or editing workflow.

Parameters

How to Use

1. Write a prompt — Describe the subject, scene, composition, lighting, materials, and visual style.
2. Specify text optional — Put exact words in quotation marks and describe where they should appear.
3. Choose aspect ratio — Select the layout that fits your target composition.
4. Choose resolution — Use 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 the image and retrieve the result.

Pricing

Pricing is based only on the selected resolution.

Best Use Cases

• Advertising creatives — Generate campaign concepts, key visuals, and promotional imagery.
• Product imagery — Create product concepts, presentation visuals, and packaging ideas.
• Poster design — Generate compositions with integrated text, hierarchy, and strong visual layout.
• Editorial artwork — Create illustrations, covers, and publication visuals.
• Social media content — Produce square, vertical, landscape, and widescreen creative assets.
• Typography-heavy concepts — Generate images where text placement and visual composition are important.
• High-resolution artwork — Use 2K or 4K when additional detail is needed for final production.

Pro Tips

• Put exact image text in quotation marks.
• Describe where text should appear relative to the subject and other visual elements.
• Start with the main subject and composition before adding stylistic details.
• Describe lighting, materials, color palette, and environment when they matter.
• Use 1K for lower-cost concept iteration before moving to higher resolutions.
• Use 4K when final output detail is more important than generation cost.
• Enable prompt expansion when a short prompt needs more descriptive interpretation.
• Choose png when you want to avoid additional JPEG compression.

Related Models

• FLUX 3 Text-to-Image — Generate images from text prompts with flexible composition and resolutions up to 4K.
• FLUX 3 Edit — Edit and combine 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",
  "aspect_ratio": "1:1",
  "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/text-to-image" \
  -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