Qwen Image 3.0 Image Edit API

alibaba/qwen-image-3.0/edit

1–3 images · Standard/Pro · 1K/2K

Qwen Image 3.0 Standard Image Edit API accepts a 1–5,000-character prompt and one to three ordered source-image URLs. Choose one of eight aspect ratios, 1K or 2K resolution, and PNG or JPEG output for the asynchronous image task.

Get API Key

Input

Prompt

510/5000

Reference images

1/3

Add images

Size

Resolution

Output format

Output

Ready

Continue with

Qwen Image 3.0 Standard Generate Qwen Image 3.0 Pro Edit Qwen Image 3.0 Pro Generate

Examples

Use image 1 as the only source. Preserve the exact heron anatomy and pose, feather detail, reeds, waterline, distant horizon, framing, and observational illustration style. Change only the time and weather from sunrise to a quiet blue hour just after rain: cool indigo ambient light, faint warm light on the horizon, small droplets on the reeds, and physically believable reflections in the water. Do not add or remove animals, plants, structures, writing, logos, products, promotional elements, or watermarks.

Image 1 defines the subject, exact bronze vessel silhouette, four bilingual labels, scale ruler, thumbnail drawings, and layout. Image 2 defines only the soft paper-cut color rhythm and flowing blue-path visual language. Preserve all content and wording from image 1, but reinterpret its background dividers and annotation arrows using the layered paper texture, blue-to-moss palette, and gentle connecting rhythm from image 2. Keep the vessel photographic and materially realistic. Do not copy objects or wording from image 2. No logos, products, sales context, promotional marks, extra text, or watermark.

Create one wide natural-history observation composition from three ordered sources without any writing. Image 1 supplies the scientifically plausible heron, wetland subject, and fine observational linework. Image 2 supplies the precise museum-object lighting, neutral archival paper, and realistic material rendering. Image 3 supplies the three-part visual rhythm and continuous blue flow path. Build three seamlessly connected visual zones showing habitat, anatomical form, and water movement, using imagery only. Keep the heron natural and use the bronze patina solely as a restrained color reference, never as an object in the result. No text, logo, brand, promotion, or watermark.

REST API

Quick Start

This flow submits one valid Qwen Image 3.0 Image Edit 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": "qwen-image-3.0/edit",
  "input": {
    "prompt": "Use image 1 as the only source. Preserve the exact heron anatomy and pose, feather detail, reeds, waterline, distant horizon, framing, and observational illustration style. Change only the time and weather from sunrise to a quiet blue hour just after rain: cool indigo ambient light, faint warm light on the horizon, small droplets on the reeds, and physically believable reflections in the water. Do not add or remove animals, plants, structures, writing, logos, products, promotional elements, or watermarks.",
    "size": "3:4",
    "resolution": "1K",
    "output_format": "jpeg",
    "prompt_extend": false,
    "negative_prompt": "changed heron anatomy, changed pose, extra animals, typography, text, logos, products, promotional badges, watermark",
    "seed": 31101,
    "enable_safety_checker": true,
    "image_urls": [
      "https://cdn.vidgo.ai/apis/models/alibaba/qwen-image-3.0/edit/v1/01/input-01.jpg"
    ]
  }
}'

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": "task-unified-...",
    "status": "not_started",
    "created_time": "2026-08-22T10:00:00Z"
  }
}

Finished response

{
  "code": 200,
  "data": {
    "task_id": "task-unified-...",
    "status": "finished",
    "files": [{
      "file_url": "https://storage.vidgo.ai/generated/image.png",
      "file_type": "image"
    }],
    "created_time": "2026-08-22T10:00:00Z",
    "progress": 100,
    "error_message": null
  }
}

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": "qwen-image-3.0/edit",
  "input": {
    "prompt": "Use image 1 as the only source. Preserve the exact heron anatomy and pose, feather detail, reeds, waterline, distant horizon, framing, and observational illustration style. Change only the time and weather from sunrise to a quiet blue hour just after rain: cool indigo ambient light, faint warm light on the horizon, small droplets on the reeds, and physically believable reflections in the water. Do not add or remove animals, plants, structures, writing, logos, products, promotional elements, or watermarks.",
    "size": "3:4",
    "resolution": "1K",
    "output_format": "jpeg",
    "prompt_extend": false,
    "negative_prompt": "changed heron anatomy, changed pose, extra animals, typography, text, logos, products, promotional badges, watermark",
    "seed": 31101,
    "enable_safety_checker": true,
    "image_urls": [
      "https://cdn.vidgo.ai/apis/models/alibaba/qwen-image-3.0/edit/v1/01/input-01.jpg"
    ]
  }
}
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	–	Must contain 1–5,000 characters after trimming.
input.image_urls	string[]	Yes	–	Provide 1–3 public HTTP(S) image URLs in order; each position maps to the image role named in the prompt.
input.size	string	No	1:1	One of 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16, 21:9.
input.resolution	string	No	1K	1K or 2K; Standard uses one base rate for either resolution.
input.output_format	string	No	png	png or jpeg.
input.prompt_extend	boolean	No	–	Controls automatic prompt expansion; the Playground explicitly sends true.
input.negative_prompt	string	No	–	Describes content to avoid, up to 5,000 characters.
input.seed	integer	No	–	Optional integer from 0 through 2,147,483,647, inclusive.
input.enable_safety_checker	boolean	No	–	Controls content safety checking. The Playground explicitly sends true by default.

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
Input mode	Prompt + 1–3 images	Images participate in edit order from image_urls.
Output	Image	Returns one or more image files asynchronously.
Resolution	1K · 2K	Defaults to 1K.
Aspect ratio	8 ratios	Supports 1:1, 3:2, 2:3, 4:3, 3:4, 16:9, 9:16, 21:9.
Output format	png · jpeg	Defaults to png.
Billing	4.8 credits at 1K or 2K, plus 0.5 credit per input image	1 credit = $0.005; the backend remains authoritative for final billing.

