Skip to main content

Wanxiang - Sketch to Image API Reference

This topic describes the API input and output parameters for the Wanxiang - Sketch to Image model.

Related guide: Sketch to image
This document applies only to the China (Beijing) region. Use an API key from this region.
Alibaba Cloud Model Studio has released a workspace-specific domain for the China (Beijing) region: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com. The new dedicated domain delivers superior performance and higher stability for inference requests. We recommend migrating from https://dashscope.aliyuncs.com to the new domain.{WorkspaceId} is your workspace ID, which can be found on the Workspace Details page in the Alibaba Cloud Model Studio console. The existing domain remains fully functional.

Model overview

Example output
image
Model overview

Model

Introduction

wanx-sketch-to-image-lite

The Wan sketch-to-image model generates exquisite graffiti artworks from hand-drawn patterns and text descriptions.

Model description

Model

Unit price

Rate limit (shared by Alibaba Cloud account and RAM users)

Free quota

Request per second (RPS) for task submission

Number of concurrent tasks

wanx-sketch-to-image-lite

CNY 0.06 per image

2

1

Free quota: 500 images

Valid for 180 days after activation

For more information, see Model billing and rate limiting.

Prerequisites

The Sketch to Image API can be invoked over HTTP or using the DashScope SDK. Before making a call, get an API key and export the API key as an environment variable. To call the API using the SDK, install the DashScope SDK. The SDK is available for Python and Java.

HTTP invocation

Image models take a long time to process. To prevent timeouts, HTTP calls support only asynchronous result retrieval. Two requests are required:
  1. Create a task to get a task ID: Send a request to create a task. The response returns a task ID (task_id).
  2. Query the result using the task ID: Use the task ID from the previous step to query the task status and result. If the task is successful, the response returns an image URL that is valid for 24 hours.
After creation, the task enters a queue for scheduling. Call the query API to retrieve the task status and result.

Step 1: Create a task and get the task ID

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis

Request parameters

Request headers
Content-Type string (Required)The content type of the request. Must be application/json.Authorization string (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.X-DashScope-Async string (Required)Enables asynchronous processing. HTTP requests support only asynchronous calls. Must be enable.
If this request header is missing, the error "current user api does not support synchronous calls" is returned.
X-DashScope-WorkSpace string (Optional)The ID of the Model Studio workspace. Example: llm-xxxx.You can get the Workspace ID.
Set this parameter to your Model Studio API key.
  • If you use an Alibaba Cloud account API key, this parameter is optional. Without it, Alibaba Cloud account permissions apply. With it, workspace permissions apply.
  • If you use a RAM user API key, this parameter is required because RAM users must belong to a workspace.
The workspace must have model access permission. If not granted, see Authorize a sub-workspace to call models.
For details about Alibaba Cloud accounts and RAM users, see Manage account.
Request body
modelstring(required)The model to invoke.inputobject(required)Basic input information, such as the prompt and image URL.

Properties

promptstring(required)The prompt used to describe the desired elements and visual features in the generated image.It supports both Chinese and English. The length cannot exceed 75 characters. Any excess characters are automatically truncated.Example: A towering tree.sketch_image_urlstring(required)The URL of the input sketch. The aspect ratio of the input sketch must be consistent with that of the output image. Otherwise, the image will be stretched or distorted. We recommend using an image with a white background.The URL must be publicly accessible and use HTTP or HTTPS.You can also obtain a temporary public URL.Image limits:
  • Image format: JPG, JPEG, PNG, TIFF, or WEBP.
  • Image resolution: Not smaller than 256 × 256 pixels and not larger than 2048 × 2048 pixels.
  • Image size: No larger than 10 MB.
  • The URL cannot contain Chinese characters.
Sketch example:image
parametersobject(optional)Image editing parameters.

Properties

stylestring(optional)The style of the output image. The following values are supported:
  • <auto>: The default value. The model randomly selects a style for the output image.
  • <3d cartoon>: 3D cartoon.
  • <anime>: The world of 2D animation.
  • <oil painting>: Oil painting.
  • <watercolor>: Watercolor.
  • <sketch>: Sketch.
  • <chinese painting>: Chinese painting.
  • <flat illustration>: Flat illustration.
sizestring(optional)The resolution of the output image. Currently, only 768*768 is supported, which is the default value.ninteger(optional)The number of images to generate. The value must be an integer from 1 to 4. The default value is 4.sketch_weightinteger(optional)The degree to which the input sketch constrains the output image.The value must be an integer from 0 to 10, with an interval of 1. The default value is 10. A larger value indicates a higher similarity between the output image and the input sketch.sketch_extractionboolean(optional)If the uploaded image is an RGB image instead of a sketch, this parameter controls whether to perform sketch edge extraction on the input image.The default value is False, which means no extraction is performed. If you set it to True, extraction is performed, and the sketch_color field becomes invalid.sketch_colorarray(optional)This field takes effect when sketch_extraction=false. The values it contains are treated as brush colors. All other values are treated as background colors. The model generates a new painting based on the areas drawn with one or more brush colors. The default value is [].If the lines in the sketch specified by sketch_image_url are not black but contain one or more other colors, you can specify one or more RGB color values as brush colors.Example: [[134, 134, 134], [0, 0, 0]]
  • curl
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": "wanx-sketch-to-image-lite",
    "input": {
        "sketch_image_url": "https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/6609471071/p743851.jpg",
        "prompt": "A towering tree"
    },
    "parameters": {
        "size": "768*768",
        "n": 2,
        "sketch_weight": 3,
        "style": "<watercolor>"
    }
}'

