Alibaba Cloud Model Studio:Wan2.1 - 汎用画像編集 API リファレンス

同期呼び出し

この例は同期呼び出しを示しており、パブリック URL、Base64 エンコーディング、ローカルファイルパスの 3 つの画像入力方法をサポートしています。

リクエスト例

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

"""
環境要件：
    dashscope python SDK >= 2.0.1
SDK のインストール/アップグレード：
    pip install -U dashscope
"""

# 以下の設定は中国 (北京) リージョン用です。呼び出し時に {WorkspaceId} を実際のワークスペース ID に置き換えてください。region の値はリージョンによって異なります。
client = dashscope.Client(
    # 環境変数が設定されていない場合は、次の行を api_key="sk-xxx" に置き換えてください
    # API キーはリージョンによって異なります。API キーの取得： https://www.alibabacloud.com/help/ja/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

# --- ヘルパー関数：Base64 エンコーディング用 ---
# フォーマットは 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("サポートされていない、または認識されない画像フォーマットです")
    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}"

"""
画像の入力方法：
次の 3 つの方法から 1 つを選択します。

1. パブリック URL を使用 - 一般にアクセス可能な画像に適しています。
2. ローカルファイルを使用 - ローカルでの開発やテストに適しています。
3. Base64 エンコーディングを使用 - 非公開の画像や暗号化された伝送が必要なシナリオに適しています。
"""

# [方法 1] パブリック画像 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"

# [方法 2] ローカルファイルを使用 (絶対パスと相対パスをサポート)
# フォーマット要件：file:// + ファイルパス
# 例 (絶対パス)：
# mask_image_url = "file://" + "/path/to/your/mask_image.png"     # Linux/macOS
# base_image_url = "file://" + "C:/path/to/your/base_image.jpeg"  # Windows
# 例 (相対パス)：
# mask_image_url = "file://" + "./mask_image.png"                 # 実際のパスに基づく
# base_image_url = "file://" + "./base_image.jpeg"                # 実際のパスに基づく

# [方法 3] Base64 エンコードされた画像を使用
# mask_image_url = encode_file("./mask_image.png")               # 実際のパスに基づく
# base_image_url = encode_file("./base_image.jpeg")              # 実際のパスに基づく

def sample_sync_call_imageedit():
    print('please wait...')
    try:
        # generate はワンステップ呼び出し（タスクを送信して完了まで待機）で、完了済みの Job を返します
        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 は編集専用の入力フィールドであり、extra_input 経由でリクエストの input セクションに渡します
            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"HTTP status code: {e.status_code}")
        print(f"Error code: {e.code}")
        print(f"Error message: {e.message}")
        print("See the documentation: https://www.alibabacloud.com/help/ja/model-studio/developer-reference/error-code")

if __name__ == '__main__':
    sample_sync_call_imageedit()

レスポンス例

URL は 24 時間有効です。速やかに画像をダウンロードしてください。

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

非同期呼び出し

この例は、非同期呼び出しメソッドのみを示しています。

リクエスト例

import os
import dashscope
from dashscope.v2 import DashScopeError

"""
環境要件：
    dashscope python SDK >= 2.0.1
SDK のインストール/アップグレード：
    pip install -U dashscope
"""

# 以下の設定は中国 (北京) リージョン用です。呼び出し時に {WorkspaceId} を実際のワークスペース ID に置き換えてください。region の値はリージョンによって異なります。
client = dashscope.Client(
    # 環境変数が設定されていない場合は、次の行を api_key="sk-xxx" に置き換えてください
    # API キーはリージョンによって異なります。API キーの取得： https://www.alibabacloud.com/help/ja/model-studio/get-api-key
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="cn-beijing",
)

# パブリック画像 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"

