General image editing - Wan2.1

​

Visão geral do modelo

Imagem original	Mude o cabelo dela para vermelho	Adicione óculos escuros à garota	Converta para o estilo de livro ilustrado francês

Consulte Recursos principais .

​

Região de Beijing

​

Primeiros passos

​

Pré-requisitos

​

Código de exemplo

O SDK encapsula o processamento assíncrono, fazendo com que a interface se comporte de forma síncrona — uma única requisição aguarda o resultado. O exemplo com curl mostra duas operações assíncronas separadas: envio da tarefa e consulta do resultado.

import base64
import os
from http import HTTPStatus
from dashscope import ImageSynthesis
import mimetypes

"""
Environment requirements:
    dashscope Python SDK >= 1.23.8
Install/Upgrade SDK:
    pip install -U dashscope
"""

# If the environment variable is not configured, replace the following line with your Model Studio API key: api_key="sk-xxx"
api_key = os.getenv("DASHSCOPE_API_KEY")

# --- Helper function for Base64 encoding ---
# The format is data:{MIME_type};base64,{base64_data}
def encode_file(file_path):
    mime_type, _ = mimetypes.guess_type(file_path)
    if not mime_type or not mime_type.startswith("image/"):
        raise ValueError("Unsupported or unrecognized image format")
    with open(file_path, "rb") as image_file:
        encoded_string = base64.b64encode(image_file.read()).decode('utf-8')
    return f"data:{mime_type};base64,{encoded_string}"

"""
Image input methods:
Choose one of the following three methods.

1. Use a public URL - suitable for publicly accessible images.
2. Use a local file - suitable for local development and testing.
3. Use Base64 encoding - suitable for private images or scenarios that require encrypted transmission.
"""

# [Method 1] Use a public image URL
mask_image_url = "http://wanx.alicdn.com/material/20250318/description_edit_with_mask_3_mask.png"
base_image_url = "http://wanx.alicdn.com/material/20250318/description_edit_with_mask_3.jpeg"

# [Method 2] Use a local file (supports absolute and relative paths)
# Format requirement: file:// + file path
# Example (absolute path):
# mask_image_url = "file://" + "/path/to/your/mask_image.png"     # Linux/macOS
# base_image_url = "file://" + "C:/path/to/your/base_image.jpeg"  # Windows
# Example (relative path):
# mask_image_url = "file://" + "./mask_image.png"                 # Path is relative to the current working directory.
# base_image_url = "file://" + "./base_image.jpeg"                # Path is relative to the current working directory.

# [Method 3] Use a Base64-encoded image
# mask_image_url = encode_file("./mask_image.png")               # Path is relative to the current working directory.
# base_image_url = encode_file("./base_image.jpeg")              # Path is relative to the current working directory.

def sample_sync_call_imageedit():
    print('Processing... please wait.')
    rsp = ImageSynthesis.call(api_key=api_key,
                              model="wanx2.1-imageedit",
                              function="description_edit_with_mask",
                              prompt="A ceramic rabbit holding a ceramic flower",
                              mask_image_url=mask_image_url,
                              base_image_url=base_image_url,
                              n=1)
    assert rsp.status_code == HTTPStatus.OK

    print('response: %s' % rsp)
    if rsp.status_code == HTTPStatus.OK:
        for result in rsp.output.results:
            print("---------------------------")
            print(result.url)
    else:
        print('sync_call Failed, status_code: %s, code: %s, message: %s' %
              (rsp.status_code, rsp.code, rsp.message))

if __name__ == '__main__':
    sample_sync_call_imageedit()

