本文介绍万相-涂鸦作画模型的API输入输出参数。
相关指南:涂鸦作画
模型效果示意
模型简介
模型说明
更多说明请参见模型计费及限流。
涂鸦作画API支持通过HTTP和DashScope SDK进行调用。
在调用前,您需要获取与配置 API Key,再配置API Key到环境变量。
如需通过SDK进行调用,请安装DashScope SDK。目前,该SDK已支持Python和Java。
图像模型处理时间较长,为了避免请求超时,HTTP调用仅支持异步获取模型结果。您需要发起两个请求:
请先确认已安装最新版DashScope SDK:安装SDK。
DashScope SDK目前已支持Python和Java。
SDK与HTTP接口的参数名基本一致,参数结构根据不同语言的SDK封装而定。参数说明可参考HTTP调用。
由于图像模型处理时间较长,底层服务采用异步方式提供。SDK在上层进行了封装,支持同步、异步两种调用方式。
如果模型调用失败并返回报错信息,请参见错误码进行解决。
此API还有特定状态码,具体如下所示。
免费额度
模型概览
模型效果示意

模型名称 | 模型简介 |
|---|---|
wanx-sketch-to-image-lite | 万相-涂鸦作画通过手绘图案和文字描述,生成精美的涂鸦绘画作品。 |
模型名称 | 计费单价 | 限流(主账号与RAM子账号共用) | 免费额度(查看) | |
|---|---|---|---|---|
任务下发接口QPS限制 | 同时处理中任务数量 | |||
wanx-sketch-to-image-lite | 0.06元/张 | 2 | 1 | 500张 |
前提条件
涂鸦作画API支持通过HTTP和DashScope SDK进行调用。
在调用前,您需要获取与配置 API Key,再配置API Key到环境变量。
如需通过SDK进行调用,请安装DashScope SDK。目前,该SDK已支持Python和Java。
请将示例代码中的 DASHSCOPE_API_HOST 替换为获取的 API Host。
HTTP调用
图像模型处理时间较长,为了避免请求超时,HTTP调用仅支持异步获取模型结果。您需要发起两个请求:
- 创建任务获取任务ID:首先发起创建任务请求,该请求会返回任务ID(task_id)。
- 根据任务ID查询结果:使用上一步获得的任务ID,查询任务状态及结果。任务成功执行时将返回图像URL,有效期24小时。
创建任务后,该任务将被加入到排队队列,等待调度执行。后续需要调用“根据任务ID查询结果接口”获取任务状态及结果。
步骤1:创建任务获取任务ID
POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis
请求参数请求头(Headers)Content-Typestring(必选)请求内容类型。此参数必须设置为application/json。Authorizationstring(必选)请求身份认证。接口使用阿里云百炼API Key进行身份认证。示例值:Bearer sk-xxxx。X-DashScope-Asyncstring(必选)异步处理配置参数。HTTP请求只支持异步,必须设置为enable。X-DashScope-WorkSpacestring(可选)阿里云百炼业务空间ID。示例值:llm-xxxx。您可以在此获取Workspace ID。
详细说明 此参数根据阿里云百炼API Key进行填写。
关于如何区分阿里云百炼主账号和RAM子账号,请参考主账号管理。 请求体(Request Body)modelstring(必选)调用模型。inputobject(必选)输入的基本信息,比如提示词、图像URL地址。
属性 prompt string(必选)提示词,用来描述生成图像中期望包含的元素和视觉特点。支持中英文,长度不超过75个字符,超过部分会自动截断。示例值:一棵参天大树。sketch_image_urlstring(必选)输入草图的URL地址。输入草图需要与输出图像的分辨率比例保持一致,否则会导致图片拉伸变形,建议使用白色背景图。URL 需为公网可访问的地址,并支持 HTTP 或 HTTPS 协议。您也可在此获取临时公网URL。图像限制:
![]() object(可选)图像处理参数。
属性 style string(可选)输出图像的风格,目前支持以下风格取值:
string(可选)输出图像的分辨率。目前仅支持一种图像分辨率:768*768,且为默认值。ninteger(可选)生成图片的数量。取值范围为1~4张,默认为4。sketch_weightinteger(可选)输入草图对输出图像的约束程度。取值范围为0-10,取值间隔为1, 默认值为10。取值越大表示输出图像跟输入草图越相似。sketch_extractionboolean(可选)如果上传图片是RGB图片,而非草图(sketch线稿),此参数可控制是否对输入图片进行sketch边缘提取。默认值为False,表示不进行提取。设置为True时,表示进行提取,此时,sketch_color字段失效。sketch_colorarray(可选)此字段在sketch_extraction=false时生效,所包含数值均被视为画笔色,其余数值均会视为背景色。模型会基于一种或多种画笔色描绘的区域生成新的画作。默认值为[]。当sketch_image_url线稿中的线条不是黑色,而是包含其他一种或多种颜色时,可以指定一个或多个RGB颜色数值作为画笔色。示例值:[[134, 134, 134], [0, 0, 0]] |
|
响应参数outputobject任务输出信息。
属性 task_id string任务ID。查询有效期24小时。task_status string任务状态。
枚举值
string请求唯一标识。可用于请求明细溯源和问题排查。codestring请求失败的错误码。请求成功时不会返回此参数,详情请参见错误码。messagestring请求失败的详细信息。请求成功时不会返回此参数,详情请参见错误码。 |
请保存 task_id,用于查询任务状态与结果。 |
步骤2:根据任务ID查询结果
GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}
请求参数请求头(Headers)Authorizationstring(必选)请求身份认证。接口使用阿里云百炼API Key进行身份认证。示例值:Bearer sk-xxxx。URL路径参数(Path parameters)task_idstring(必选)任务ID。 |
请将 86ecf553-d340-4e21-xxxxxxxxx替换为真实的task_id。若使用新加坡地域的模型,需将base_url替换为https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx,其中{WorkspaceId}需替换为真实的业务空间ID。 |
响应参数outputobject任务输出信息。
属性 task_id string任务ID。查询有效期24小时。task_status string任务状态。
枚举值
object任务结果统计。
属性 TOTAL integer总的任务数。SUCCEEDED integer任务状态为成功的任务数。FAILED integer任务状态为失败的任务数。array of object任务结果列表,包括图像URL、部分任务执行失败报错信息等。
数据结构 string请求失败的错误码。请求成功时不会返回此参数,详情请参见错误码。messagestring请求失败的详细信息。请求成功时不会返回此参数,详情请参见错误码。object输出信息统计。只对成功的结果计数。
属性 image_count integer模型成功生成图片的数量。计费公式:费用 = 图片数量 × 单价。string请求唯一标识。可用于请求明细溯源和问题排查。 |
任务数据(如任务状态、图像URL等)仅保留24小时,超时后会被自动清除。请您务必及时保存生成的图像。 |
DashScope SDK调用
请先确认已安装最新版DashScope SDK:安装SDK。
DashScope SDK目前已支持Python和Java。
SDK与HTTP接口的参数名基本一致,参数结构根据不同语言的SDK封装而定。参数说明可参考HTTP调用。
由于图像模型处理时间较长,底层服务采用异步方式提供。SDK在上层进行了封装,支持同步、异步两种调用方式。
Python SDK调用
- 同步调用
- 异步调用
请求示例
响应示例
Java SDK调用
- 同步调用
- 异步调用
请求示例
响应示例
错误码
如果模型调用失败并返回报错信息,请参见错误码进行解决。
此API还有特定状态码,具体如下所示。
HTTP状态码 | 接口错误码(code) | 接口错误信息(message) | 含义说明 |
|---|---|---|---|
400 | InvalidParameter.DataInspection | Unable to download the media resource during the data inspection process. | 输入图片无法下载,请检查URL地址是否正确且可访问。 |
400 | InvalidParameter | Value error, format of image {url} is not valid : payload.input.sketch | 输入图片格式不合法,请确认图片格式为JPG、JPEG、PNG、TIFF或WEBP。 |
常见问题
模型计费及限流
免费额度
- 额度说明:免费额度是指模型成功生成的输出图片数量。输入图片及模型处理失败的情况不占用免费额度。
- 领取方式:开通阿里云百炼大模型服务后自动发放,有效期90天。
- 使用账号:阿里云主账号与其RAM子账号共享免费额度。
- 更多详情请参见新人免费额度。
- 当计费为限时免费时,表示该模型处于公测阶段,免费额度用尽后不可使用。
- 当计费有明确单价时,如0.2元/秒,表示该模型已商业化,免费额度用尽或过期后需付费使用。
- 计费项:只对模型成功生成的输出图片进行收费,其余情况暂不计费。
- 付费方式:由阿里云主账号统一付费。RAM子账号不能独立计量计费,必须由所属的主账号付费。如果您需要查询账单信息,请前往阿里云控制台账单概览。
- 充值途径:您可以在阿里云控制台费用与成本页面进行充值。
- 模型调用情况:您可以前往阿里云百炼的模型观测查看模型调用量及调用次数。
- 更多计费问题请参见计费项。
- 限流说明:阿里云主账号与其RAM子账号共享限流限制。
