Flux Dev Text to Image API

blackforestlabs/flux/dev

6 sizes · png/jpeg

Flux Dev Text to Image transforms descriptive natural language prompts into photorealistic images with strong prompt adherence, natural lighting, and native text rendering across flexible canvas proportions. It handles human anatomical details and spatial depth while rendering readable quoted lettering and cohesive graphic elements.

Input

Prompt

Size

Output Format

OutputIdle

Generated images will appear here

Estimated Cost: 1 MP × 1 × 4 = 4 credits · $0.020

Billed at 4 credits per billable MP multiplied by image count; 1 credit = $0.005.

Examples

A vertical environmental photograph from deep inside a vast natural blue glacier cave. One small adult explorer wearing a burnt-orange parka, dark trousers and a climbing helmet stands in the lower third on solid textured ice, seen from behind in a stable natural stance. A modest warm-white headlamp illuminates a nearby translucent ridge. Towering curved walls of aquamarine ice sweep upward around the explorer, with intricate trapped bubbles and layered striations visible in the foreground; pale daylight enters through a narrow opening far above. Strong sense of human scale, physically plausible ice translucency, controlled blue and amber color contrast, deep spatial perspective, crisp near textures and gentle distant haze, documentary adventure photography, no text, no logos, no watermark.

A wide surreal fine-art landscape with a single enormous manta-ray-shaped cloud floating slowly above ochre desert dunes. The ray is made entirely of soft white cloud vapor, with broad gracefully curved wings and a long delicate cloud tail, recognizable as a manta silhouette rather than a solid animal. Late afternoon sunlight gives the vapor luminous edges, while its broad soft shadow falls naturally across the wind-sculpted sand. One tiny solitary traveler in a dark cloak stands on a distant dune ridge at the lower right, emphasizing the vast scale. A pale clear sky, long elegant dune curves, quiet wonder, cinematic depth and carefully balanced negative space, detailed sand ripples in the foreground, no buildings, no vehicles, no typography, no logo, no watermark.

REST API

Quick Start

This flow submits one valid Flux Dev Text to Image API request, captures its task_id, and reads image URLs after the asynchronous task ends.

Connect to the Vidgo API

Create an API key, keep it on the server, and send it as Authorization: Bearer VIDGO_API_KEY.

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

Submit one image task

Send the current model ID, prompt to the unified submit endpoint. The example keeps only first-call fields.

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/dev",
  "input": {
    "prompt": "An intimate documentary photograph of an elderly violin restorer in a small lived-in workshop, viewed from slightly above bench height. The craftsman wears a faded indigo work shirt and round spectacles, leaning forward to inspect the curved varnished body of one antique violin resting on a folded linen cloth. One hand steadies the violin gently while the other holds a small inspection light. A large window on the left casts soft directional afternoon daylight across his lined face, amber wood grain, delicate wood shavings, a steel chisel and worn workbench. A few unfinished violin shapes hang softly out of focus in the background. Quiet concentration, believable hands and tools, rich natural material textures, subtle film grain, restrained warm colors, one coherent scene, no staged product display, no lettering, no logos, no watermark.",
    "n": 1,
    "output_format": "png",
    "size": "4:3"
  }
}'

Wait for the image result

Read data.task_id and poll only while status is not_started or running. Stop on both finished and failed.

Track status

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

Poll every 2–5 seconds and back off on 429/5xx. Or provide top-level callback_url to receive a terminal-state callback.

not_startedrunningfinishedfailed

Submit response

{
  "code": 200,
  "data": {
    "task_id": "ZOBDNFN25SVGKU85",
    "status": "running",
    "created_time": "2026-09-25T11:20:26"
  }
}

Finished response

{
  "code": 200,
  "data": {
    "task_id": "ZOBDNFN25SVGKU85",
    "status": "finished",
    "files": [
      {
        "file_url": "https://cdn.vidgo.ai/apis/models/blackforestlabs/flux/dev/v1/01/output.png",
        "file_type": "image"
      }
    ],
    "created_time": "2026-09-25T11:20:26",
    "error_message": null,
    "progress": 100
  }
}

Complete runnable polling example

Expand for the same payload end to end, including business-code, missing-task-ID, failed-state, unexpected-state, and network-error handling.

Complete runnable polling example

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

