Skip to main content

General image editing - Wan2.1

O modelo de edição de imagens Wan executa diversas tarefas de edição a partir de prompts de texto: outpainting, remoção de marca d'água, transferência de estilo, edição baseada em instruções, inpainting local e restauração de imagens.

Este documento se aplica apenas à região China (Beijing). Para usar o modelo, é necessário obter uma chave de API da região China (Beijing).

Visão geral do modelo

Demonstração de desempenho

image

Imagem original

image

Mude o cabelo dela para vermelho

35779519-bfc3-4b0a-a594-d764fe9a46d83005601501

Adicione óculos escuros à garota

image

Converta para o estilo de livro ilustrado francês

Consulte Recursos principais .
Preços

Região de Beijing

A região de Beijing não oferece cota gratuita. Todas as chamadas são faturáveis. Confirme antes de prosseguir.

Modelo

Preço unitário

Limite de taxa (compartilhado pela conta Alibaba Cloud e usuários RAM)

Limite RPS para envio de tarefas

Número de tarefas simultâneas

wanx2.1-imageedit

$0,020070/imagem

2

2

Primeiros passos

Pré-requisitos

Obtenha uma chave de API e defina-a como variável de ambiente. Se você usar o DashScope SDK para fazer chamadas, também será necessário instalar o SDK.

Código de exemplo

Chame a API de edição de imagens para executar inpainting local.
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.
  • Python
  • Java
  • curl
Suporta três métodos de entrada: URL pública, codificação Base64 ou caminho de arquivo local.
Exemplo de requisição
import base64
import os
import mimetypes
import dashscope
from dashscope.v2 import DashScopeError

"""
Requisitos de ambiente:
    dashscope Python SDK >= 2.0.1
Instalar/atualizar o SDK:
    pip install -U dashscope
"""

