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.
Model overview
Example output
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 can take a long time to process. HTTP calls support only asynchronous result retrieval to prevent request timeouts. This requires two requests:
Create a task to obtain a task ID: Sends a request to create a task. Returns a task ID (
task_id) in the response.Query the result by task ID: Uses the task ID from the previous step to query the task status and result. Returns an image URL (valid for 24 hours) if the task succeeds.
After creating a task, it is added to a queue to await scheduling. Call the "Query the result by task ID" API to retrieve the task status and result.
Step 1: Create a task and get the task ID
POST https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis/
Request parameters |
curl |
Request headers |
|
|
Content-Type The content type of the request. Must be |
|
|
Authorization The authentication credentials using a Model Studio API key. Example: |
|
|
X-DashScope-Async Enables asynchronous processing. Must be Important Returns "current user api does not support synchronous calls" error if not included. |
|
|
X-DashScope-WorkSpace The ID of the Model Studio workspace. Example: You can get a Workspace ID. |
|
Request body |
|
|
model The model to invoke. |
|
|
input Basic input information, such as the prompt and image URL. prompt 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_url 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 the HTTP or HTTPS protocol. You can also obtain a temporary public URL. Image limits:
Sketch example:
|
|
|
parameters Image editing parameters. |
Response parameters |
Successful responseSave the Error responseTask creation failed. See error codes to resolve the issue. |
|
output Task output information. |
|
|
request_id Unique identifier for the request. Use for tracing and troubleshooting issues. |
|
|
code The error code. Returned only when the request fails. See error codes for details. |
|
|
message Detailed error message. Returned only when the request fails. See error codes for details. |
Step 2: Query the result by task ID
GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}
Request parameters | Query task resultsReplace For models in the Singapore region, replace base_url with |
Headers | |
Authorization The authentication credentials using a Model Studio API key. Example: | |
Path parameters | |
task_id The ID of the task to query. |
Response parameters | Success responseTask data (task status and image URLs) is retained for only 24 hours and then automatically purged. Save generated images promptly. Failure responseWhen a task fails, Partial failure responseThe model can generate multiple images in a single task. If at least one image generates successfully, the task status is marked as |
output The task output. | |
usage The output statistics. Only successful results are counted. | |
request_id Unique identifier for the request. Use for tracing and troubleshooting issues. |
DashScope SDK invocation
Ensure you have installed the latest version of the DashScope SDK. See SDK installation.
The DashScope SDK supports Python and Java.
Parameter names in the SDK are mostly the same as in the HTTP API. However, parameter structure varies by SDK encapsulation for each programming language. See the HTTP call section for parameter details.
Because image models can take a long time to process, the underlying service is asynchronous. The SDK provides a higher-level encapsulation supporting both synchronous and asynchronous calls.
Python SDK invocation
Synchronous call
Request example
from http import HTTPStatus
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath
import requests
from dashscope import ImageSynthesis
import os
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
}
}
Asynchronous invocation
Request example
from http import HTTPStatus
from urllib.parse import urlparse, unquote
from pathlib import PurePosixPath
import requests
from dashscope import ImageSynthesis
import os
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"
# Asynchronous invocation
def async_call():
print('----create task----')
task_info = create_async_task()
print('----wait task done then save image----')
wait_async_task(task_info)
# Create an asynchronous task
def create_async_task():
rsp = ImageSynthesis.async_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(rsp)
if rsp.status_code == HTTPStatus.OK:
print(rsp.output)
else:
print('create_async_task Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
return rsp
# Wait for the asynchronous task to complete
def wait_async_task(task):
rsp = ImageSynthesis.wait(task)
print(rsp)
if rsp.status_code == HTTPStatus.OK:
print(rsp.output.task_status)
# 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('Failed, status_code: %s, code: %s, message: %s' %
(rsp.status_code, rsp.code, rsp.message))
if __name__ == '__main__':
async_call()Response example
1. Example response for creating a task
{
"status_code": 200,
"request_id": "31b04171-011c-96bd-ac00-f0383b669cc7",
"code": "",
"message": "",
"output": {
"task_id": "4f90cf14-a34e-4eae-xxxxxxxx",
"task_status": "PENDING",
"results": []
},
"usage": null
}2. Example response for querying the task result
{
"status_code": 200,
"request_id": "d861d3ba-4b29-9491-abad-266ef4fb2f08",
"code": null,
"message": "",
"output": {
"task_id": "4f90cf14-a34e-4eae-xxxxxxxx",
"task_status": "SUCCEEDED",
"results": [{
"url": "https://dashscope-result-hz.oss-cn-hangzhou.aliyuncs.com/xxxx.png"
}],
"submit_time": "2024-10-31 20:40:35.631",
"scheduled_time": "2024-10-31 20:40:35.684",
"end_time": "2024-10-31 20:41:02.700",
"task_metrics": {
"TOTAL": 1,
"SUCCEEDED": 1,
"FAILED": 0
}
},
"usage": {
"image_count": 1
}
}Java SDK invocation
Synchronous call
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;
public class Main {
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
}
}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;
public class Main {
public void asyncCall() {
System.out.println("---create task----");
String taskId = this.createAsyncTask();
System.out.println("---wait task done then return image url----");
this.waitAsyncTask(taskId);
}
/**
* Create an asynchronous task
* @return taskId
*/
public String createAsyncTask() {
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 {
result = imageSynthesis.asyncCall(param);
} catch (Exception e){
throw new RuntimeException(e.getMessage());
}
String taskId = result.getOutput().getTaskId();
System.out.println("taskId=" + taskId);
return taskId;
}
/**
* Wait for the asynchronous task to complete
* @param taskId The task ID
* */
public void waitAsyncTask(String taskId) {
ImageSynthesis imageSynthesis = new ImageSynthesis();
ImageSynthesisResult result = null;
try {
// If you have set the DASHSCOPE_API_KEY in the system environment variable, the apiKey can be null.
result = imageSynthesis.wait(taskId, null);
} catch (ApiException | NoApiKeyException e){
throw new RuntimeException(e.getMessage());
}
System.out.println(JsonUtils.toJson(result.getOutput()));
System.out.println(JsonUtils.toJson(result.getUsage()));
}
public static void main(String[] args){
Main text2Image = new Main();
text2Image.asyncCall();
}
}Response example
1. Example response for creating a task and getting the task ID
{
"request_id": "5dbf9dc5-4f4c-9605-85ea-542f97709ba8",
"output": {
"task_id": "7277e20e-aa01-4709-xxxxxxxx",
"task_status": "PENDING"
}
}2. Example response for querying the task result by task ID
{
"request_id": "c44213ba-7aa3-91e4-97c1-c527ade82597",
"output": {
"task_id": "7277e20e-aa01-4709-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 messages 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.