Qwen Image 3.0 Pro Image Edit API

alibaba/qwen-image-3.0-pro/edit

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

Qwen Image 3.0 Pro Image Edit API accepts a 1–5,000-character edit 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

557/5000

Reference images

1/3

Add images

Size

Resolution

Output format

Output

Ready

Continue with

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

Examples

Use image 1 as the sole source. Preserve the exact glacier silhouette, accumulation basin, compressed blue-ice layers, flow direction, calving face, crystal inset, arrows, framing, and geological relationships. Refine only the scientific visual clarity: increase the distinction between snow, firn, and blue ice; reveal finer crystal layers and moraine textures; make arrow weights more consistent; and add subtle depth lighting inside the cutaway without moving any element. Do not add writing, labels, logos, products, promotional elements, or watermarks.

Image 1 is authoritative for the complete observatory architecture, cutaway geometry, five numbered bilingual zone labels, circulation, cables, north arrow, scale, and camera view. Image 2 contributes only its quiet archival paper, charcoal annotation, and oxidized-green accent language. Re-render image 1 as a refined architectural archive plate using those surface qualities while preserving every structural relationship and every word from image 1. Do not import the bronze vessel or any label from image 2. Keep concrete, timber, metal, and rock materially distinct. No firm branding, property promotion, products, extra text, or watermark.

Edit image 1 while locking image 1 as the sole composition and scene. The final result must remain one continuous full-frame vertical underwater view with the same surface buoy, single descending fiber cable, seafloor observatory station, equipment positions, organisms, seabed, and cyan-to-navy depth lighting from image 1. Use image 2 only as a microscopic reference for clearer translucent material layering inside small pressure-resistant components; do not copy its glacier, arrows, inset, mountains, white background, or composition. Use image 3 only as a microscopic reference for realistic metal, concrete-like pressure housings, and precise color-coded cable routing; do not copy its building, dome, rooms, stairs, rock mountain, labels, or composition. Improve fine structure and cable legibility without creating comparisons or separate regions. No split screen, panels, columns, borders, arrows, numbers, writing, labels, logos, brands, promotion, or watermark.

REST API

Quick Start