Response parameters

outputobjectTask output information.

Properties

task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.

Enumeration values

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: The task does not exist or its status is unknown.
request_id stringUnique request identifier for tracing and troubleshooting.code stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes.
  • Successful response
  • Error response
Save the task_id to query the task status and result.
{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

Step 2: Query the result by task ID

GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}

Request parameters

Headers

Authorization string (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.

Path parameters

task_id string (Required)The ID of the task.
  • Query task results
Replace 86ecf553-d340-4e21-xxxxxxxxx with your actual task_id.
If you use a model in the Singapore region, replace base_url with https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx, where {WorkspaceId} is your actual workspace ID.
curl -X GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Response parameters

outputobjectThe task output.

Properties

task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.

Enumeration values

  • PENDING
  • RUNNING
  • SUCCEEDED
  • FAILED
  • CANCELED
  • UNKNOWN: The task does not exist or its status is unknown.
task_metrics objectStatistics for the task result.

Properties

TOTAL integerThe total number of tasks.SUCCEEDED integerThe number of successful tasks.FAILED integerThe number of failed tasks.
results array of objectThe list of task results, including image URLs, error messages in case of partial task failure.
{
    "results": [
        {
            "url": ""
        },
        {
            "code": "",
            "message": ""
        }
    ]
}
code stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes.
usage objectThe output statistics. Only successful results are counted.

Properties

image_count integerNumber of images successfully generated. Billing: Cost = Number of images × Unit price.
request_id stringUnique request identifier for tracing and troubleshooting.
  • Success response
  • Failure response
  • Partial failure response
Task data (task status and image URLs) is retained for only 24 hours and then automatically purged. Save generated images promptly.
{
    "request_id": "85eaba38-0185-99d7-8d16-4d9135238846",
    "output": {
        "task_id": "86ecf553-d340-4e21-af6e-a0c6a421c010",
        "task_status": "SUCCEEDED",
        "results": [
            {
                "url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/123/a1.png"
            },
            {
                "url": "https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/123/b2.png"
            }
        ],
        "task_metrics": {
            "TOTAL": 2,
            "SUCCEEDED": 2,
            "FAILED": 0
        }
    },
    "usage": {
        "image_count": 2
    }
}

DashScope SDK invocation

Install the latest DashScope SDK. See Install the SDK. The DashScope SDK supports Python and Java. SDK parameter names are mostly consistent with the HTTP API. Parameter structure varies by SDK language. For details, see the HTTP Invocation section. Because image models take a long time to process, the underlying service is asynchronous. The SDK supports both synchronous and asynchronous calls.

Python SDK invocation

  • Synchronous call
  • Asynchronous invocation
Request example
import dashscope
from http import HTTPStatus
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath
import requests
from dashscope import ImageSynthesis
import os

dashscope.base_http_api_url = 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1'

prompt = "A towering tree"
sketch_image_url = "https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/6609471071/p743851.jpg"
model = "wanx-sketch-to-image-lite"
task = "image2image"

print('----sync call, please wait a moment----')
rsp = ImageSynthesis.call(api_key=os.getenv("DASHSCOPE_API_KEY"),
                          model=model,
                          prompt=prompt,
                          n=1,
                          style='<watercolor>',
                          size='768*768',
                          sketch_image_url=sketch_image_url,
                          task=task)
print('response: %s' % rsp)
if rsp.status_code == HTTPStatus.OK:
    print(rsp.output)
    # save file to current directory
    for result in rsp.output.results:
        file_name = PurePosixPath(unquote(urlparse(result.url).path)).parts[-1]
        with open('./%s' % file_name, 'wb+') as f:
            f.write(requests.get(result.url).content)
else:
    print('sync_call Failed, status_code: %s, code: %s, message: %s' %
          (rsp.status_code, rsp.code, rsp.message))
Response example
{
	"status_code": 200,
	"request_id": "4126d9dd-e037-9f32-8d56-6d29ab3f9a06",
	"code": null,
	"message": "",
	"output": {
		"task_id": "b476bc4e-35c1-4c4e-a4d9-xxxxxxx",
		"task_status": "SUCCEEDED",
		"results": [{
			"url": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxxx.png"
		}],
		"submit_time": "2024-11-01 09:50:56.081",
		"scheduled_time": "2024-11-01 09:50:56.104",
		"end_time": "2024-11-01 09:51:22.740",
		"task_metrics": {
			"TOTAL": 1,
			"SUCCEEDED": 1,
			"FAILED": 0
		}
	},
	"usage": {
		"image_count": 1
	}
}

Java SDK invocation

  • Synchronous call
  • Asynchronous invocation
Request example
// 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 com.alibaba.dashscope.utils.Constants;

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

    public void syncCall() {
        String prompt = "A towering tree";
        String sketchImageUrl = "https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/6609471071/p743851.jpg";
        String model = "wanx-sketch-to-image-lite";
        ImageSynthesisParam param = ImageSynthesisParam.builder()
                .model(model)
                .prompt(prompt)
                .n(1)
                .size("768*768")
                .sketchImageUrl(sketchImageUrl)
                .style("<watercolor>")
                .build();

        String task = "image2image";
        ImageSynthesis imageSynthesis = new ImageSynthesis(task);
        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));
    }

    public static void main(String[] args){
        Main text2Image = new Main();
        text2Image.syncCall();
    }

}
Response example
{
	"request_id": "150edcda-05d5-9ffe-8803-84626d1db623",
	"output": {
		"task_id": "f2098ff0-146e-404c-bb25-xxxxxxxx",
		"task_status": "SUCCEEDED",
		"results": [{
			"url": "https://dashscope-result-hz.oss-cn-hangzhou.aliyuncs.com/xxxx.png"
		}],
		"task_metrics": {
			"TOTAL": 1,
			"SUCCEEDED": 1,
			"FAILED": 0
		}
	},
	"usage": {
		"image_count": 1
	}
}

