Flux Dev Image to Image API

blackforestlabs/flux/dev/image-to-image

1 image · png/jpeg

Flux Dev Image to Image transforms a single reference image using descriptive natural language prompts, combining consistent visual guidance with flexible canvas proportions. It maintains primary subject contours, spatial perspective, and lighting mood while applying text-directed material changes, background scene adjustments, and artistic restyling.

Input

Prompt

Image Urls

Upload Image

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 bold Fauvist oil painting on rough linen canvas of a golden dog running on a beach. PAINTING, not a photograph. Broad angular strokes of ochre, terracotta and cream construct the complete dog in SIDE PROFILE facing RIGHT, tail to the LEFT; keep the overall dog silhouette and beach subject from the reference. Four natural legs in a running stride. The entire animal fits comfortably in the lower half of the portrait canvas. Build the sea and sky from large flat patches of muted teal, pale blue and warm grey. Scraped palette-knife impasto, thick raised paint ridges, broken color and visible bristle marks across every part of the composition, simplified shapes, expressive brushwork, deliberately painterly edges. An unframed full-bleed fine-art painting with no decorative border, no lettering, no signature, no watermark.

Use the supplied photograph as the fixed composition for a seasonal weather variation. Show the SAME entire dark-green step-through bicycle from the SAME SIDE VIEW: front wheel and wicker front basket on the LEFT, rear wheel and saddle on the RIGHT, two wheels side by side and both fully visible. Keep the pale plaster wall directly behind the bicycle, the wooden gate on the far LEFT and the leafy tree above the wall on the RIGHT. Preserve the original wide camera position, lens perspective, bicycle position and scale. Change only the weather, ground moisture and foliage: soft overcast autumn daylight, fine rain, wet stone paving with small puddles, scattered russet leaves, and amber foliage on the existing tree. Realistic gentle reflections, naturally aged materials and subtle rain streaks. A quiet residential courtyard, not an alley. Do not rotate the bicycle or move the camera. No rear view, no people, no extra bicycles, no text, no logos, no watermark.

REST API

Quick Start

This flow submits one valid Flux Dev Image 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, and ordered image URLs 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/image-to-image",
  "input": {
    "prompt": "Reimagine this same reading room as a warm and inviting evening interior. Retain the principal perspective, the large window on the left, the central rectangular table and chairs, and the low shelves on the right. Replace the cold concrete wall finish with warm light-oak paneling and the floor with natural oak planks; give the chairs comfortable muted rust-colored upholstery. Add subtle warm reading light above the table and a gentle glow along the shelves. Through the existing window, show the soft blue light of dusk. Realistic architectural photography with convincing wood grain, fabric texture and balanced warm interior light against cool outdoor light. The room remains simple, unoccupied and clearly related to the original layout. No text, logos, commercial styling or watermark.",
    "n": 1,
    "output_format": "png",
    "image_urls": [
      "https://cdn.vidgo.ai/apis/models/blackforestlabs/flux/dev/image-to-image/v1/01/input.png"
    ]
  }
}'

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": "I0RYI5JVOJC6CR8I",
    "status": "running",
    "created_time": "2026-09-25T11:22:15"
  }
}

Finished response

