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

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 | 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 |
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:
- Create a task to get a task ID: Send a request to create a task. The response returns a task ID (
task_id). - 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.
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 parametersRequest headersContent-Typestring (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.X-DashScope-WorkSpace string (Optional)The ID of the Model Studio workspace. Example: llm-xxxx.You can get the Workspace ID.
Details Set this parameter to your Model Studio API key.
For details about Alibaba Cloud accounts and RAM users, see Manage account. Request bodymodelstring(required)The model to invoke.inputobject(required)Basic input information, such as the prompt and image URL.
Properties prompt string(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:
![]() object(optional)Image editing parameters.
Properties style string(optional)The style of the output image. The following values are supported:
string(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]] |
|
Response parametersoutputobjectTask output information.
Properties task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.
Enumeration values
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. |
Save the task_id to query the task status and result. |
Step 2: Query the result by task ID
GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}
Request parametersHeadersAuthorizationstring (Required)Authenticates the request with a Model Studio API key. Example: Bearer sk-xxxx.Path parameterstask_idstring (Required)The ID of the task. |
Replace 86ecf553-d340-4e21-xxxxxxxxx with your actual task_id.If you use a model in the Singapore region, replace |
Response parametersoutputobjectThe task output.
Properties task_id stringThe task ID. Valid for queries for 24 hours.task_status stringThe status of the task.
Enumeration values
objectStatistics for the task result.
Properties TOTAL integerThe total number of tasks.SUCCEEDED integerThe number of successful tasks.FAILED integerThe number of failed tasks.array of objectThe list of task results, including image URLs, error messages in case of partial task failure.
Structure stringError code. Returned only for failed requests. See Error codes.message stringDetailed error message. Returned only for failed requests. See Error codes.objectThe output statistics. Only successful results are counted.
Properties image_count integerNumber of images successfully generated. Billing: Cost = Number of images × Unit price.stringUnique request identifier for tracing and troubleshooting. |
Task data (task status and image URLs) is retained for only 24 hours and then automatically purged. Save generated images promptly. |
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
Response example
Java SDK invocation
- Synchronous call
- Asynchronous invocation
Request example
Response example
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.
- 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.
- 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 limit scope: Shared between your Alibaba Cloud account and its RAM users.
