Wan 2.7 Image Edit API

alibaba/wan-2.7/image-edit

6 preset sizes / custom size · 1–4 images

Wan 2.7 Image Edit transforms and blends 1–4 reference images with natural language instructions, enabling mask-free localized repainting, identity preservation, and stylistic transfer. It seamlessly updates targeted components while retaining original facial features, primary composition, and ambient lighting textures.

Get API Key

Input

Prompt

880/5000

Image Urls

1/4

Add images

Size

Output count

Seed

OutputReady

Continue with

Wan 2.7 Image Text to Image Wan 2.7 Image Pro Edit Wan 2.7 Video Edit

Examples

Edit the supplied photo in place. Treat the woman and her umbrella as a locked foreground cutout. Keep her EXACT image-space size, position, pose, face, short curly hair, rust raincoat, dark trousers, both hands and folded blue umbrella. Match the original close three-quarter portrait crop: her head stays near the top of the frame, her body fills most of the image height, and her feet remain OUTSIDE the bottom edge. Do not zoom out, move the camera, extend her legs or reveal shoes. Change only pixels of the plain corridor behind her into a rain-soaked bus shelter: glass wall with droplets at the right, a blurred wet residential street and trees behind her, subtle amber reflections. Preserve her face and body proportions with the same framing. Apply only a subtle cooler ambient tone to harmonize the light. No text, other people, advertising, logos, watermark, or foxes.

Transform image 1 into an elegant hand-printed color woodcut. Preserve the single beetle silhouette, its six legs, two antennae, orientation, size and exact location on the diagonal tree trunk. Replace photographic shading with bold carved black contour lines, restrained emerald, warm ivory and burnt-orange ink areas, visible wood grain and subtle print registration texture. Keep the original composition and recognizable bark grooves. No extra insects, no text, no border. No advertising, brands, logos, watermark, or foxes.

Edit image 1 only on the face of the wooden ferry sign. Replace all existing lettering with exactly two large centered lines: "渡口 / FERRY" and "09:30". Keep the sign wood grain, weathering, posts, exact perspective, framing, harbor water, mooring rope and background buildings unchanged. New lettering is off-white hand-painted clean sans serif, easily readable, follows the physical sign perspective. No additional words or objects. No advertising, brands, logos, watermark, or foxes.

REST API

Quick Start

This flow submits one valid Wan 2.7 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": "alibaba/wan-2.7/image-edit",
  "input": {
    "prompt": "Edit the supplied photo in place. Treat the woman and her umbrella as a locked foreground cutout. Keep her EXACT image-space size, position, pose, face, short curly hair, rust raincoat, dark trousers, both hands and folded blue umbrella. Match the original close three-quarter portrait crop: her head stays near the top of the frame, her body fills most of the image height, and her feet remain OUTSIDE the bottom edge. Do not zoom out, move the camera, extend her legs or reveal shoes. Change only pixels of the plain corridor behind her into a rain-soaked bus shelter: glass wall with droplets at the right, a blurred wet residential street and trees behind her, subtle amber reflections. Preserve her face and body proportions with the same framing. Apply only a subtle cooler ambient tone to harmonize the light. No text, other people, advertising, logos, watermark, or foxes.",
    "size": "768x1024",
    "n": 1,
    "seed": 270911,
    "image_urls": [
      "https://cdn.vidgo.ai/apis/models/alibaba/wan-2.7/image-edit/v1/01/input-01.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": "OISWB6GIYIVLWIFE",
    "status": "running",
    "created_time": "2026-09-24T15:56:55"
  }
}

Finished response