{
  "code": 200,
  "data": {
    "task_id": "I0RYI5JVOJC6CR8I",
    "status": "finished",
    "files": [
      {
        "file_url": "https://cdn.vidgo.ai/apis/models/blackforestlabs/flux/dev/image-to-image/v1/01/output.png",
        "file_type": "image"
      }
    ],
    "created_time": "2026-09-25T11:22:15",
    "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/image-to-image",
  "input": {
    "prompt": "Reimagine this same reading room as a warm and inviting evening interior. Retain the principal perspective, the large window on the left, the central rectangular table and chairs, and the low shelves on the right. Replace the cold concrete wall finish with warm light-oak paneling and the floor with natural oak planks; give the chairs comfortable muted rust-colored upholstery. Add subtle warm reading light above the table and a gentle glow along the shelves. Through the existing window, show the soft blue light of dusk. Realistic architectural photography with convincing wood grain, fabric texture and balanced warm interior light against cool outdoor light. The room remains simple, unoccupied and clearly related to the original layout. No text, logos, commercial styling or watermark.",
    "n": 1,
    "output_format": "png",
    "image_urls": [
      "https://cdn.vidgo.ai/apis/models/blackforestlabs/flux/dev/image-to-image/v1/01/input.png"
    ]
  }
}
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 transformation instruction containing at least one non-whitespace character.
input.image_urls	string[]	Yes	–	Array containing exactly one valid HTTP(S) reference image URL.
input.size	string	No	1:1	Output canvas size preset or custom WIDTHxHEIGHT with positive integers. Omitted to follow source image aspect ratio. 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/image-to-image	Single-image editing.
output_format	png · jpeg	Defaults to png.

Flux Dev Image to Image API API documentation

Flux Dev Image to Image

Flux Dev Image to Image is a 12-billion-parameter (12B) flow-matching image transformation model developed by Black Forest Labs. By pairing a single public reference image with natural language prompts, the model restyles artistic elements, swaps surface materials, and transforms backgrounds while preserving subject contours, spatial perspective, and lighting mood. It supports 6 preset aspect ratios as well as custom pixel dimensions, defaulting to source guidance and 1:1 billing when size is omitted, outputs in PNG or JPEG format at 4 credits ($0.020) per megapixel, with automatic refunds on task failures.

Why Choose Flux Dev

Subject Contour & Layout RetentionGuides restyling through reference imagery while retaining primary spatial positioning, subject silhouettes, and lighting mood.
Lightweight Single-Image GuidanceRequires only one publicly accessible HTTP(S) image link to establish a reliable visual foundation for prompt transformations.
Text-Directed Style RestylingAdjusts surface textures, lighting atmosphere, and background environments through expressive natural language directions.
Flexible Sizing & Format SupportInherits source dimensions by default or accepts explicit preset and custom pixel sizes, outputting in high-grade PNG or JPEG.
Transparent Pricing & Automatic RefundsBilled per megapixel at 4 credits ($0.020) per MP with full automatic refunds if a generation task terminates abnormally.

Parameters

Parameter	Requirement	Description
prompt	Required	Image transformation instruction containing at least one non-whitespace character.
image_urls	Required	Array containing exactly one valid HTTP(S) reference image URL.
size	Optional	Output canvas size preset or custom WIDTHxHEIGHT with positive integers. Omitted to follow source image aspect ratio. 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

Supply 1 Reference Image URLProvide a single accessible HTTP or HTTPS image URL inside the image_urls array as the transformation base.
Write Transformation InstructionsClearly describe target aesthetic modifications, material textures, or environmental changes in the prompt.
Configure Dimensions and Output FormatOmit size to follow the reference image or specify custom dimensions, and select PNG or JPEG format.
Submit Task and Poll StatusSend your API request to retrieve a task_id and poll the task endpoint until status transitions to finished.
Retrieve Generated ImageryExtract the finished image URLs directly from data.files[].file_url in the completed response payload.

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.
Image to Image Default	4 × n credits	When size is omitted in requests, pricing defaults to 1:1. Explicitly specifying size changes the charge; generation is guided by the reference image.

Best Use Cases

Product Photography Scene StagingTransport clean studio product photos into lifestyle or outdoor settings to reduce physical staging costs.
Character & Portrait Style ReimaginingUpdate wardrobe, makeup aesthetics, or atmospheric lighting on portrait photos while preserving identity contours.
Design Sketch MaterializationTransform conceptual line art, layout sketches, or simple 3D models into rendered artwork with realistic lighting.
Cross-Genre Artistic Style TransferReinterpret photography into expressive oil painting, watercolor, illustration, or other distinct visual movements.

Pro Tips

Focus your prompt primarily on the elements and styles you wish to modify; unchanged subjects do not need repeated descriptions.
Provide reference images with well-defined subjects and clear lighting to ensure the model captures the core composition effectively.
If the transformed scene requires lettering, enclose the words in quotation marks to activate legible text rendering.
Match your output aspect ratio closely to the reference image proportion to prevent unexpected cropping or perspective distortion.
Use JPEG format for quick turnaround previews and reserve PNG for production deliverables and print media.

Notes

Single image requirement: The image_urls array must contain exactly one accessible HTTP(S) image URL.
Prompt requirement: The prompt parameter is required and must contain at least one non-whitespace character after trimming.
Pricing defaults: Omitting size follows reference guidance with a default 1:1 (4 credits) charge; explicit sizes are billed by canvas pixels.
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 Image to Image API frequently asked questions

What is the Flux Dev Image to Image API?

Flux Dev Image to Image is Black Forest Labs' 12-billion-parameter rectified flow transformer model designed for reference-guided visual transformations and style restyling. By pairing a single public source image with descriptive natural language prompts, it transforms surface textures, scene backgrounds, and stylistic genres while preserving original subject silhouettes, spatial layout, and lighting mood. Built on an advanced flow-matching architecture with guidance distillation, it ensures visual coherence across transformation workflows. You can call it programmatically or try it from the playground above.

What are the requirements for input images in Flux Dev Image to Image?

Supply the reference image as an array containing exactly one publicly accessible HTTP or HTTPS URL within the image_urls field. The URL should point to a standard static image format such as PNG or JPEG.

How is output image size determined in Flux Dev Image to Image?

When the size parameter is omitted, the API generates imagery guided by the reference image with pricing defaulting to 1:1 (4 credits per image). You can also explicitly specify presets such as 16:9 or custom WIDTHxHEIGHT pixel dimensions when a fixed aspect ratio is desired.

How can I maintain subject contours when using Flux Dev Image to Image?

Focus your prompt specifically on the changes you want to introduce—such as new background scenery, attire, or color palette—rather than over-describing static attributes. Using a reference image with distinct subject boundaries and balanced lighting further ensures reliable contour retention.

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

Pricing matches text-to-image at 4 credits ($0.020) per billable megapixel (MP). Omitting size or selecting presets such as 1:1, 4:3, 16:9, or 9:16 costs 4 credits ($0.020) per image, while 1:1 HD costs 8 credits ($0.040). If a task fails to generate an output, all deducted credits are fully and automatically refunded.

Which model should I use if I need to provide multiple reference images?

Flux Dev Image to Image is designed specifically for single-image guidance. For advanced tasks requiring composition from multiple visual inputs (up to 8 reference images), select the Flux 2 Pro Edit model.

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

Flux Dev Image to Image supports png and jpeg formats via the output_format parameter. If omitted from your request, the API defaults to delivering lossless png images.

Which endpoint should I use when I do not have a reference image?

When generating new artwork entirely from text descriptions without an existing photo, use the dedicated Flux Dev Text to Image endpoint.