Pengeditan gambar umum - Wan2.1

​

Ikhtisar model

Gambar asli

Ubah rambutnya menjadi merah

Tambahkan sepasang kacamata hitam pada gadis tersebut

Konversi ke gaya buku bergambar Prancis

Lihat Fitur utama.

​

Mulai

​

Prasyarat

​

Kode contoh

SDK mengenkapsulasi pemrosesan async, sehingga antarmuka berperilaku secara sinkron — satu permintaan menunggu hasilnya. Contoh curl menunjukkan dua operasi async terpisah: kirim task dan kueri hasil.

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

"""
Persyaratan lingkungan:
    dashscope python SDK >= 1.23.8
Instal/Perbarui SDK:
    pip install -U dashscope
"""

# Jika variabel lingkungan belum dikonfigurasi, ganti baris berikut dengan: api_key="sk-xxx"
api_key = os.getenv("DASHSCOPE_API_KEY")

# --- Fungsi bantu: untuk encoding Base64 ---
# Formatnya adalah 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("Format gambar tidak didukung atau tidak dikenali")
    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}"

"""
Metode input gambar:
Pilih salah satu dari tiga metode berikut.

1. Gunakan URL publik - cocok untuk gambar yang dapat diakses publik.
2. Gunakan file lokal - cocok untuk pengembangan dan pengujian lokal.
3. Gunakan encoding Base64 - cocok untuk gambar privat atau skenario yang memerlukan transmisi terenkripsi.
"""

# [Metode 1] Gunakan URL gambar publik
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"

# [Metode 2] Gunakan file lokal (mendukung jalur absolut dan relatif)
# Persyaratan format: file:// + jalur file
# Contoh (jalur absolut):
# mask_image_url = "file://" + "/path/to/your/mask_image.png"     # Linux/macOS
# base_image_url = "file://" + "C:/path/to/your/base_image.jpeg"  # Windows
# Contoh (jalur relatif):
# mask_image_url = "file://" + "./mask_image.png"                 # Sesuaikan dengan jalur aktual
# base_image_url = "file://" + "./base_image.jpeg"                # Sesuaikan dengan jalur aktual

# [Metode 3] Gunakan gambar yang di-encode Base64
# mask_image_url = encode_file("./mask_image.png")               # Sesuaikan dengan jalur aktual
# base_image_url = encode_file("./base_image.jpeg")              # Sesuaikan dengan jalur aktual

def sample_sync_call_imageedit():
    print('mohon tunggu...')
    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 Gagal, 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;

/**
 * Persyaratan lingkungan
 *      dashscope java SDK >=2.20.9
 * Perbarui dependensi Maven:
 *      https://mvnrepository.com/artifact/com.alibaba/dashscope-sdk-java
 */

public class ImageEditSync {

    // Jika variabel lingkungan belum dikonfigurasi, ganti baris berikut dengan: apiKey="sk-xxx"
    static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    /**
     * Metode input gambar: Pilih salah satu dari tiga berikut.
     *
     * 1. Gunakan URL publik - cocok untuk gambar yang dapat diakses publik.
     * 2. Gunakan file lokal - cocok untuk pengembangan dan pengujian lokal.
     * 3. Gunakan encoding Base64 - cocok untuk gambar privat atau skenario yang memerlukan transmisi terenkripsi.
     */

    //[Metode 1] URL publik
    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";

    //[Metode 2] Jalur file lokal (file://+jalur absolut atau file:///+jalur absolut)
    // static String maskImageUrl = "file://" + "/your/path/to/mask_image.png";    // Linux/macOS
    // static String baseImageUrl = "file:///" + "C:/your/path/to/base_image.png";  // Windows

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