REQUEST_BODY=$(cat <<'JSON'
{
  "model": "blackforestlabs/flux/dev",
  "input": {
    "prompt": "An intimate documentary photograph of an elderly violin restorer in a small lived-in workshop, viewed from slightly above bench height. The craftsman wears a faded indigo work shirt and round spectacles, leaning forward to inspect the curved varnished body of one antique violin resting on a folded linen cloth. One hand steadies the violin gently while the other holds a small inspection light. A large window on the left casts soft directional afternoon daylight across his lined face, amber wood grain, delicate wood shavings, a steel chisel and worn workbench. A few unfinished violin shapes hang softly out of focus in the background. Quiet concentration, believable hands and tools, rich natural material textures, subtle film grain, restrained warm colors, one coherent scene, no staged product display, no lettering, no logos, no watermark.",
    "n": 1,
    "output_format": "png",
    "size": "4:3"
  }
}
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

This table lists only public fields inside input. See Quick Start for top-level model and optional callback_url usage.

Field	Type	Required	Default	Description
input.prompt	string	Yes	–	Image generation prompt containing at least one non-whitespace character.
input.size	string	No	1:1	Canvas size preset or custom WIDTHxHEIGHT with positive integers. 1:1, 1:1 HD, 4:3, 3:4, 16:9, 9:16, WIDTHxHEIGHT.
input.n	integer	No	1	Number of images to generate as a positive integer, defaults to 1.
input.output_format	string	No	png	Output image format, supports png or jpeg, defaults to png. png, jpeg.

Response Fields

The submit response identifies the task. The status response supplies image files or failure details at a terminal state.

Field	Type	Description
code	integer	Business response code; 0 or 200 indicates success.
message	string	Optional human-readable response message.
data.task_id	string	Unique task ID used for status queries after submission.
data.status	string	not_started, running, finished, or failed.
data.created_time	string	Task creation timestamp.
data.progress	integer	Progress from 0–100 in status responses.
data.files[]	array	Generated files in returned order when finished.
data.files[].file_url	string	Direct generated-image URL.
data.files[].file_type	string	Image results are identified as image.
data.files[].watermark_url	string \| null	Optional watermarked-file URL when present.
data.error_message	string \| null	Readable failure reason for failed tasks.

Task Lifecycle

Only the first two states may be polled again. finished and failed are terminal.

not_started
Accepted and queued; wait before checking again.
running
Image generation is in progress; continue polling.
finished
Successful terminal state; validate files and read image URLs.
failed
Failure terminal state; read error_message and stop.

Polling and Errors

Authentication401 means the key is missing or invalid. Fix authentication before resubmitting and never expose the key in browser code.
Validation400 indicates an invalid model ID, field, enum, length, or image count.
Polling intervalStart at 2–5 seconds, use exponential backoff for 429/5xx, and enforce an overall timeout.
Terminal statesStop after finished or failed. Treat finished without a valid image as a separate error.
Callback optionProvide a public top-level callback_url to receive a flat task object after finished or failed.
Network errorsDistinguish request timeout, network failure, and task failure. Retry the same query only when safe.

Model Specifications

Specification	Value	Details
Model	blackforestlabs/flux/dev	Text-to-image generation.
output_format	png · jpeg	Defaults to png.

Flux Dev Text to Image API API documentation

Flux Dev Text to Image

Flux Dev Text to Image is a 12-billion-parameter (12B) flow-matching diffusion transformer model developed by Black Forest Labs, designed to produce high-fidelity realistic imagery from natural language prompts. Utilizing guidance distillation, it offers balanced performance across anatomical details, lighting textures, prompt adherence, and native English typography. It supports 6 standard canvas presets as well as custom WIDTHxHEIGHT dimensions with positive integers, outputs in PNG or JPEG format, and features transparent pricing at 4 credits ($0.020) per megapixel with automatic refunds on task failures.

Why Choose Flux Dev

Native Typography RenderingAccurately renders embedded English text, signs, and posters by simply enclosing target words in quotation marks within the prompt.
12B Flow-Matching BackboneCombines a 12-billion-parameter rectified flow transformer architecture with guidance distillation for detailed imagery and efficient inference.
Nuanced Prompt AdherenceInterprets multi-subject spatial layouts, tactile surface materials, and distinct visual aesthetics to match your prompt vision.
Flexible Presets & Custom DimensionsProvides 6 built-in presets (1:1, 1:1 HD, 4:3, 3:4, 16:9, 9:16) along with support for custom WIDTHxHEIGHT pixel specifications.
Megapixel Pricing & Refund ProtectionCharges transparently at 4 credits ($0.020) per billable MP, rounded up per image, with full automatic credit refunds if a task fails.

Parameters

Parameter	Requirement	Description
prompt	Required	Image generation prompt containing at least one non-whitespace character.
size	Optional	Canvas size preset or custom WIDTHxHEIGHT with positive integers. Default`1:11:1 HD4:33:416:99:16WIDTHxHEIGHT`
n	Optional	Number of images to generate as a positive integer, defaults to 1. Default`1`
output_format	Optional	Output image format, supports png or jpeg, defaults to png. Default`pngjpeg`

How to Use

Craft Prompt and TypographyDetail subject attributes, lighting, and perspective; enclose any lettering in double quotation marks to guide in-image typography.
Select Aspect Ratio and SizeChoose from presets such as 1:1, 16:9, or 9:16, or define custom dimensions using WIDTHxHEIGHT positive integer pixel counts.
Set Image Count and Output FormatSpecify the number of images to generate via parameter n, and select either lossless PNG or compact JPEG format.
Submit Task and Poll StatusInitiate a POST request with your API key, obtain the task_id, and query task status until it reaches finished.
Download Generated ImageryRetrieve the high-quality generated image URLs directly from data.files[].file_url in the completed response.

Pricing

Billed per submitted parameters at 4 credits ($0.020) per billable MP. Canvas pixel count is rounded up to the nearest integer MP (minimum 1 MP) and multiplied by n; failed tasks are automatically refunded.

Usage	Rate	Details
Unit Price	4 credits/MP · $0.020/MP	1 MP = 1,000,000 pixels, calculated per image.
1:1 · 4:3 · 3:4 · 16:9 · 9:16	4 credits/image · $0.020/image	Each of these presets corresponds to 1 billable MP.
1:1 HD · 1024x1536	8 credits/image · $0.040/image	Each of these dimensions corresponds to 2 billable MP.
Custom Dimensions	max(1, ceil(W × H / 1,000,000)) × n × 4 credits	Calculated dynamically using the submitted size and n parameters.

Best Use Cases

Commercial Posters and Promotional BannersCreate marketing materials featuring clean typography, readable brand slogans, and structured studio lighting.
Concept Art and WorldbuildingRapidly ideate architectural environments, character concepts, and visual atmospheres for game and film development.
E-Commerce Product ScenesProduce realistic tabletop staging, lifestyle backgrounds, and catalog settings without costly physical studio setups.
Creative Visual ExplorationEnable design teams to iterate through diverse art styles, lighting moods, and compositions during client ideation phases.

Pro Tips

Wrap target text in double quotation marks and specify its medium, such as a neon sign, printed banner, or packaging label.
Structure your prompt progressively: describe the primary subject, environment context, lighting direction, and overall style.
Decide on your aspect ratio before finalizing the prompt so the model can optimize the composition for the canvas layout.
Use positive natural language to describe preferred details, materials, and colors rather than relying on broad abstract adjectives.
Keep custom canvas dimensions near 1 to 2 megapixels to maintain optimal structural coherence and cost efficiency.

Notes

Prompt requirement: The prompt parameter is required and must contain at least one non-whitespace character after trimming.
Canvas calculation: Image pixel dimensions (Width × Height) are rounded up to the nearest whole megapixel, with a 1 MP minimum per image.
Output format support: The output_format parameter accepts png or jpeg, defaulting to png when omitted.
Automatic refund: Tasks that fail or terminate abnormally automatically refund all deducted credits to your account balance.

Related Models

Grok Imagine Image 2.0 Text to Image preview

Grok Imagine Image 2.0 Text to ImageGenerate crisp, high-fidelity images up to 2K from text prompts with Grok Imagine Image 2.0. Features designer-grade typography, precise prompt adherence, and versatile aspect ratios.

Grok Imagine Image 2.0 EditGenerate crisp, high-fidelity images up to 2K from text prompts with Grok Imagine Image 2.0. Features designer-grade typography, precise prompt adherence, and versatile aspect ratios.

Qwen Image 3.0 Text-to-ImageAlibaba Qwen Image 3.0 Standard and Pro generation and editing with eight aspect ratios, 1K or 2K output, and ordered one-to-three-image editing.

Qwen Image 3.0 Image EditAlibaba Qwen Image 3.0 Standard and Pro generation and editing with eight aspect ratios, 1K or 2K output, and ordered one-to-three-image editing.

Qwen Image 3.0 Pro Text-to-Image preview

Qwen Image 3.0 Pro Text-to-ImageAlibaba Qwen Image 3.0 Standard and Pro generation and editing with eight aspect ratios, 1K or 2K output, and ordered one-to-three-image editing.

Qwen Image 3.0 Pro Image EditAlibaba Qwen Image 3.0 Standard and Pro generation and editing with eight aspect ratios, 1K or 2K output, and ordered one-to-three-image editing.

Seedream 5.0 Pro Text-to-ImageThe ByteDance Seedream 5.0 Pro API generates 1K or 2K JPEG/PNG images from prompts and edits one to ten ordered HTTP(S) image inputs.

Seedream 5.0 Pro Image EditThe ByteDance Seedream 5.0 Pro API generates 1K or 2K JPEG/PNG images from prompts and edits one to ten ordered HTTP(S) image inputs.

Nano Banana 2 Lite Text to Image preview

Nano Banana 2 Lite Text to ImageGenerate crisp 1K images in ~4 seconds from text prompts with Nano Banana 2 Lite. Optimized for high-volume rapid iteration, in-image text in 25+ languages, and 10 aspect ratios at $0.025 per generation.

Nano Banana 2 Lite EditGenerate crisp 1K images in ~4 seconds from text prompts with Nano Banana 2 Lite. Optimized for high-volume rapid iteration, in-image text in 25+ languages, and 10 aspect ratios at $0.025 per generation.

Grok Imagine Image Quality Text to Image preview

Grok Imagine Image Quality Text to ImageGenerate high-fidelity images up to 2K resolution from text prompts with Grok Imagine Image Quality. Features photorealistic detail, sharp text rendering, and 5 aspect ratios.

Grok Imagine Image Quality EditGenerate high-fidelity images up to 2K resolution from text prompts with Grok Imagine Image Quality. Features photorealistic detail, sharp text rendering, and 5 aspect ratios.

GPT Image 2 Text-to-ImageOpenAI image generation and editing with quality tiers, flexible size controls, and single-image outputs up to 4K.

GPT Image 2 Image EditOpenAI image generation and editing with quality tiers, flexible size controls, and single-image outputs up to 4K.

Wan 2.7 Image Standard Text to Image preview

Wan 2.7 Image Standard Text to ImageCreate and edit images from prompts or reference photos with Wan 2.7 Image Standard and Pro models.

Wan 2.7 Image Standard EditCreate and edit images from prompts or reference photos with Wan 2.7 Image Standard and Pro models.

Flux Dev Text to Image API frequently asked questions

What is the Flux Dev Text to Image API?

Flux Dev Text to Image is a 12-billion-parameter text-to-image foundation model created by Black Forest Labs. It transforms detailed natural language prompts into photorealistic images with strong prompt adherence, balanced anatomical rendering, and native typography capabilities across preset or custom aspect ratios. Built on an advanced rectified flow transformer with guidance distillation, it interprets complex scene descriptions with natural lighting textures while rendering crisp quoted English lettering. You can call it programmatically or try it from the playground above.

What aspect ratios and canvas sizes does Flux Dev Text to Image support?

Flux Dev Text to Image supports six built-in canvas presets: 1:1 (512×512), 1:1 HD (1024×1024), 4:3 (1024×768), 3:4 (768×1024), 16:9 (1024×576), and 9:16 (576×1024). You can also provide custom WIDTHxHEIGHT dimensions such as 1024x1536 using positive integers, allowing flexible alignment with any display or print format.

How do I render specific text with Flux Dev Text to Image?

To render legible English lettering in your image, enclose the exact text in double quotation marks within the prompt and describe its context or physical medium, such as a street sign, neon signboard, or product label.

What is the generation cost for Flux Dev Text to Image?

Pricing is 4 credits ($0.020) per billable megapixel (MP). Canvas dimensions are rounded up to the nearest integer megapixel with a minimum of 1 MP per image. Standard presets including 1:1, 4:3, 3:4, 16:9, and 9:16 cost 4 credits ($0.020) each, while 1:1 HD costs 8 credits ($0.040). If a task fails, all deducted credits are automatically refunded.

Which image output formats are supported by Flux Dev Text to Image?

Flux Dev Text to Image supports both png and jpeg encoding via the output_format parameter. If omitted from your API request, the system defaults to high-fidelity, lossless png output.

Can I generate multiple images in a single request with Flux Dev Text to Image?

Yes. Set the n parameter to a positive integer to generate multiple images in one call. Total credits equal the single-image cost multiplied by n, and all completed image URLs are returned together in the data.files array.

How does Flux Dev compare with other models in the Flux family?

Flux Dev utilizes a 12B flow-matching transformer backbone with guidance distillation, delivering a well-balanced profile of detailed aesthetics, prompt fidelity, and typography suitable for frequent production iteration; for higher fidelity and complex multi-reference editing, creators can select the flagship Flux 2 Pro series.

Which endpoint should I use when generating from an existing reference photo?

When you have an existing source image and want to perform restyling, re-lighting, or visual modifications, use the dedicated Flux Dev Image to Image endpoint. The Text to Image endpoint is designed specifically for direct creation from text prompts.