# A configuração abaixo refere-se à região China (Pequim). Substitua {WorkspaceId} pelo ID real do seu workspace. O valor de region varia conforme a região.
client = dashscope.Client(
    # Se a variável de ambiente não estiver configurada, substitua a linha abaixo pela sua API Key do Model Studio: api_key="sk-xxx"
    # As API Keys variam conforme a região. Para obter uma API Key, consulte https://www.alibabacloud.com/help/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

# --- Função auxiliar: codificação Base64 ---
# O formato é 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("Formato de imagem não suportado ou não reconhecido")
    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 imagem:
Escolha um dos três métodos a seguir.

1. Usar uma URL pública - adequado para imagens acessíveis publicamente.
2. Usar um arquivo local - adequado para desenvolvimento e testes locais.
3. Usar codificação Base64 - adequado para imagens privadas ou cenários que exigem transmissão criptografada.
"""

# [Método 1] Usar uma URL pública de imagem
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 um arquivo local (caminhos absolutos e relativos são suportados)
# Requisito de formato: file:// + caminho do arquivo
# Exemplo (caminho absoluto):
# mask_image_url = "file://" + "/path/to/your/mask_image.png"     # Linux/macOS
# base_image_url = "file://" + "C:/path/to/your/base_image.jpeg"  # Windows
# Exemplo (caminho relativo):
# mask_image_url = "file://" + "./mask_image.png"                 # O caminho é relativo ao diretório de trabalho atual.
# base_image_url = "file://" + "./base_image.jpeg"                # O caminho é relativo ao diretório de trabalho atual.

# [Método 3] Usar uma imagem codificada em Base64
# mask_image_url = encode_file("./mask_image.png")               # O caminho é relativo ao diretório de trabalho atual.
# base_image_url = encode_file("./base_image.jpeg")              # O caminho é relativo ao diretório de trabalho atual.

def sample_sync_call_imageedit():
    print('Processando... aguarde um momento.')
    try:
        # generate é uma chamada de uma etapa (envia a tarefa e aguarda a conclusão) e retorna um Job concluído
        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 são campos de entrada específicos da edição, passados via extra_input para a seção input da solicitação
            extra_input={
                "mask_image_url": mask_image_url,
                "base_image_url": base_image_url,
            },
            n=1,
        )
        print('resposta: %s' % job)
        for url in job.image_urls:
            print("---------------------------")
            print(url)
    except DashScopeError as e:
        print(f"Código de status HTTP: {e.status_code}")
        print(f"Código de erro: {e.code}")
        print(f"Mensagem de erro: {e.message}")
        print("Consulte a documentação: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code")

if __name__ == '__main__':
    sample_sync_call_imageedit()
Exemplo de resposta
A URL expira em 24 horas. Baixe a imagem antes desse prazo.
{
    "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
    }
}

Recursos principais

Use o parâmetro function para especificar os recursos de edição. Todos os recursos seguem o mesmo método de chamada descrito em Primeiros passos. As seções a seguir apresentam exemplos curl com os campos JSON input e parameters específicos de cada recurso.
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

Transfere um estilo artístico para toda a imagem. Casos de uso: criação de livros ilustrados, fundos para redes sociais ou imagens conceituais que correspondam a um estilo específico.
  • 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

image

image

image

image

image

image

Controle o grau de modificação da imagem com strength
O parâmetro parameters.strength (0,0–1,0, padrão: 0,5) controla a intensidade da modificação: valores próximos de 0 preservam o original, enquanto valores próximos de 1 aplicam mais alterações.
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)

image

image

image

image

Estilização local

Aplica transferência de estilo apenas a uma área específica. Casos de uso: personalização (roupas de personagens) ou design publicitário (destaque de produtos).
  • 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

image

image

Ice Sculpture

image

Cloud

image

Chinese festive lantern

image

Wooden

image

Blue and white porcelain

image

Fluffy

image
Weaving

image

Balloon

Edição baseada em instruções

Adiciona ou modifica conteúdo por meio de instruções de texto sem especificar áreas. Casos de uso: edições simples sem posicionamento preciso (adicionar acessórios, mudar a cor do cabelo).
  • 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

image

image

Add a pair of sunglasses to the kitten.

Modificar um elemento

image

image

Change her hair to red.

Controle o grau de modificação da imagem com strength
O parâmetro parameters.strength (0,0–1,0, padrão: 0,5) controla a intensidade da modificação: valores próximos de 0 preservam o original, enquanto valores próximos de 1 aplicam mais alterações.
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)

image

image

image

image

Inpainting local

Adiciona, modifica ou exclui conteúdo em uma área mascarada. Casos de uso: edições que exigem controle preciso (trocar roupas, substituir objetos, remover elementos indesejados).
  • 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"
  }
}
CapacidadesImagem de entradaImagem de máscara de entrada(Branco é a área a ser editada)Imagem de saída
Adicionar um elemento
image
image
image
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
image
image
image
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
image
image
image
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

Aviso de risco legalO uso deste recurso para processar imagens protegidas por direitos autorais (como remover a marca d'água de outra marca) pode constituir violação de direitos autorais. Certifique-se de ter o direito legal de usar a imagem processada e assuma todas as responsabilidades legais relacionadas.
Remove textos em chinês/inglês ou marcas d'água. Casos de uso: processamento de materiais ou limpeza de anúncios.
  • 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)

image

image

image

image

Outpainting

Expande a imagem proporcionalmente em todas as direções e preenche o conteúdo inteligentemente. Casos de uso: ajustar composição ou converter proporções para diferentes mídias.
  • 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

image

image

Super-resolução de imagem

Melhora a nitidez da imagem e suporta upscaling para imagens de baixa resolução ou desfocadas. Casos de uso: restaurar fotos antigas ou aumentar a resolução para impressão/exibição em HD.
  • 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)

image

image

Colorização de imagem

Converte imagens em preto e branco ou escala de cinza para coloridas. Casos de uso: colorir fotos históricas ou desenhos lineares.
  • 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

image

image

Desenho linear para imagem (suporta desenho baseado em rabiscos)

Gera imagens a partir de contornos lineares e prompts de texto. Casos de uso: conceitos arquitetônicos, ilustrações ou desenhos baseados 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)

image

image

A living room in a minimalist Nordic style.

Desenho baseado em rabiscos

(is_sketch=true)

image

image

A tree, in a two-dimensional anime style.

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

Aviso de risco legalO uso deste recurso para processar personagens de desenhos animados protegidos por direitos autorais pode constituir violação de direitos autorais. Você deve ter o direito legal de usar o personagem referenciado ou usar seu próprio personagem original. Você também deve assumir todas as responsabilidades legais relacionadas.
  • 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

image

image

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

Para mais informações sobre os parâmetros de entrada e resposta, consulte Referência da API de edição geral de imagens.

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

Se a chamada do modelo falhar e retornar uma mensagem de erro, consulte Códigos de erro para resolução.

FAQ

P: Por que minha tarefa falhou (FAILED)? R: Os motivos comuns para falha na tarefa incluem:
  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.