鞋靴模特API参考 - 阿里云百炼

相关指南：鞋靴模特

本文档仅适用于华北2（北京）地域，且必须使用该地域的API Key。
shoemodel-v1 模型当前仅提供免费体验，免费额度用完后不可调用且不支持付费。

模型概览

模型名	免费额度（查看）	计费单价	限流（含主账号与RAM子账号）
			任务下发接口QPS限制	同时处理中任务数量
shoemodel-v1	500张	目前仅供免费体验。免费额度用完后不可调用，敬请关注后续动态。	2	1

前提条件

您需要已获取与配置 API Key并配置API Key到环境变量。请将示例代码中的 DASHSCOPE_API_HOST 替换为获取的 API Host。

HTTP调用

为了减少等待时间并且避免请求超时，服务采用异步方式提供。您需要发起两个请求：

创建任务：首先发送一个请求创建鞋靴模特任务，该请求会返回任务ID。
根据任务ID查询结果：使用上一步获得的任务ID，查询模型生成的结果。

步骤1：创建任务获取任务ID

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/virtualmodel/generation 调用时请将{WorkspaceId}替换为真实的业务空间ID。

请求头（Headers）

Authorizationstring必选推荐您使用阿里云百炼API-Key，也可填DashScope API-Key。例如：Bearer d1xxx2a。X-DashScope-Asyncstring必选是否使用DashScope异步调用。HTTP只支持异步调用，设置为enable。Content-Typestring必选请求内容类型。固定为application/json。

请求体（Request Body）

modelstring必选调用模型。鞋靴模特生成模型为shoemodel-v1。parameters Integer必选图片生成的数量，目前支持 1~4 张，默认值 1。inputobject必选输入图像的基本信息，比如图像URL地址。

属性

template_image_url string必选模板模特图片的URL地址。URL 需为公网可访问的地址，并支持 HTTP 或 HTTPS 协议。您也可在此获取临时公网URL。图像限制：

图片大小建议小于5M。
图像格式：jpg、png、jpeg、bmp、webp、avif。
图像比例：图长边与短边的比例需在[2:3, 3:2] 范围内，推荐比例为4:3。

shoe_image_url list 必选鞋靴多视角图片URL地址。URL 需为公网可访问的地址，并支持 HTTP 或 HTTPS 协议。您也可在此获取临时公网URL。

图片大小建议小于5M。
图像格式：jpg、png、jpeg、bmp、webp、avif。
图像比例：图长边与短边的比例需在[2:3, 3:2] 范围内，推荐与模特模板一样，比例为4:3。
多视角图片张数小于3。

scale float 可选控制生成强度。范围在[2.0,8.0]，默认为5.0，数值越大，颜色越鲜亮。

鞋靴模特试穿

curl --location 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/virtualmodel/generation' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "shoemodel-v1",
    "input": {
        "template_image_url": "https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/8268778171/p809310.webp",
        "shoe_image_url": ["https://help-static-aliyun-doc.aliyuncs.com/assets/img/zh-CN/8268778171/p809301.webp"]
    },
    "parameters":
    {
        "n": 1
    }
}'

响应

outputobject任务输出信息。

属性

task_id string任务id。task_status string任务状态。

PENDING：排队中
RUNNING：处理中
SUSPENDED：挂起
SUCCEEDED：执行成功
FAILED：执行失败

codestring任务执行失败的错误码。messagestring任务执行失败的详细信息。request_idstring请求唯一标识。可用于请求明细溯源和问题排查。

{
    "output": {
	"task_id": "d76ec1e8-ea27-4038-8913-xxxxxxxxxxxx",
        "task_status": "PENDING"
    }
    "request_id": "7574ee8f-38a3-4b1e-9280-11c33ab46e51"
}

步骤2：根据任务ID查询结果

GET https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id} 调用时请将{WorkspaceId}替换为真实的业务空间ID。

请求头（Headers）

Authorizationstring必选推荐使用阿里云百炼API-Key，也可填DashScope API-Key。例如：Bearer d1xxx2a。

URL路径参数（Path parameters）

task_idstring必选任务id。

获取任务结果

curl --location --request GET 'https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/tasks/{task_id}' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

响应

outputobject任务输出信息。

属性

task_id string任务id。task_status string任务状态。

PENDING：排队中
RUNNING：处理中
SUSPENDED：挂起
SUCCEEDED：执行成功
FAILED：执行失败

task_metrics object任务信息统计指标。

属性

TOTAL integer总的任务数。SUCCEEDED integer任务状态为成功的任务数。FAILED integer任务状态为失败的任务数。

submit_time string任务提交时间。scheduled_time string任务排期执行时间。end_time string任务完成时间。results array输出图片列表。每个元素包含一个url字段，表示生成图片的URL。codestring任务执行失败的错误码。messagestring任务执行失败的详细信息。

request_idstring请求唯一标识。可用于请求明细溯源和问题排查。

{
    "request_id":"<your request id>",
    "output":{
        "task_id":"<your task id>",
        "task_status":"SUCCEEDED",
        "submit_time":"2024-05-16 13:50:xx.xxx",
        "scheduled_time":"2024-05-16 13:50:xx.xxx",
        "end_time":"2024-05-16 13:50:xx.xxx",
        "results":[
            {
                "url":"https://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxx/res_img.png?Expires=xxx&OSSAccessKeyId=YOUR_ACCESS_KEY_ID&Signature=YOUR_SIGNATURE"
            }
        ],
        "task_metrics":{
            "TOTAL":1,
            "SUCCEEDED":1,
            "FAILED":0
        }
    },
    "usage":{
        "image_count":1
    }
}

错误码

如果模型调用失败并返回报错信息，请参见错误码进行解决。此API还有特定状态码，具体如下所示。

HTTP状态码	接口错误码（code）	接口错误信息（message）	含义说明
400	InvalidParameter	Required parameter(s) missing or invalid, please check the request parameters.（可根据实际情况修改）	接口调用参数不合法
400	InvalidFile.Content	The input image has no human body or has unclear human body. Please upload other image.	输入图片中人体不完整或者没有人体
400	InvalidParameter	The request is missing required parameters or in a wrong format, please check the parameters that you send.	入参格式不对
400	InvalidParameter.DataInspection	Unable to download the media resource during the data inspection process.	数据检查过程中无法下载媒体资源，请检查输入URL是否可访问以及图片格式是否正确
400	InvalidFile.Resolution	The image resolution is invalid, please make sure that the aspect ratio is smaller than 3:2, and largest length of image is smaller than 4096.	上传图片大小不符合要求
500	InternalError.Algo	An internal error occurs during computation, please try this model later.	算法运行错误

​模型概览

​前提条件

​HTTP调用

​步骤1：创建任务获取任务ID

请求头（Headers）

请求体（Request Body）

响应

​步骤2：根据任务ID查询结果

请求头（Headers）

URL路径参数（Path parameters）

响应

​错误码

模型概览

前提条件

HTTP调用

步骤1：创建任务获取任务ID

步骤2：根据任务ID查询结果

错误码