def sample_async_call_imageedit():
    try:
        # 非同期呼び出し（タスクを送信）、task_id を含む Job オブジェクトを返します
        job = client.images.jobs.create(
            model="wanx2.1-imageedit",
            function="description_edit_with_mask",
            prompt="A ceramic rabbit holding a ceramic flower",
            # mask_image_url/base_image_url は編集専用の入力フィールドであり、extra_input 経由でリクエストの input セクションに渡します
            extra_input={
                "mask_image_url": mask_image_url,
                "base_image_url": base_image_url,
            },
            n=1,
        )
        print(job)
        print("task_id: %s" % job.task_id)

        # 非同期タスク情報を取得
        snapshot = client.images.jobs.fetch(job.task_id)
        print(snapshot.status)  # タスクのステータスを確認

        # 非同期タスクが終了するのを待つ（指数バックオフでポーリング、デフォルトの合計予算は 24 時間。FAILED のタスクは DashScopeError をスローします）
        done = client.images.jobs.wait(job.task_id)
        print(done)
        for url in done.image_urls:
            print("---------------------------")
            print(url)
    except DashScopeError as e:
        print(f"HTTP status code: {e.status_code}")
        print(f"Error code: {e.code}")
        print(f"Error message: {e.message}")
        print("See the documentation: https://www.alibabacloud.com/help/ja/model-studio/developer-reference/error-code")

if __name__ == '__main__':
    sample_async_call_imageedit()

レスポンス例

1. タスク作成のレスポンス例

{
	"status_code": 200,
	"request_id": "6dc3bf6c-be18-9268-9c27-xxxxxx",
	"code": "",
	"message": "",
	"output": {
		"task_id": "686391d9-7ecf-4290-a8e9-xxxxxx",
		"task_status": "PENDING",
		"video_url": ""
	},
	"usage": null
}

2. タスク結果クエリのレスポンス例

URL は 24 時間有効です。速やかに画像をダウンロードしてください。

{
    "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?Expires=17xxxxxx"
            }
        ],
        "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
    }
}

同期呼び出し

この例は同期呼び出しを示しており、パブリック URL、Base64 エンコーディング、ローカルファイルパスの 3 つの画像入力方法をサポートしています。

リクエスト例

// 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;

/**
 * 環境要件
 *      dashscope java SDK >=2.20.9
 * Maven 依存関係の更新：
 *      https://mvnrepository.com/artifact/com.alibaba/dashscope-sdk-java
 */

public class ImageEditSync {
    static {Constants.baseHttpApiUrl="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";}

    // 環境変数が設定されていない場合は、次の行を apiKey="sk-xxx" に置き換えてください
    static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    /**
     * 画像の入力方法：次の 3 つから 1 つを選択します。
     *
     * 1. パブリック URL を使用 - 一般にアクセス可能な画像に適しています。
     * 2. ローカルファイルを使用 - ローカルでの開発やテストに適しています。
     * 3. Base64 エンコーディングを使用 - 非公開の画像や暗号化された伝送が必要なシナリオに適しています。
     */

    //[方法 1] パブリック 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";

    //[方法 2] ローカルファイルパス (file://+絶対パス または file:///+絶対パス)
    // static String maskImageUrl = "file://" + "/your/path/to/mask_image.png";    // Linux/macOS
    // static String baseImageUrl = "file:///" + "C:/your/path/to/base_image.png";  // Windows