{
    "status_code": 200,
    "request_id": "dc41682c-4e4a-9010-bc6f-xxxxxx",
    "code": null,
    "message": "",
    "output": {
        "task_id": "6e319d88-a07a-420c-9493-xxxxxx",
        "task_status": "SUCCEEDED",
        "results": [
            {
                "url": "https://dashscope-result-wlcb-acdr-1.oss-cn-wulanchabu-acdr-1.aliyuncs.com/xxx.png?xxxxxx"
            }
        ],
        "submit_time": "2025-05-26 14:58:27.320",
        "scheduled_time": "2025-05-26 14:58:27.339",
        "end_time": "2025-05-26 14:58:39.170",
        "task_metrics": {
            "TOTAL": 1,
            "SUCCEEDED": 1,
            "FAILED": 0
        }
    },
    "usage": {
        "image_count": 1
    }
}

// Copyright (c) Alibaba, Inc. and its affiliates.

import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesis;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisParam;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.Base64;
import java.util.HashMap;
import java.util.Map;

/**
 * Environment requirements:
 *      dashscope java SDK >=2.20.9
 * Update Maven dependency:
 *      https://mvnrepository.com/artifact/com.alibaba/dashscope-sdk-java
 */

public class ImageEditSync {

    // If the environment variable is not configured, replace the following line with your Model Studio API key: String apiKey = "sk-xxx";
    static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    /**
     * Image input methods: Choose one of the following three methods.
     *
     * 1. Use a public URL - suitable for publicly accessible images.
     * 2. Use a local file - suitable for local development and testing.
     * 3. Use Base64 encoding - suitable for private images or scenarios that require encrypted transmission.
     */

    //[Method 1] Public URL
    static String maskImageUrl = "http://wanx.alicdn.com/material/20250318/description_edit_with_mask_3_mask.png";
    static String baseImageUrl = "http://wanx.alicdn.com/material/20250318/description_edit_with_mask_3.jpeg";

    //[Method 2] Local file path (file://+absolute path or file:///+absolute path)
    // static String maskImageUrl = "file://" + "/your/path/to/mask_image.png";    // Linux/macOS
    // static String baseImageUrl = "file:///" + "C:/your/path/to/base_image.png";  // Windows

    //[Method 3] Base64 encoding
    // static String maskImageUrl = encodeFile("/your/path/to/mask_image.png");
    // static String baseImageUrl = encodeFile("/your/path/to/base_image.png");

    public static void syncCall() {
        // Set the parameters.
        Map<String, Object> parameters = new HashMap<>();
        parameters.put("prompt_extend", true);

        ImageSynthesisParam param =
                ImageSynthesisParam.builder()
                        .apiKey(apiKey)
                        .model("wanx2.1-imageedit")
                        .function(ImageSynthesis.ImageEditFunction.DESCRIPTION_EDIT_WITH_MASK)
                        .prompt("A ceramic rabbit holding a ceramic flower")
                        .maskImageUrl(maskImageUrl)
                        .baseImageUrl(baseImageUrl)
                        .n(1)
                        .size("1024*1024")
                        .parameters(parameters)
                        .build();

        ImageSynthesis imageSynthesis = new ImageSynthesis();
        ImageSynthesisResult result = null;
        try {
            System.out.println("---Synchronous call, please wait...----");
            result = imageSynthesis.call(param);
        } catch (ApiException | NoApiKeyException e){
            throw new RuntimeException(e.getMessage());
        }
        System.out.println(JsonUtils.toJson(result));
    }

    /**
     * Encodes a file into a Base64 string.
     * @param filePath The path to the file.
     * @return A Base64 string in the format data:{MIME_type};base64,{base64_data}.
     */
    public static String encodeFile(String filePath) {
        Path path = Paths.get(filePath);
        if (!Files.exists(path)) {
            throw new IllegalArgumentException("File does not exist: " + filePath);
        }
        // Detect the MIME type.
        String mimeType = null;
        try {
            mimeType = Files.probeContentType(path);
        } catch (IOException e) {
            throw new IllegalArgumentException("Cannot detect file type: " + filePath);
        }
        if (mimeType == null || !mimeType.startsWith("image/")) {
            throw new IllegalArgumentException("Unsupported or unrecognized image format");
        }
        // Read the file content and encode it.
        byte[] fileBytes = null;
        try{
            fileBytes = Files.readAllBytes(path);
        } catch (IOException e) {
            throw new IllegalArgumentException("Cannot read file content: " + filePath);
        }

        String encodedString = Base64.getEncoder().encodeToString(fileBytes);
        return "data:" + mimeType + ";base64," + encodedString;
    }

