DocsICP FilingConsole
官方文档
首页

Footwear model API reference

更新时间：
复制 MD 格式
产品详情
我的收藏

This topic describes the input and output parameters of the footwear model. The footwear model takes a series of multi-angle images of footwear as input, applies an AI try-on to the shoe area of a model template image, and reconstructs the footwear layout on the model to generate a final image with a natural layout, rich details, high fidelity, and realistic try-on results. This model is suitable for scenarios such as creating product images with models, generating AI try-ons for new footwear, and adjusting the footwear layout on a model.

Related guide: Footwear model

Important

  • This document applies only to the Chinese mainland (Beijing) region. Use an API key from this region.

  • The shoemodel-v1 model is currently available for a free trial only. After the free quota is used, you can no longer call the model, and payment is not supported.

Model overview

Model name

Free quota(View)

Billing unit price

Rate limiting (for Alibaba Cloud accounts and RAM users)

QPS limit for task submission API

Number of concurrent tasks

shoemodel-v1

500 images

For free trial only.

You cannot make calls after the free quota is used up. Please stay tuned for future updates.

2

1

Prerequisites

Obtain an API key and export the API key as an environment variable.

HTTP invocation

To reduce wait times and prevent request timeouts, this service is provided asynchronously. You must make two requests:

  • Create a task: Send a request to create a footwear model task. The response returns a task ID.

  • Query the result by task ID: Use the task ID from the previous step to retrieve the model's generation result.

Step 1: Create a task and get the task ID

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/aigc/virtualmodel/generation

Replace {WorkspaceId} with your actual workspace ID.

Headers

Footwear model try-on

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
    }
}'

Authorization string Required

Use an Alibaba Cloud Model Studio API key. You can also use a DashScope API key. Example: Bearer d1xxx2a.

X-DashScope-Async string Required

Specifies whether to use DashScope asynchronous invocation. Because HTTP supports only asynchronous invocation, you must set this parameter to enable.

Content-Type string Required

The content type of the request. This must be application/json.

Request body

model string Required

The model to call. Set this parameter to shoemodel-v1 for the footwear model.

parameters Integer Required

The number of images to generate. The value must be an integer from 1 to 4. The default value is 1.

input object Required

Basic information about the input images, such as their URLs.

Properties

template_image_url string Required

The URL of the model template image.

The URL must be publicly accessible and use HTTP or HTTPS.You can also obtain a temporary public URL.

Image requirements:

  • Image size: Less than 5 MB.

  • Image format: JPG, PNG, JPEG, BMP, WebP, or AVIF.

  • Image aspect ratio: The aspect ratio must be in the range of [2:3, 3:2]. A ratio of 4:3 is recommended.

shoe_image_url list Required

The URLs of the multi-view footwear images.

The URL must be publicly accessible and use HTTP or HTTPS.You can also obtain a temporary public URL.

  • Image size: Less than 5 MB.

  • Image format: JPG, PNG, JPEG, BMP, WebP, or AVIF.

  • Aspect ratio: The ratio of the longer side to the shorter side must be in the [2:3, 3:2] range. A 4:3 ratio is recommended to match the model template.

  • You can provide a maximum of two multi-view images.

scale float Optional

Controls the generation intensity.

The value must be in the range of [2.0, 8.0]. The default value is 5.0. A larger value produces more vibrant colors.

Response

Normal response

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

Abnormal response

{
    "code":"InvalidApiKey",
    "message":"Invalid API-key provided.",
    "request_id":"fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1"
}

output object

Information about the task output.

Properties

task_id string

The task ID.

task_status string

The task status.

  • PENDING: The task is in the queue.

  • RUNNING: The task is being processed.

  • SUSPENDED: The task is suspended.

  • SUCCEEDED: The task was successful.

  • FAILED: The task failed.

code string

The error code for the failed task.

message string

Detailed information about the failed task.

request_id string

The unique request ID. Use this ID for traceability and troubleshooting.

Step 2: Query the result by task ID

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

Replace {WorkspaceId} with your actual workspace ID.

Headers

Get task result

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

Authorization string Required

Use an Alibaba Cloud Model Studio API key. You can also use a DashScope API key. Example: Bearer d1xxx2a.

URL path parameters

task_id string Required

The task ID.

Response

Task successful

{
    "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=xxx&Signature=xxx"
            }
        ],
        "task_metrics":{
            "TOTAL":1,
            "SUCCEEDED":1,
            "FAILED":0
        }
    },
    "usage":{
        "image_count":1
    }
}

Task running

{
    "request_id":"e5d70b02-ebd3-98ce-9fe8-759d7d7b107d",
    "output":{
        "task_id":"86ecf553-d340-4e21-af6e-a0c6a421c010",
        "task_status":"RUNNING",
        "task_metrics":{
            "TOTAL":1,
            "SUCCEEDED":1,
            "FAILED":0
        }
    }
}

Task failed

{
  "request_id": "<your request id>",
  "output": {
    "task_id": "<your task id>",
    "task_status": "FAILED",
    "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",
    "code": "InvalidImageResolution",
    "message": "The input image resolution is too large or small"
  },
  "usage": {
    "image_num": 0
  }
}

output object

Task output information.

Properties

task_id string

The task ID.

task_status string

The task status.

  • PENDING: The task is in the queue.

  • RUNNING: The task is being processed.

  • SUSPENDED: Suspended

  • SUCCEEDED: The task was successful.

  • FAILED: The task failed.

task_metrics object

Task statistics.

Properties

TOTAL integer

The total number of tasks.

SUCCEEDED integer

The number of successful tasks.

FAILED integer

The number of failed tasks.

submit_time string

The time the task was submitted.

scheduled_time string

The time the task was scheduled to run.

end_time string

The time the task was completed.

results array

A list of output images. Each element contains a url field, which is the URL of the generated image.

code string

The error code for a failed task.

message string

The detailed information for a failed task.

request_id string

The unique request ID. Use this ID for traceability and troubleshooting.

Error codes

If the model call fails and returns an error message, see Error codes for resolution.

The following table describes the specific status codes for this API.

HTTP status code

API error code (code)

API error message (message)

Description

400

InvalidParameter

Required parameter(s) missing or invalid, please check the request parameters.

The API call parameters are invalid.

400

InvalidFile.Content

The input image does not contain a human body or the human body is unclear. Upload a different image.

The input image contains an incomplete human body or no human body.

400

InvalidParameter

The request is missing required parameters or is in the wrong format. Check the parameters that you sent.

The format of the request parameters is incorrect.

400

InvalidParameter.DataInspection

Unable to download the media resource during the data inspection process.

Failed to download the media resource during data inspection. Check if the input URL is accessible and the image format is correct.

400

InvalidFile.Resolution

The image resolution is invalid. Make sure that the aspect ratio is less than 3:2 and the longest side of the image is less than 4096 pixels.

The uploaded image size does not meet the requirements.

500

InternalError.Algo

An internal error occurred during computation. Try this model again later.

An algorithm execution error occurred.

Previous：Virtual ModelNext：Creative poster generation