Edición general de imágenes - Wan2.1

​

Resumen de modelos

Imagen original

Cambiar su cabello a rojo

Añadir un par de gafas de sol a la niña

Convertir al estilo de libro ilustrado francés

Consulte Características clave.

​

Introducción

​

Requisitos previos

​

Código de ejemplo

El SDK encapsula el procesamiento asíncrono, por lo que la interfaz se comporta de manera síncrona: una sola solicitud espera el resultado. El ejemplo de curl muestra dos operaciones asíncronas separadas: enviar tarea y consultar resultado.

import base64
import os
import mimetypes
import dashscope
from dashscope.v2 import DashScopeError

"""
Requisitos del entorno:
    SDK de Python dashscope >= 2.0.1
Instalación/actualización del SDK:
    pip install -U dashscope
"""

# La siguiente configuración corresponde a la región de China (Pekín). Sustituya {WorkspaceId} por el ID real de su espacio de trabajo (workspace) al realizar la llamada. El valor de region varía según la región.
client = dashscope.Client(
    # Si la variable de entorno no está configurada, sustituya la siguiente línea por su API Key de Model Studio: api_key="sk-xxx"
    # Las claves de API difieren según la región. Para obtener una clave de API, véase https://www.alibabacloud.com/help/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

# --- Función auxiliar: codificación Base64 ---
# El formato es 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}"

"""
Métodos de entrada de imagen:
Se proporcionan los tres métodos siguientes; elija uno de ellos:

1. Usar una URL pública - para imágenes ya accesibles públicamente
2. Usar un archivo local - para desarrollo y pruebas locales
3. Usar codificación Base64 - para imágenes privadas o escenarios que requieren transmisión cifrada
"""

# [Método 1] Usar una URL pública de imagen
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"

# [Método 2] Usar un archivo local (se admiten rutas absolutas y relativas)
# Requisito de formato: file:// + ruta del archivo
# Ejemplo (ruta absoluta):
# mask_image_url = "file://" + "/path/to/your/mask_image.png"     # Linux/macOS
# base_image_url = "file://" + "C:/path/to/your/base_image.jpeg"  # Windows
# Ejemplo (ruta relativa):
# mask_image_url = "file://" + "./mask_image.png"                 # Use la ruta real
# base_image_url = "file://" + "./base_image.jpeg"                # Use la ruta real

# [Método 3] Usar una imagen codificada en Base64
# mask_image_url = encode_file("./mask_image.png")               # Use la ruta real
# base_image_url = encode_file("./base_image.jpeg")              # Use la ruta real

def sample_sync_call_imageedit():
    print('Espere, por favor...')
    try:
        # generate es una llamada de un solo paso ("enviar + esperar") que devuelve un objeto Job completado.
        job = client.images.generate(
            model="wanx2.1-imageedit",
            function="description_edit_with_mask",
            prompt="A ceramic rabbit holding a ceramic flower",
            # mask_image_url/base_image_url son campos de edición de la sección input, que se pasan mediante extra_input a la sección input de la solicitud.
            extra_input={
                "mask_image_url": mask_image_url,
                "base_image_url": base_image_url,
            },
            n=1,
        )
        print('response: %s' % job)
        for url in job.image_urls:
            print("---------------------------")
            print(url)
    except DashScopeError as e:
        print(f"Código de estado HTTP: {e.status_code}")
        print(f"Código de error: {e.code}")
        print(f"Mensaje de error: {e.message}")
        print("Consulte la documentación: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")

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.Constants;
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 {
    static {Constants.baseHttpApiUrl="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";}

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

    /**
     * Image input methods: Choose one of the following three.
     *
     * 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 requiring 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 parameter
        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("---sync call, please wait a moment----");
            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 file path
     * @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://{WorkspaceId}.cn-beijing.maas.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
    }
}

​

Características clave

Una solicitud completa de curl debe incluir campos de nivel superior como model, input y parameters, tal como se describe en la Referencia de la API de edición general de imágenes.

​

Estilización global

• Establezca function en stylization_all.
• Estilos admitidos:
  • Estilo de libro ilustrado francés
  • Estilo artístico de pan de oro
• parameters.strength (0.0–1.0, valor predeterminado: 0.5) controla la intensidad de la modificación. Los valores más bajos conservan más del original.
• Formato del prompt: "Convertir a [estilo]" (por ejemplo, "Convertir a estilo de libro ilustrado francés").

{
  "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
  }
}

Imagen de entrada	Imagen de salida
	Prompt: Convertir a estilo de libro ilustrado francés	Prompt: Convertir a estilo artístico de pan de oro

Controle el grado de modificación de la imagen con strength

Prompt de entrada: Convertir a estilo de libro ilustrado francés.

Imagen de entrada	Imagen de salida
	strength=0.0 (valor mínimo)	strength=0.5 (valor predeterminado)	strength=1.0 (valor máximo)

​

Estilización local

• Establezca function en stylization_local.
• Estilos admitidos y valores de parámetros:
  • Escultura de hielo: ice
  • Nube: cloud
  • Farol festivo chino: chinese festive lantern
  • Tablón: wooden
  • Porcelana azul y blanca: blue and white porcelain
  • Esponjoso: fluffy
  • Hilo: weaving
  • Globo: balloon
• Formato del prompt: "Cambiar [objeto] a [estilo]" (por ejemplo, "Cambiar la casa a estilo de madera").

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

Imagen de entrada	Imagen de salida
	Escultura de hielo	Nube	Farol festivo chino	Madera
	Porcelana azul y blanca	Esponjoso	Tejido	Globo

​

Edición basada en instrucciones

• Establezca function en description_edit.
• parameters.strength (0.0–1.0, valor predeterminado: 0.5) controla la intensidad de la modificación. Los valores más bajos conservan más del original.
• Prompt: Incluya verbos de acción como "agregar" o "modificar". Para eliminaciones, utilice Inpainting local en su lugar.

{
  "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	Imagen de entrada	Imagen de salida
Añadir un elemento		Añadir un par de gafas de sol al gatito.
Modificar un elemento		Cambiar su cabello a rojo.

Controle el grado de modificación de la imagen con strength

Prompt de entrada: Cambiar su ropa por una camisa de playa estampada y colorida.

Imagen de entrada	Imagen de salida
	strength=0.0 (valor mínimo)	strength=0.5 (valor predeterminado)	strength=1.0 (valor máximo)

​

Inpainting local

• Establezca function en description_edit_with_mask.
• Requisitos de máscara: Proporcione mask_image_url donde blanco = área a editar, negro = área a conservar.
• Prompt: Incluya acciones ("agregar", "modificar") y describa el contenido posterior a la eliminación para las supresiones.
  • Añadir/Modificar: Describa la acción o el resultado final.
  • Eliminar: Deje prompt vacío para objetos pequeños. Para objetos grandes, describa el fondo deseado después de la eliminación, no la acción de eliminación en sí.

{
  "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	Imagen de entrada	Imagen de máscara de entrada(El blanco es el área a editar)	Imagen de salida
Añadir un elemento			Añadir un sombrero al cachorro. Alternativamente, describa el resultado esperado: "Un cachorro con sombrero".
Modificar un elemento			Un conejo de cerámica sosteniendo una flor de cerámica. Alternativamente, describa la acción: "Reemplazar la zanahoria sostenida por el conejo de cerámica con una flor de cerámica".
Eliminar un elemento			Un jarrón de vidrio transparente sobre la mesa. Describa la escena después de la eliminación, no la eliminación en sí; no escriba "Eliminar el oso pardo".

​

Eliminación de texto y marcas de agua

• Establezca function en remove_watermark.
• Prompt: Use instrucciones generales ("Eliminar el texto") o especifique el tipo ("Eliminar texto en inglés").

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

Imagen de entrada	Imagen de salida (Eliminar el texto en la imagen)

​

Outpainting

• Establezca function en expand.
• Parámetros relacionados: top_scale, bottom_scale, left_scale y right_scale controlan las proporciones de expansión por dirección (por ejemplo, 1.5 = 1.5× tamaño).
• Consejo de prompt: Describa la escena completa que espera ver después de la expansión.

{
  "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
  }
}

Imagen de entrada	Imagen de salida

​

Superresolución de imágenes

• Establezca function en super_resolution.
• parameters.upscale_factor (1–4, predeterminado: 1) controla el escalado. El valor 1 mejora solo la nitidez, sin ampliar.
• Consejo de prompt: Use "Superresolución de imagen" o describa el contenido de la imagen.

{
  "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
  }
}

Imagen de entrada (imagen borrosa)	Imagen de salida (imagen nítida)

​

Colorización de imágenes

• Establezca function en colorization.
• Prompt: Déjelo vacío para la colorización automática o especifique los colores de los elementos clave (por ejemplo, "fondo azul, hojas amarillas").

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

Imagen de entrada	Imagen de salida

​

De arte lineal a imagen

• Establezca function en doodle.
• Parámetro relacionado: parameters.is_sketch — controla cómo el modelo procesa la entrada.
  • false (predeterminado): El modelo extrae arte lineal de la entrada RGB y luego genera la imagen (RGB → arte lineal → imagen).
  • true: El modelo genera directamente desde la entrada RGB como garabatos (RGB → imagen).
• Prompt: Describa el contenido esperado; más detalle produce mejores 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	Imagen de entrada	Imagen de salida
De arte lineal a imagen (is_sketch=false)		Una sala de estar en un estilo nórdico minimalista.
Dibujo basado en garabatos (is_sketch=true)		Un árbol, en estilo de anime bidimensional.

​

Generar imagen basada en un personaje de caricatura de referencia

• Establezca function en control_cartoon_feature.
• Formato de prompt: "El personaje de dibujos animados [detalles de acción/entorno]..."

{
  "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"
  }
}

Imagen de entrada	Imagen de salida

​

Puesta en marcha

​

Mejores prácticas

• Sondeo asíncrono: Utilice intervalos de sondeo graduales (por ejemplo, cada 3 s durante 30 s, y luego aumente) para evitar límites de tasa.
• Ajuste de parámetros: Pruebe parámetros clave como strength en ensayos a pequeña escala antes de la producción para encontrar los valores óptimos.
• Almacenamiento de imágenes: Las URL de resultados caducan después de 24 horas. Descargue y transfiera al almacenamiento persistente (por ejemplo, OSS) de inmediato.

​

Prevención de riesgos

• Manejo de errores: Verifique task_status en los resultados de la consulta. Si es FAILED, registre code y message para la solución de problemas. Los errores transitorios (por ejemplo, tiempos de espera agotados) pueden resolverse al reintentar.
• Moderación de contenido: Todo el contenido de entrada y salida se revisa para garantizar el cumplimiento. El contenido que no cumpla las normas devuelve DataInspectionFailed.

​

Referencia de API

​

Facturación y limitación de tasa

• Cuotas gratuitas y precios: Wan edición de imágenes 2.1.
• Para la limitación de tasa del modelo, consulte Wanxiang.
• Detalles de facturación:
  • Facturado por imagen generada exitosamente. Los cargos se aplican solo cuando task_status es SUCCEEDED.
  • Las llamadas fallidas no generan cargos ni consumen la Cuota gratuita para nuevos usuarios.

​

Códigos de error

​

FAQ

1. Fallo en la moderación de contenido: La entrada o la salida activó la política de seguridad.
2. Error de parámetro: Parámetros de solicitud no válidos (por ejemplo, nombre de function incorrecto o URL inaccesible).
3. Error interno del modelo: problema de procesamiento inesperado. Verifique los campos code y error en la respuesta de la consulta.