    public static void main(String[] args) {
        syncCall();
    }
}

{
    "request_id": "bf6c6361-f0fc-949c-9d60-xxxxxx",
    "output": {
        "task_id": "958db858-153b-4c81-b243-xxxxxx",
        "task_status": "SUCCEEDED",
        "results": [
            {
                "url": "https://dashscope-result-wlcb-acdr-1.oss-cn-wulanchabu-acdr-1.aliyuncs.com/xxx.png?xxxxxx"
            }
        ],
        "task_metrics": {
            "TOTAL": 1,
            "SUCCEEDED": 1,
            "FAILED": 0
        }
    },
    "usage": {
        "image_count": 1
    }
}

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
  "model": "wanx2.1-imageedit",
  "input": {
    "function": "description_edit_with_mask",
    "prompt": "A ceramic rabbit holding a ceramic flower.",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/description_edit_with_mask_3.jpeg",
    "mask_image_url": "http://wanx.alicdn.com/material/20250318/description_edit_with_mask_3_mask.png"
  },
  "parameters": {
    "n": 1
  }
}'

{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

curl -X GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

{
    "request_id": "eeef0935-02e9-9742-bb55-xxxxxx",
    "output": {
        "task_id": "a425c46f-dc0a-400f-879e-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-02-21 17:56:31.786",
        "scheduled_time": "2025-02-21 17:56:31.821",
        "end_time": "2025-02-21 17:56:42.530",
        "results": [
            {
                "url": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/aaa.png"
            }
        ],
        "task_metrics": {
            "TOTAL": 1,
            "SUCCEEDED": 1,
            "FAILED": 0
        }
    },
    "usage": {
        "image_count": 1
    }
}

​

Recursos principais

Observação: Uma requisição curl completa deve incluir campos de nível superior como model, input e parameters. Para detalhes sobre a estrutura, consulte Referência da API de edição geral de imagens .

​

Estilização global

• Defina function como stylization_all.
• Estilos suportados:
  • Estilo de livro ilustrado francês
  • Estilo de arte com folha de ouro
• parameters.strength (0,0–1,0, padrão: 0,5) controla a intensidade da modificação. Valores mais baixos preservam mais a imagem original.
• Formato do prompt: "Convert to [style]" (ex.: "Convert to French picture book style").

{
  "input": {
    "function": "stylization_all",
    "prompt": "Convert to French picture book style",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/stylization_all_3.png"
  },
  "parameters": {
    "strength": 0.5
  }
}

Imagem de entrada	Imagem de saída
	Prompt: Convert to French picture book style	Prompt: Convert to gold foil art style

Controle o grau de modificação da imagem com strength

Prompt de entrada: Convert to French picture book style.

Imagem de entrada	Imagem de saída
	strength=0.0 (valor mínimo)	strength=0.5 (valor padrão)	strength=1.0 (valor máximo)

​

Estilização local

• Defina function como stylization_local.
• Estilos suportados: Os estilos disponíveis e seus valores correspondentes são:
  • Escultura de gelo: ice
  • Nuvem: cloud
  • Lanterna festiva chinesa: chinese festive lantern
  • Tábua de madeira: wooden
  • Porcelana azul e branca: blue and white porcelain
  • Felpudo: fluffy
  • Fio/Lã: weaving
  • Balão: balloon
• Formato do prompt: "Change [object] to [style]" (ex.: "Change the house to wooden style").

{
  "input": {
    "function": "stylization_local",
    "prompt": "Change the house to wooden style",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/stylization_local_1.png"
  }
}

Imagem de entrada	Imagem de saída
	Ice Sculpture	Cloud	Chinese festive lantern	Wooden
	Blue and white porcelain	Fluffy	Weaving	Balloon

​

Edição baseada em instruções

• Defina function como description_edit.
• parameters.strength (0,0–1,0, padrão: 0,5) controla a intensidade da modificação. Valores mais baixos preservam mais a imagem original.
• Prompt: Inclua verbos de ação como "add" ou "modify". Para exclusões, use Inpainting local.

{
  "input": {
    "function": "description_edit",
    "prompt": "Add a pair of sunglasses to the kitten",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/description_edit_1.jpeg"
  },
  "parameters": {
    "strength": 0.5
  }
}

Capacidades	Imagem de entrada	Imagem de saída
Adicionar um elemento		Add a pair of sunglasses to the kitten.
Modificar um elemento		Change her hair to red.

Controle o grau de modificação da imagem com strength

Prompt de entrada: Change her clothes to a colorful printed beach shirt.

Imagem de entrada	Imagem de saída
	strength=0.0 (valor mínimo)	strength=0.5 (valor padrão)	strength=1.0 (valor máximo)

​

Inpainting local

• Defina function como description_edit_with_mask.
• Requisitos da máscara: Forneça mask_image_url onde branco = área de edição, preto = área mantida.
• Prompt: Inclua ações ("add", "modify") e descreva o conteúdo pós-exclusão para remoções.
  • Adicionar/Modificar: Descreva a ação ou o resultado final.
  • Excluir: Deixe o prompt vazio para objetos pequenos. Para objetos grandes, descreva o fundo desejado após a exclusão — não a ação de excluir em si.

{
  "input": {
    "function": "description_edit_with_mask",
    "prompt": "A ceramic rabbit holding a ceramic flower",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/description_edit_with_mask_1.jpeg",
    "mask_image_url": "http://wanx.alicdn.com/material/20250318/description_edit_with_mask_1_mask.png"
  }
}

Capacidades	Imagem de entrada	Imagem de máscara de entrada(Branco é a área a ser editada)	Imagem de saída
Adicionar um elemento			Add a hat to the puppy. Você também pode escrever o prompt como "A puppy wearing a hat" para descrever o conteúdo esperado da imagem.
Modificar um elemento			A ceramic rabbit holding a ceramic flower. Você também pode escrever o prompt como "Replace the carrot held by the ceramic rabbit with a ceramic flower" para descrever a ação.
Excluir um elemento			A transparent glass vase on the table. O prompt precisa descrever o conteúdo após a exclusão. Não escreva como "Delete the brown bear".

​

Remoção de texto e marca d'água

• Defina function como remove_watermark.
• Prompt: Use instruções gerais ("Remove the text") ou especifique o tipo ("Remove English text").

{
  "input": {
    "function": "remove_watermark",
    "prompt": "Remove the text in the image",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/remove_watermark_1.png"
  }
}

Imagem de entrada	Imagem de saída (Remove the text in the image)

​

Outpainting

• Defina function como expand.
• Parâmetros relacionados: top_scale, bottom_scale, left_scale e right_scale controlam as proporções de expansão por direção (ex.: 1,5 = 1,5× o tamanho).
• Dica de prompt: Descreva a cena completa que você espera ver após a expansão.

{
  "input": {
    "function": "expand",
    "prompt": "A family on the lawn in a park",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/expand_1.jpeg"
  },
  "parameters": {
    "top_scale": 1.5,
    "bottom_scale": 1.5,
    "left_scale": 1.5,
    "right_scale": 1.5
  }
}

Imagem de entrada	Imagem de saída

​

Super-resolução de imagem

• Defina function como super_resolution.
• parameters.upscale_factor (1–4, padrão: 1) controla o upscaling. O valor 1 melhora apenas a nitidez, sem ampliar a imagem.
• Dica de prompt: Use "Image super resolution" ou descreva o conteúdo da imagem.

{
  "input": {
    "function": "super_resolution",
    "prompt": "Image super resolution",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/super_resolution_1.jpeg"
  },
  "parameters": {
    "upscale_factor": 2
  }
}

Imagem de entrada (imagem desfocada)	Imagem de saída (imagem nítida)

​

Colorização de imagem

• Defina function como colorization.
• Prompt: Deixe vazio para colorização automática ou especifique cores de elementos-chave (ex.: "blue background, yellow leaves").

{
  "input": {
    "function": "colorization",
    "prompt": "blue background, yellow leaves",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/colorization_1.jpeg"
  }
}

Imagem de entrada	Imagem de saída

​

Desenho linear para imagem (suporta desenho baseado em rabiscos)

• Defina function como doodle.
• Parâmetro relacionado: parameters.is_sketch, que controla o resultado da geração da imagem.
  • false (padrão): O modelo extrai o desenho linear da entrada RGB e então gera a imagem (RGB → desenho linear → imagem).
  • true: O modelo gera diretamente da entrada RGB, semelhante a rabiscos (RGB → imagem).
• Prompt: Descreva o conteúdo esperado — mais detalhes resultam em melhores resultados.

{
  "input": {
    "function": "doodle",
    "prompt": "A living room in a minimalist Nordic style.",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/doodle_1.png"
  },
  "parameters": {
    "is_sketch": false
  }
}

{
  "input": {
    "function": "doodle",
    "prompt": "A tree, in a two-dimensional anime style",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/doodle_2.png"
  },
  "parameters": {
    "is_sketch": true
  }
}

Capacidades	Imagem de entrada	Imagem de saída
Desenho linear para imagem (is_sketch=false)		A living room in a minimalist Nordic style.
Desenho baseado em rabiscos (is_sketch=true)		A tree, in a two-dimensional anime style.

​

Gerar imagem baseada em personagem de desenho animado de referência

• Defina function como control_cartoon_feature.
• Formato do prompt: "The cartoon character [action/environment details]..."

{
  "input": {
    "function": "control_cartoon_feature",
    "prompt": "The cartoon character cautiously peeks out, peering at a brilliant blue gem in the room",
    "base_image_url": "http://wanx.alicdn.com/material/20250318/control_cartoon_feature_1.png"
  }
}

Imagem de entrada	Imagem de saída

​

Entrando em produção

​

Melhores práticas

• Polling assíncrono: Use intervalos de polling graduais (ex.: a cada 3s por 30s, depois aumente) para evitar limites de taxa.
• Ajuste de parâmetros: Teste parâmetros-chave como strength em testes de pequena escala antes da produção para encontrar os valores ideais.
• Armazenamento de imagens: As URLs retornadas pela API expiram após 24 horas. Baixe as imagens e transfira-as para armazenamento persistente (ex.: OSS) prontamente.

​

Prevenção de riscos

• Tratamento de erros: Verifique o task_status nos resultados da consulta. Se for FAILED, registre o code e a message para solução de problemas. Erros transitórios (ex.: timeouts) podem ser resolvidos em nova tentativa.
• Moderação de conteúdo: A API revisa todas as entradas e saídas quanto à conformidade. Conteúdo não conforme retorna DataInspectionFailed.

​

Referência da API

​

Faturamento e limitação de taxa

• Para cotas gratuitas e preços do modelo, consulte Wan image editing 2.1.
• Para limitação de taxa do modelo, consulte Wanxiang.
• Detalhes do faturamento:
  • O faturamento é feito pelo número de imagens geradas com sucesso. As cobranças ocorrem apenas quando o task_status é SUCCEEDED.
  • Chamadas falhas não incorrem em cobranças nem consomem a Cota gratuita para novos usuários.

​

Códigos de erro

​

FAQ

1. Falha na moderação de conteúdo: A entrada ou saída acionou a política de segurança.
2. Erro de parâmetro: Parâmetros de requisição inválidos (ex.: nome de function incorreto ou URL inacessível).
3. Erro interno do modelo: Problema inesperado de processamento. Verifique os campos code e error na resposta da consulta para detalhes sobre a solução de problemas.