Qwen Image 3.0 Image Edit API documentation

Qwen Image 3.0 Standard Image Edit

Qwen Image 3.0 Standard Image Edit API requires a prompt and one to three ordered public HTTP(S) image URLs. Refer to each image by its array position in the prompt, describe the requested changes, and retrieve the edited image after the asynchronous task reaches finished.

Why Choose Qwen Image 3.0 Standard Image Edit API?

Direct the edit in plain language.State what should remain recognizable and what should change in the result.
Give each source a role.Combine a primary asset with distinct style, setting, or composition references.
Reframe for new placements.Adapt an existing creative to square, portrait, landscape, or ultrawide delivery.
Build practical variants.Create campaign, product, and localization versions from an established visual.

Parameters

Parameter	Requirement	Description
prompt	Required	Edit instruction containing 1–5,000 characters after trimming.
image_urls	Required	Ordered array of 1–3 public HTTP(S) image URLs; each position maps to the role named in the prompt.
size	Optional	Output aspect ratio. Default`1:13:22:34:33:416:99:1621:9`
resolution	Optional	Output resolution. Default`1K2K`
output_format	Optional	Output image encoding. Default`pngjpeg`
prompt_extend	Optional	Boolean that enables automatic prompt expansion.
negative_prompt	Optional	Content to avoid, up to 5,000 characters.
seed	Optional	Integer from 0 through 2,147,483,647, inclusive.
enable_safety_checker	Optional	Boolean that controls content safety checking.

How to Use

Order the source images.Place the main asset first, followed by images with distinct supporting roles.
Name what to preserve.Identify the product, person, text, geometry, or material that should remain recognizable.
Describe the change.Specify the new setting, composition, lighting, color, or copy after the preservation rules.
Review the edited asset.Check both the requested transformation and the details that were meant to stay consistent.

Pricing

Standard Image Edit costs 4.8 credits plus 0.5 credit for each input image at either resolution. Credits convert at $0.005 each.

Usage	Rate	Details
One-image edit	5.3 credits	4.8 base credits plus 0.5 credit for one source image.
Three-image edit	6.3 credits	4.8 base credits plus 1.5 credits for three source images.

Best Use Cases

Product setting changesKeep the product recognizable while rebuilding its background, lighting, and props.
Poster revisionsRetain a visual system while changing campaign color, setting, or subject treatment.
Multi-source compositesAssign separate images to the main object, destination environment, and visual direction.
Localized creative variantsAdapt visible copy and framing while carrying the core asset into a new market.

Pro Tips

Refer to image 1, image 2, and image 3 explicitly; array order is preserved.
Place preservation requirements before the requested changes.
Use one source for each distinct role instead of repeating near-identical images.
Name exact materials, colors, and lighting changes rather than asking for a generic upgrade.
Remove unused sources before submission so each image contributes a clear purpose.

Notes

Qwen Image 3.0 Standard Image Edit API preserves image_urls array order in the submitted request.
The Playground accepts JPEG, PNG, or WebP uploads up to 30 MB per file and submits their public URLs.
Prompt extension and safety checking are enabled in the Playground and sent explicitly.
A finished task should contain a valid image file; failed is also a terminal state.

Related Models

GPT Image 2Compare quality tiers and flexible image generation or editing up to 4K.

Seedream 5.0 LiteUse 2K or 3K presets, custom sizes, and a larger multi-reference workflow.

FLUX.2Choose Pro or Flex generation and editing with multi-reference controls.

Nano Banana 2Explore 1K, 2K, and 4K image creation with an expanded reference-image limit.

Frequently Asked Questions about Qwen Image 3.0 Image Edit

What is the Qwen Image 3.0 Image Edit API?

Qwen Image 3.0 Image Edit is Alibaba's Standard model for changing existing images with natural-language instructions. You provide one to three ordered source images and explain what to preserve or change; it returns a revised image for product, poster, scene, and localization updates.

How do I call Standard Image Edit?

Upload each source to a public HTTP(S) URL, submit the model and input object with a Bearer key, then track the returned task ID or use a callback.

How much does Standard Image Edit cost?

The total is 4.8 credits plus 0.5 credit per source image at either 1K or 2K. Representative totals appear above.

What inputs define an edit?

A prompt and one to three ordered image URLs are required. The parameter table lists the optional canvas, output, prompt, seed, and safety controls.

Where are edited images returned?

Read data.files[].file_url after finished. Stop on failed and surface the provided error_message.

Should I use Generate, Standard Edit, or Pro Edit?

Use Generate without source-image URLs and Edit with one to three ordered source-image URLs. Standard Edit has a 4.8-credit base rate at 1K or 2K; Pro Edit has a 6.4-credit base rate at 1K and 12-credit base rate at 2K. Both add 0.5 credit per source image.