Footwear model API reference

Related guide: Footwear model

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

AuthorizationstringRequiredUse an Alibaba Cloud Model Studio API key. You can also use a DashScope API key. Example: Bearer d1xxx2a.X-DashScope-AsyncstringRequiredSpecifies whether to use DashScope asynchronous invocation. Because HTTP supports only asynchronous invocation, you must set this parameter to enable.Content-TypestringRequiredThe content type of the request. This must be application/json.

Request body

modelstringRequiredThe model to call. Set this parameter to shoemodel-v1 for the footwear model.parameters IntegerRequiredThe number of images to generate. The value must be an integer from 1 to 4. The default value is 1.inputobjectRequiredBasic information about the input images, such as their URLs.

Properties

template_image_url stringRequiredThe 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 RequiredThe 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 OptionalControls 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.

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

Response

outputobjectInformation about the task output.

Properties

task_id stringThe task ID.task_status stringThe 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.

codestringThe error code for the failed task.messagestringDetailed information about the failed task.request_idstringThe unique request ID. Use this ID for traceability and troubleshooting.

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

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

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

URL path parameters

task_idstringRequiredThe task ID.

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"

Response

outputobjectTask output information.

Properties

task_id stringThe task ID.task_status stringThe 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 objectTask statistics.

Properties

TOTAL integerThe total number of tasks.SUCCEEDED integerThe number of successful tasks.FAILED integerThe number of failed tasks.

submit_time stringThe time the task was submitted.scheduled_time stringThe time the task was scheduled to run.end_time stringThe time the task was completed.results arrayA list of output images. Each element contains a url field, which is the URL of the generated image.codestringThe error code for a failed task.messagestringThe detailed information for a failed task.

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

{
    "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
    }
}

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.

​Model overview

​Prerequisites

​HTTP invocation

​Step 1: Create a task and get the task ID

Headers

Request body

Response

​Step 2: Query the result by task ID

Headers

URL path parameters

Response

​Error codes

Model overview

Prerequisites

HTTP invocation

Step 1: Create a task and get the task ID

Step 2: Query the result by task ID

Error codes