    //[方法 3] 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() {
        // 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("---同期呼び出し、しばらくお待ちください----");
            result = imageSynthesis.call(param);
        } catch (ApiException | NoApiKeyException e){
            throw new RuntimeException(e.getMessage());
        }
        System.out.println(JsonUtils.toJson(result));
    }

    /**
     * ファイルを Base64 文字列にエンコードします
     * @param filePath ファイルパス
     * @return data:{MIME_type};base64,{base64_data} 形式の Base64 文字列
     */
    public static String encodeFile(String filePath) {
        Path path = Paths.get(filePath);
        if (!Files.exists(path)) {
            throw new IllegalArgumentException("ファイルが存在しません: " + filePath);
        }
        // MIME タイプを検出
        String mimeType = null;
        try {
            mimeType = Files.probeContentType(path);
        } catch (IOException e) {
            throw new IllegalArgumentException("ファイルタイプを検出できません: " + filePath);
        }
        if (mimeType == null || !mimeType.startsWith("image/")) {
            throw new IllegalArgumentException("サポートされていない、または認識されない画像フォーマットです");
        }
        // ファイルの内容を読み取り、エンコードする
        byte[] fileBytes = null;
        try{
            fileBytes = Files.readAllBytes(path);
        } catch (IOException e) {
            throw new IllegalArgumentException("ファイルの内容を読み取れません: " + filePath);
        }

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

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

レスポンス例

URL は 24 時間有効です。速やかに画像をダウンロードしてください。

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

非同期呼び出し

この例は、非同期呼び出しメソッドのみを示しています。

リクエスト例

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

import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesis;
import com.alibaba.dashscope.aigc.imagesynthesis.ImageSynthesisListResult;
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.task.AsyncTaskListParam;
import com.alibaba.dashscope.utils.Constants;
import com.alibaba.dashscope.utils.JsonUtils;

import java.util.HashMap;
import java.util.Map;

/**
 * 環境要件
 *      dashscope java SDK >= 2.20.1
 * Maven 依存関係の更新：
 *      https://mvnrepository.com/artifact/com.alibaba/dashscope-sdk-java
 */

public class ImageEditAsync {
    static {Constants.baseHttpApiUrl="https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";}

    // 環境変数が設定されていない場合は、次の行を apiKey="sk-xxx" に置き換えてください
    static String apiKey = System.getenv("DASHSCOPE_API_KEY");

    //[方法 1] パブリック 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";

    public static void asyncCall() {
        // 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("---非同期呼び出し、しばらくお待ちください----");
            result = imageSynthesis.asyncCall(param);
        } catch (ApiException | NoApiKeyException e){
            throw new RuntimeException(e.getMessage());
        }

        System.out.println(JsonUtils.toJson(result));

        String taskId = result.getOutput().getTaskId();

        System.out.println("taskId=" + taskId);

        try {
            result = imageSynthesis.wait(taskId, apiKey);
        } catch (ApiException | NoApiKeyException e){
            throw new RuntimeException(e.getMessage());
        }
        System.out.println(JsonUtils.toJson(result));
        System.out.println(JsonUtils.toJson(result.getOutput()));
    }

    public static void listTask() throws ApiException, NoApiKeyException {
        ImageSynthesis is = new ImageSynthesis();
        AsyncTaskListParam param = AsyncTaskListParam.builder().build();
        param.setApiKey(apiKey);
        ImageSynthesisListResult result = is.list(param);
        System.out.println(result);
    }

    public void fetchTask(String taskId) throws ApiException, NoApiKeyException {
        ImageSynthesis is = new ImageSynthesis();
        // DASHSCOPE_API_KEY が環境変数として設定されている場合、apiKey は空にできます。
        ImageSynthesisResult result = is.fetch(taskId, apiKey);
        System.out.println(result.getOutput());
        System.out.println(result.getUsage());
    }

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

レスポンス例

1. タスク作成のレスポンス例

{
	"request_id": "5dbf9dc5-4f4c-9605-85ea-xxxxxxxx",
	"output": {
		"task_id": "7277e20e-aa01-4709-xxxxxxxx",
		"task_status": "PENDING"
	}
}

2. タスク結果クエリのレスポンス例

URL は 24 時間有効です。速やかに画像をダウンロードしてください。

{
	"request_id": "3d740fc4-a968-9c36-b0e7-xxxxxxxx",
	"output": {
		"task_id": "34dcf4b0-ed84-441e-91cb-xxxxxxxx",
		"task_status": "SUCCEEDED",
		"results": [
			{
				"url": "https://dashscope-result-hz.oss-cn-hangzhou.aliyuncs.com/xxx.png"
			}
		],
		"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",
		"task_metrics": {
			"TOTAL": 1,
			"SUCCEEDED": 1,
			"FAILED": 0
		}
	},
	"usage": {
		"image_count": 1
	}
}