Error codes

If the model call fails and returns an error message, see Error codes for resolution. This API also has specific status codes, as described in the following table.

HTTP status code

API error code (code)

API error message (message)

Description

400

InvalidURL

The request URL is invalid, please check the request URL is available and the request image format is one of the following types: JPEG, JPG, PNG, BMP, and WEBP.

Failed to download the input image. Check your network connection or the input format.

400

InvalidFile.Resolution

The image resolution is invalid, please make sure that the aspect ratio is smaller than 2.0, and largest length of image is smaller than 4096.

The uploaded image size does not meet the requirements.

FAQ

Model billing and rate limiting

Free quota
  • Description: The free quota applies only to successfully generated output images. Input images or failed model processing do not consume the free quota.
  • How to get: It is automatically granted when you activate Model Studio. Valid for 90 days.
  • Account scope: Shared between your Alibaba Cloud account and its RAM users.
  • For more details, see Free quota for new users.
Limited-time free trial
  • If billing shows a limited-time free trial, the model is in public preview. You cannot use the model after the free quota runs out.
Billing details
  • If a clear unit price is shown — for example, CNY 0.2 per second — the model is commercially available. You must pay after the free quota expires or is fully consumed.
  • Billing scope: Charges apply only to successfully generated output images. Other scenarios are not billed.
  • Billing method: Billing is applied to your Alibaba Cloud account. RAM users cannot be billed independently. Your Alibaba Cloud account must cover all associated charges. To view billing information, go to the Bills page.
  • Recharge: Go to the Expenses and Costs console.
  • View invocation metrics: Go to the Monitoring page.
  • For more billing questions, see Billing Items.
Rate limiting
  • Rate limit scope: Shared between your Alibaba Cloud account and its RAM users.
Text Generation
Video Generation
World models
3D Model Generation
Audio
  • Audio generation
Realtime API
Text Embedding
Decision Model
TokenPlan
Model Production