{
  "code": 200,
  "data": {
    "task_id": "OISWB6GIYIVLWIFE",
    "status": "finished",
    "files": [
      {
        "file_type": "image",
        "file_url": "https://cdn.vidgo.ai/apis/models/alibaba/wan-2.7/image-edit/v1/01/output-attempt-02.jpg"
      }
    ],
    "created_time": "2026-09-24T15:56:55",
    "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": "alibaba/wan-2.7/image-edit",
  "input": {
    "prompt": "Edit the supplied photo in place. Treat the woman and her umbrella as a locked foreground cutout. Keep her EXACT image-space size, position, pose, face, short curly hair, rust raincoat, dark trousers, both hands and folded blue umbrella. Match the original close three-quarter portrait crop: her head stays near the top of the frame, her body fills most of the image height, and her feet remain OUTSIDE the bottom edge. Do not zoom out, move the camera, extend her legs or reveal shoes. Change only pixels of the plain corridor behind her into a rain-soaked bus shelter: glass wall with droplets at the right, a blurred wet residential street and trees behind her, subtle amber reflections. Preserve her face and body proportions with the same framing. Apply only a subtle cooler ambient tone to harmonize the light. No text, other people, advertising, logos, watermark, or foxes.",
    "size": "768x1024",
    "n": 1,
    "seed": 270911,
    "image_urls": [
      "https://cdn.vidgo.ai/apis/models/alibaba/wan-2.7/image-edit/v1/01/input-01.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	–	String, 1–5,000 characters after trimming.
input.image_urls	string[]	Yes	–	1–4 public HTTP(S) image URLs, in order. Refer to image 1, image 2, etc. in the prompt. A single string or Base64 is not accepted.
input.size	string \| object	No	1024x1024	Six preset sizes, or an object such as {"width":1280,"height":720}. Width and height must be positive integers.
input.n	integer	No	1	Output image count, integer 1–4. Credits = per-image rate × n.
input.seed	integer	No	–	Optional integer, omitted when unset. The upstream documentation specifies no numeric range.

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–4 images	Edit preserves the reference-image order.
Size	512x512, 1024x1024, 768x1024, 1024x768, 576x1024, 1024x576	Default: 1024x1024; custom positive integer width and height are supported.
Output count	1–4	Integer; default: 1.
Seed	integer	Optional; the upstream specifies no numeric range.
Billing	4.2 credits per output image ($0.021). Total credits = 4.2 × n. Size and reference images add no charges. 1 credit = $0.005.	1 credit = $0.005.

Wan 2.7 Image Edit API documentation

Wan 2.7 Image Edit Overview

Wan 2.7 Image Edit is a unified multimodal image editing and reference-blending model developed by Alibaba Tongyi Lab. Creators can execute complex multi-image synthesis, localized inpainting, and stylistic transformations without manual masking by issuing intuitive natural language instructions (e.g., "place the person from image 1 into the scenic backdrop of image 2"). The model excels in facial identity retention across scenes and supports 6 preset aspect ratios as well as custom pixel dimensions, serving as an efficient engine for e-commerce scene staging, portrait retouching, and asset compositing.

Why Choose

Mask-Free Natural Language EditingEliminates tedious manual lassoing and brush selections; describe modifications and replacements in conversational text, and the model handles segmentation and edge transitions automatically.
1–4 Multi-Reference SynthesisUpload up to 4 reference pictures and cross-reference them as "image 1", "image 2", etc. in your prompt to synthesize characters, merchandise, and backgrounds into a harmonious composition.
High-Fidelity Subject & Lighting RetentionModifies requested garments, objects, or scenery while preserving primary facial contours, character expressions, and authentic ambient reflections.

Parameters

Parameter	Requirement	Description
prompt	Required	String, 1–5,000 characters after trimming.
image_urls	Required	1–4 public HTTP(S) image URLs, in order. Refer to image 1, image 2, etc. in the prompt. A single string or Base64 is not accepted.
size	Optional	Six preset sizes, or an object such as {"width":1280,"height":720}. Width and height must be positive integers. Default`1024x1024512x512768x10241024x768576x10241024x576`
n	Optional	Output image count, integer 1–4. Credits = per-image rate × n. Default`1`
seed	Optional	Optional integer, omitted when unset. The upstream documentation specifies no numeric range.

How to Use

Provide Reference ImagesPrepare 1 to 4 clean reference images via public HTTP(S) URLs (or upload directly in the playground).
Write Edit InstructionsSpecify the exact transformation, such as "preserve the subject identity from image 1 and place them onto the beach setting of image 2".
Submit Task and DownloadSubmit via the API or console, track the task asynchronously, and download the finished composite output.

Pricing

4.2 credits per output image ($0.021). Total credits = 4.2 × n. Size and reference images add no charges. 1 credit = $0.005.

Usage	Rate	Details
Standard	4.2 credits/image · $0.021	Multiply by output count n; credits are refunded for failed tasks.

Use Cases

E-Commerce Staging & Scene ReplacementRelocate studio-shot merchandise or models into authentic outdoor or lifestyle locations with photorealistic shadows.
Multi-Image Asset FusionExtract character faces from image 1, apparel from image 2, and aesthetics from image 3 into a cohesive hero asset.
Mask-Free Retouching & Wardrobe SwapsRapidly alter hairstyles, clothing colors, or handheld accessories while keeping facial structures strictly intact.

Tips

Reference Images by Index: Use explicit labels like "image 1" and "image 2" in your prompt to guide the multimodal planner in extracting targeted features accurately.
Use "Preserve... While Changing..." Structures: Clearly delineate preserved anchors (e.g., "preserve the facial structure of image 1") from modified areas to balance attention weights.
Match Image Quality and Lighting: Using reference photos with comparable resolutions and illumination angles delivers the most seamless color blending.

Notes

Reference Images Required: This endpoint mandates 1 to 4 reference image URLs; use Wan 2.7 Image Text to Image for prompt-only generation.
Public Accessibility: URLs passed via API must be directly reachable HTTP(S) links without authentication barriers.
Web Upload Limits: The web console accepts JPEG, PNG, and WebP formats up to 30 MB per file.

Related Models

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.

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.

Nano Banana 2 Text-to-ImageGoogle's next-gen image model powered by Gemini 3.1 Flash with native 2K/4K resolution, chain-of-thought reasoning, precise multi-language text rendering, and up to 14 reference images.

Nano Banana 2 Image EditGoogle's next-gen image model powered by Gemini 3.1 Flash with native 2K/4K resolution, chain-of-thought reasoning, precise multi-language text rendering, and up to 14 reference images.

Nano Banana Pro Text-to-ImageGoogle's Nano Banana Pro image model powered by Gemini 3 Pro for 4K generation, strong text rendering, multi-image blending, and production-ready image editing.

Nano Banana Pro Image EditGoogle's Nano Banana Pro image model powered by Gemini 3 Pro for 4K generation, strong text rendering, multi-image blending, and production-ready image editing.

GPT Image 1.5OpenAI's latest image model with 4x speed, precision editing, and superior text rendering.

Z-ImageAlibaba's efficient 6B-parameter image model with sub-second generation and exceptional Chinese-English bilingual text rendering capabilities.

Seedream 4.5ByteDance's unified 4K image generation and editing model with professional-grade text rendering and commercial photography quality.

Seedream 5.0 LiteByteDance Seedream 5.0 Lite family on Vidgo API: seedream-5.0-lite for text-to-image and seedream-5.0-lite-edit for image-to-image editing, with 2K/3K presets, custom sizes, and up to 10 reference images.

Wan 2.7 Image Edit API FAQ

What is the Wan 2.7 Image Edit API?

Wan 2.7 Image Edit is an Alibaba Tongyi Lab model designed for high-fidelity image editing and multi-reference fusion. It combines 1–4 reference pictures with text prompts to perform mask-free inpainting, cross-scene subject transfers, and style migration. Built on a unified multimodal planner and DiT backbone, it executes desired modifications while preserving source identity and ambient lighting. You can call it programmatically or try it from the playground above.

How many reference images can I upload to Wan 2.7 Image Edit?

You can provide between 1 and 4 public image URLs. The images are ordered sequentially in an array and referenced as "image 1" through "image 4" in your prompt, with zero surcharge for multiple references.

Do I need to supply a mask when using Wan 2.7 Image Edit?

No. The model provides native mask-free editing. Simply describe the modifications in plain text, and the multimodal engine identifies the target boundaries automatically.

How does Wan 2.7 Image Edit preserve facial identity across edits?

The architecture decouples facial identity latents from background and apparel variables. Reinforcing instructions such as "keep the facial appearance of image 1 unchanged" ensures strict identity retention.

Can Wan 2.7 Image Edit output a different aspect ratio than the input?

Yes. You can specify any of the 6 preset dimensions or pass custom pixel measurements in the size parameter. The model intelligently extends the visual narrative to fill the target canvas.

Does using 4 reference images cost more than 1 in Wan 2.7 Image Edit?

No. Billing is determined solely by the number of output images generated (4.2 credits / $0.021 per image), with no additional fees for input images.

What happens to credits if an edit task fails?

Vidgo implements an automated refund guarantee. If a task fails due to unreachable image URLs, validation errors, or timeouts, all deducted credits are returned immediately.