Alibaba Qwen Image 3.0 Edit API Documentation

Alibaba Qwen Image 3.0 Edit API Documentation

Playground

Qwen Image 3.0 Edit is a high-quality image editing model that transforms existing images with natural-language instructions, delivering advanced instruction understanding, superior visual quality, and up to 2K output for creative and production workflows. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

Qwen Image 3.0 Edit transforms 1 to 3 reference images using natural-language instructions. Upload source images, describe the desired edit, and generate a refined output while preserving the requested visual context.

Why Choose This?

• Instruction-based image editing
  Edit images using clear natural-language instructions.

• Multi-image input
  Use 1 to 3 reference images to provide visual context for the edit.

• Reference-guided refinement
  Preserve important subject, style, composition, or identity details from the input images.

• Flexible output sizing
  Choose 1k or 2k resolution and optionally set the output aspect ratio.

• Prompt expansion support
  Enable intelligent prompt expansion for richer edit interpretation.

• Seed control
  Use a fixed seed for reproducible results, or -1 for random generation.

Parameters

How to Use

1. Upload input images — Provide 1 to 3 images for editing or reference guidance.
2. Write your edit prompt — Describe the change you want and what should remain unchanged.
3. Choose resolution optional — Use 1k for standard output or 2k when higher detail is needed.
4. Choose aspect ratio optional — Set a specific aspect ratio or leave it empty to follow the first input image ratio.
5. Set prompt expansion optional — Keep prompt expansion enabled for richer interpretation, or disable it for stricter prompt control.
6. Set seed optional — Use a fixed seed when you need reproducible results.
7. Submit — Generate the edited image and retrieve the output URL.

Pricing

Pricing includes input image cost and output image cost.

Example Costs

Best Use Cases

• Photo retouching — Adjust appearance, lighting, background, or composition.
• Creative image edits — Change style, mood, objects, clothing, or environment.
• Product image refinement — Improve product visuals for ecommerce, marketing, and campaigns.
• Character and portrait edits — Preserve identity while changing details or visual style.
• Reference-guided editing — Use multiple images to guide the final edited result.

Pro Tips

• Use clear edit prompts that describe both what should change and what should stay the same.
• Upload only the images needed for the edit.
• Use multiple input images when reference context matters.
• Leave aspect_ratio empty when you want the first input image ratio to guide the output.
• Keep enable_prompt_expansion enabled for richer interpretation.
• Disable prompt expansion when you need stricter control over the exact prompt.
• Use a fixed seed when comparing edit variations.

Related Models

• Qwen Image 3.0 Text-to-Image — Generate images from text prompts.
• Qwen Image 3.0 Edit — Edit images with natural-language instructions.

## Authentication

For authentication details, please refer to the [Authentication Guide](/api-authentication).

## API Endpoints

### Submit Task & Query Result

<ApiTabs submitUrl={model.submitUrl} resultUrl={model.resultUrl} payload={model.defaultValues} />

## Parameters

### Task Submission Parameters

#### Request Parameters

<RequestParams params={model.params} />

#### Response Parameters

<SubmitResponse />

#### Result Request Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| id | string | Yes | - | Task ID |

#### Result Response Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| code | integer | HTTP status code (e.g., 200 for success) |
| message | string | Status message (e.g., "success") |
| data | object | The prediction data object containing all details |
| data.id | string | Unique identifier for the prediction |
| data.model | string | Model ID used for the prediction |
| data.outputs | array&lt;string \| object&gt; | Array of generated outputs (empty when status is not completed). Items are usually URL strings, but may be text strings or structured result objects, depending on the model. |
| data.urls | object | Object containing related API endpoints |
| data.urls.get | string | URL to poll for the prediction result |
| data.status | string | Status: `created`, `processing`, `completed`, or `failed` |
| data.created_at | string | ISO timestamp of when the request was created |
| data.error | string | Error message (empty if no error occurred) |
| data.timings | object | Object containing timing details |
| data.timings.inference | integer | Inference time in milliseconds |