This flow submits one valid Qwen Image 3.0 Pro 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-pro/edit",
  "input": {
    "prompt": "Use image 1 as the sole source. Preserve the exact glacier silhouette, accumulation basin, compressed blue-ice layers, flow direction, calving face, crystal inset, arrows, framing, and geological relationships. Refine only the scientific visual clarity: increase the distinction between snow, firn, and blue ice; reveal finer crystal layers and moraine textures; make arrow weights more consistent; and add subtle depth lighting inside the cutaway without moving any element. Do not add writing, labels, logos, products, promotional elements, or watermarks.",
    "size": "16:9",
    "resolution": "1K",
    "output_format": "jpeg",
    "prompt_extend": false,
    "negative_prompt": "typography, text, labels, moved composition, extra stages, logos, promotional marks, watermark",
    "seed": 32101,
    "enable_safety_checker": true,
    "image_urls": [
      "https://cdn.vidgo.ai/apis/models/alibaba/qwen-image-3.0-pro/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-pro/edit",
  "input": {
    "prompt": "Use image 1 as the sole source. Preserve the exact glacier silhouette, accumulation basin, compressed blue-ice layers, flow direction, calving face, crystal inset, arrows, framing, and geological relationships. Refine only the scientific visual clarity: increase the distinction between snow, firn, and blue ice; reveal finer crystal layers and moraine textures; make arrow weights more consistent; and add subtle depth lighting inside the cutaway without moving any element. Do not add writing, labels, logos, products, promotional elements, or watermarks.",
    "size": "16:9",
    "resolution": "1K",
    "output_format": "jpeg",
    "prompt_extend": false,
    "negative_prompt": "typography, text, labels, moved composition, extra stages, logos, promotional marks, watermark",
    "seed": 32101,
    "enable_safety_checker": true,
    "image_urls": [
      "https://cdn.vidgo.ai/apis/models/alibaba/qwen-image-3.0-pro/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; the Pro base rate changes with 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	6.4 credits (1K) or 12 credits (2K), plus 0.5 credit per input image	1 credit = $0.005; the backend remains authoritative for final billing.

Qwen Image 3.0 Pro Image Edit API documentation

Qwen Image 3.0 Pro Image Edit

Qwen Image 3.0 Pro Image Edit API uses a resolution-based rate plus 0.5 credit per source image. The base rate is 6.4 credits at 1K and 12 credits at 2K; image_urls accepts one to three ordered public HTTP(S) URLs.

Why Choose Qwen Image 3.0 Pro Image Edit API?

Name details that should remain recognizable.List the product, identity, typography, geometry, or material that the edit prompt should retain.
Direct several source roles.Use separate images to establish the main asset, visual language, and target environment.
Handle substantial revisions.Change composition, setting, lighting, or style while maintaining source continuity.
Choose between two resolution rates.Use the 6.4-credit base rate at 1K or the 12-credit base rate at 2K, plus 0.5 credit per source image.

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

Assign every source.Place the primary asset first and give each following image one distinct purpose.
Write preservation rules.List the identity, shape, text, color, material, or layout relationships that should remain.
Direct the transformation.Describe the new composition, environment, lighting, and style after the fixed requirements.
Inspect the returned image.Review the requested change and compare named product, identity, text, and material details with the source images.

Pricing

Pro Image Edit uses a resolution-based rate plus 0.5 credit for each input image. Credits convert at $0.005 each.

Usage	Rate	Details
1K edit with 1–3 images	6.9–7.9 credits	6.4 base credits plus 0.5 credit for each source image.
2K edit with 1–3 images	12.5–13.5 credits	12 base credits plus 0.5 credit for each source image.

Best Use Cases

Product-setting editsUse a product source image and request a new campaign setting while naming packaging geometry, labels, and materials to retain.
Portrait revisionsUse a portrait source image and request wardrobe, lighting, or environment changes while naming facial details to retain.
Multi-source art directionAssign separate images to the subject, visual system, and destination environment.
Detailed layout revisionsRefine a composition for commercial crops, typography, and downstream production.

Pro Tips

Refer to image 1, image 2, and image 3 explicitly so each source role is unambiguous.
Put non-negotiable preservation rules before visual changes.
Use only sources with distinct jobs in the final direction.
For 2K delivery, specify the materials, edge detail, and text that need close inspection.
Wait until every upload has a public HTTP(S) URL before submitting the task.

Notes

Source order stays intact and should match the roles described in the prompt.
The Playground accepts JPEG, PNG, or WebP uploads up to 30 MB per file.
Prompt extension and safety checking are enabled in the Playground and sent explicitly.
A finished response should contain valid image files; failed also ends the task.

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 Pro Image Edit

What is the Qwen Image 3.0 Pro Image Edit API?

Qwen Image 3.0 Pro Image Edit API accepts a prompt and one to three ordered public HTTP(S) image URLs under the qwen-image-3.0-pro/edit model ID. It returns an asynchronous PNG or JPEG image task at 1K or 2K.

How do I call Pro Image Edit?

Upload the sources to public HTTP(S) URLs, submit the Pro model and input object with a Bearer key, then track the task ID or use a callback.

How much does Pro Image Edit cost?

Start with 6.4 credits at 1K or 12 credits at 2K, then add 0.5 credit per source image. The pricing table shows each range.

What inputs define a Pro edit?

A prompt and one to three ordered image URLs are required. The optional output, prompt, seed, and safety controls are listed above.

How are edited images returned?

Read every valid data.files[].file_url after finished. On failed, stop polling and surface error_message.

Should I use Standard Edit or Pro Edit?

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 and accept one to three ordered image URLs.