    public static void syncCall() {
        // Setel parameter 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("---panggilan sinkron, mohon tunggu sebentar----");
            result = imageSynthesis.call(param);
        } catch (ApiException | NoApiKeyException e){
            throw new RuntimeException(e.getMessage());
        }
        System.out.println(JsonUtils.toJson(result));
    }

    /**
     * Meng-encode file menjadi string Base64
     * @param filePath Jalur file
     * @return String Base64 dalam 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 tidak ada: " + filePath);
        }
        // Deteksi tipe MIME
        String mimeType = null;
        try {
            mimeType = Files.probeContentType(path);
        } catch (IOException e) {
            throw new IllegalArgumentException("Tidak dapat mendeteksi tipe file: " + filePath);
        }
        if (mimeType == null || !mimeType.startsWith("image/")) {
            throw new IllegalArgumentException("Format gambar tidak didukung atau tidak dikenali");
        }
        // Baca konten file dan encode
        byte[] fileBytes = null;
        try{
            fileBytes = Files.readAllBytes(path);
        } catch (IOException e) {
            throw new IllegalArgumentException("Tidak dapat membaca konten file: " + 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://dashscope.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
    }
}

​

Fitur utama

Catatan: Permintaan curl lengkap harus mencakup bidang tingkat atas seperti model, input, dan parameters. Untuk detail struktur, lihat Referensi API pengeditan gambar umum.

​

Stilisasi global

• Atur function ke stylization_all.
• Gaya yang didukung:
  • Gaya buku bergambar Prancis
  • Gaya seni foil emas
• parameters.strength (0,0–1,0, default: 0,5) mengontrol intensitas modifikasi. Nilai lebih rendah mempertahankan lebih banyak elemen asli.
• Format prompt: "Convert to [style]" (misalnya, "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
  }
}

Gambar input	Gambar output
	Prompt: Convert to French picture book style	Prompt: Convert to gold foil art style

Kontrol tingkat modifikasi gambar dengan strength

Prompt input: Convert to French picture book style.

Gambar input	Gambar output
	strength=0.0 (nilai minimum)	strength=0.5 (nilai default)	strength=1.0 (nilai maksimum)

​

Stilisasi lokal

• Atur function ke stylization_local.
• Gaya yang didukung: Gaya yang didukung dan nilai yang sesuai adalah:
  • Patung es: es
  • Cloud: cloud
  • Lentera perayaan Tiongkok: chinese festive lantern
  • Papan: kayu
  • Porselen biru-putih: blue and white porcelain
  • Fluffy: fluffy
  • Benang rajut: weaving
  • Balon: balloon
• Format prompt: "Change [object] to [style]" (misalnya, "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"
  }
}

Gambar input	Gambar output
	Ice Sculpture	Cloud	Chinese festive lantern	Wooden
	Blue and white porcelain	Fluffy	Weaving	Balloon

​

Pengeditan berbasis instruksi

• Atur function ke description_edit.
• parameters.strength (0,0–1,0, default: 0,5) mengontrol intensitas modifikasi. Nilai lebih rendah mempertahankan lebih banyak elemen asli.
• Prompt: Sertakan kata kerja aksi seperti "add" atau "modify". Untuk penghapusan, gunakan Inpainting lokal sebagai gantinya.

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

Capabilities	Input image	Output image
Add an element		Tambahkan sepasang kacamata hitam ke anak kucing tersebut.
Modify an element		Ubah warna rambutnya menjadi merah.

Kontrol tingkat modifikasi gambar dengan strength

Input prompt: Ubah pakaiannya menjadi kemeja pantai bermotif warna-warni.

Gambar input	Gambar output
	strength=0.0 (nilai minimum)	strength=0.5 (nilai default)	strength=1.0 (nilai maksimum)

​

Inpainting lokal

• Atur function ke description_edit_with_mask.
• Persyaratan mask: Sediakan mask_image_url dengan area putih = area diedit, area hitam = area dipertahankan.
• Prompt: Sertakan aksi ("add", "modify") dan jelaskan konten setelah penghapusan untuk kasus penghapusan.
  • Tambah/Modifikasi: Jelaskan aksi atau hasil akhir.
  • Hapus: Biarkan prompt kosong untuk objek kecil. Untuk objek besar, jelaskan latar belakang yang diinginkan setelah penghapusan — bukan aksi penghapusannya sendiri.

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

Kemampuan	Gambar input	Input Mask Image(Putih adalah area yang akan diedit)	Gambar output
Tambah elemen			Add a hat to the puppy. Anda juga dapat menulis prompt sebagai "A puppy wearing a hat" untuk menggambarkan konten gambar yang diharapkan.
Ubah elemen			A ceramic rabbit holding a ceramic flower. Anda juga dapat menulis prompt sebagai "Replace the carrot held by the ceramic rabbit with a ceramic flower" untuk menggambarkan aksi.
Hapus elemen			A transparent glass vase on the table. Prompt harus menggambarkan konten setelah penghapusan. Jangan menulisnya sebagai "Delete the brown bear".

​

Penghapusan teks dan watermark

• Atur function ke remove_watermark.
• Prompt: Gunakan instruksi umum ("Remove the text") atau tentukan jenisnya ("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"
  }
}

Gambar input	Gambar hasil (Hapus teks pada gambar)

​

Outpainting

• Atur function ke expand.
• Parameter terkait: top_scale, bottom_scale, left_scale, dan right_scale mengontrol rasio perluasan per arah (misalnya, 1,5 = ukuran 1,5×).
• Saran prompt: Gambarkan adegan lengkap yang Anda harapkan setelah perluasan.

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

Gambar input	Gambar output

​

Super-resolusi gambar

• Atur function ke super_resolution.
• parameters.upscale_factor (1–4, default: 1) mengontrol upscaling. Nilai 1 hanya meningkatkan kejernihan, tanpa memperbesar.
• Saran prompt: Gunakan "Image super resolution" atau gambarkan konten gambar.

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

Gambar input (gambar buram)	Gambar output (gambar jernih)

​

Pewarnaan gambar

• Atur function ke colorization.
• Prompt: Biarkan kosong untuk pewarnaan otomatis, atau tentukan warna elemen kunci (misalnya, "blue background, yellow leaves").

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

Gambar input	Gambar output

​

Garis ilustrasi ke gambar (mendukung gambar berbasis coretan)

• Atur function ke doodle.
• Parameter terkait: parameters.is_sketch, yang mengontrol hasil pembuatan gambar.
  • false (default): Model mengekstraksi garis ilustrasi dari input RGB, lalu menghasilkan gambar (RGB → garis ilustrasi → gambar).
  • true: Model menghasilkan langsung dari input RGB seperti coretan (RGB → gambar).
• Prompt: Gambarkan konten yang diharapkan — semakin detail, hasilnya semakin baik.

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

Kemampuan	Gambar input	Gambar output
Garis ilustrasi ke gambar (is_sketch=false)		A living room in a minimalist Nordic style.
Gambar berbasis coretan (is_sketch=true)		A tree, in a two-dimensional anime style.

​

Buat gambar berdasarkan karakter kartun referensi

• Atur function ke control_cartoon_feature.
• Format prompt: "The cartoon character [detail aksi/lingkungan]..."

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

Gambar input	Gambar output

​

Produksi

​

Praktik terbaik

• Polling asinkron: Gunakan interval polling bertahap (misalnya, setiap 3 detik selama 30 detik, lalu tingkatkan) untuk menghindari batas laju.
• Penyetelan parameter: Uji parameter kunci seperti strength dalam uji coba skala kecil sebelum produksi untuk menemukan nilai optimal.
• Penyimpanan gambar: URL yang dikembalikan API kedaluwarsa setelah 24 jam. Unduh gambar dan pindahkan ke penyimpanan persisten (misalnya, OSS) segera.

​

Pencegahan risiko

• Penanganan error: Periksa task_status dalam hasil kueri. Jika FAILED, catat code dan message untuk troubleshooting. Error sementara (misalnya, timeout) mungkin berhasil saat dicoba ulang.
• Moderasi konten: API meninjau semua input/output untuk kepatuhan. Konten yang tidak sesuai mengembalikan DataInspectionFailed.

​

Referensi API

​

Penagihan dan pembatasan laju

• Untuk informasi mengenai kuota gratis dan harga model, lihat Pengeditan gambar Wan 2.1.
• Untuk pembatasan laju model, lihat Wan.
• Detail penagihan:
  • Penagihan dilakukan per jumlah gambar yang berhasil dihasilkan. Biaya hanya dikenakan jika task_status bernilai SUCCEEDED.
  • Panggilan gagal tidak dikenai biaya atau mengurangi Kuota gratis untuk pengguna baru.

​

Kode error

​

FAQ

1. Kegagalan moderasi konten: Input atau output memicu kebijakan keamanan.
2. Error parameter: Parameter permintaan tidak valid (misalnya, nama function salah atau URL tidak dapat diakses).
3. Error internal model: Masalah pemrosesan tak terduga. Periksa bidang code dan error dalam respons kueri untuk detail troubleshooting.