Alibaba AI Docs

Appearance

AI Try-on Plus API reference ​

Aitryon-plus delivers higher image clarity, better fabric texture, and more accurate logos, but takes longer to process.

Important

This document applies only to the China (Beijing) region --- use an API key from that region.

Capabilities ​

Multiple garment try-on

  • Single top try-on: Generates random bottoms or keeps the original.

  • Single bottoms try-on: Generates a random top or keeps the original.

  • Top and bottoms combination: Replaces the entire outfit.

  • Dress/Jumpsuit try-on

Fine-grained control

  • Face: Keep the original or generate a random face.

  • Resolution: Specify output dimensions or use the original.

Overview ​

ModelPriceRate limit (shared by Alibaba Cloud account and RAM users)
Task submission API RPSConcurrent tasks
aitryon-plus$0.071677/image105

Examples ​

Input: Full-body, front-facing person imageInput: Flat-lay garment imageOutput: Generated try-on image
*Flat-lay top image
Flat-lay bottoms image

Input image requirements ​

Before calling the API, ensure images meet these requirements.

Person image requirements ​

RequirementDetails
Image- File size: 5 KB to 5 MB - Resolution: Width and height must each be between 150 and 4096 pixels. - Format: JPG, JPEG, PNG, BMP, and HEIC. - Link: The image must be at a publicly accessible HTTP or HTTPS URL. Local paths are not supported.
Subject- Subject diversity: Supports people of different genders, skin colors, and ages (6 years and older). - Pose: Full-body, front-facing photo with good lighting. Hands must be fully visible. Avoid crossed arms or obstructions. - Subject count: The image must contain only one complete person.

Valid person images ​

Invalid person images ​

Multiple peopleNot a full-body, front-facing photo (Avoid side, sitting, lying, or half-body photos)Obstructed person or garment (Avoid holding objects, bags, etc.)Poor lighting or blurry image

Garment image requirements ​

RequirementDetails
Image- File size: 5 KB to 5 MB - Resolution: Width and height must each be between 150 and 4096 pixels. - Format: JPG, JPEG, PNG, BMP, and HEIC. - Link: The image must be at a publicly accessible HTTP or HTTPS URL. Local paths are not supported.
Garment- Type: Supports single tops, bottoms, and dresses. Also supports suits and top-and-bottom combinations. - Category: Supports common apparel categories. Does not support underwear, wedding dresses, or special ethnic costumes. - Display: \ \ - Single garment: Flat-lay photo with only one garment. \ \ - No folds or obstructions: Spread flat, free of wrinkles. \ \ - Simple, clean background: Uniform color, no complex lighting or shadows. \ \ - Large garment-to-image ratio: Fill the frame. Excessive white space reduces quality.

Valid garment images ​

Top
Bottoms
Dress/Jumpsuit

Invalid garment images ​

Multiple garmentsNot a front-facing photoFolded or obstructedWrinkled garment

Prerequisites ​

Get an API key and set the API key as an environment variable.

HTTP ​

The API uses an asynchronous workflow:

  1. Create task : Submit an image generation request and receive a task_id.

  2. Query result : Poll task status with task_id until complete, then retrieve the result.

Step 1: Create a task ​

Send a POST request to create a try-on task.

HELPCODEESCAPE-http
POST https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis

This model has long processing time, so tasks use asynchronous submission. After creation, the system returns a task_id. Query results within 24 hours.

Request parameters ​

FieldTypeLocationRequiredDescriptionExample
Content-TypeStringHeaderYesRequest type: application/json.application/json
AuthorizationStringHeaderYesAPI key format: Bearer sk-xxxx.Bearer sk-xxxx
X-DashScope-AsyncStringHeaderYesFixed value: enable (asynchronous submission).enable
modelStringBodyYesModel to call.aitryon-plus
input.person_image_urlStringBodyYesPublicly accessible person image URL (or get a temporary URL): - File size: 5 KB to 5 MB - Resolution: 150-4096 pixels (width and height) - Formats: JPG, JPEG, PNG, BMP, HEIC - Must contain exactly one complete person - HTTP/HTTPS URLs only (no local paths) * **Note ** Download reference person images here.http://aaa/1.jpg
input.top_garment_urlStringBodyNoPublicly accessible top or dress garment URL (or get a temporary URL): - File size: 5 KB to 5 MB - Resolution: 150-4096 pixels (width and height) - Formats: JPG, JPEG, PNG, BMP, HEIC - Flat-lay image: only one garment, fully visible, clean background, minimal white space - HTTP/HTTPS URLs only (no local paths) See Garment image requirements for examples. ** **Note ** - Provide at least one of top_garment_url or bottom_garment_url. - If omitted, generates random top. - For dress/jumpsuit, pass URL here and omit bottom_garment_url.http://aaa/2.jpg
input.bottom_garment_urlStringBodyNoPublicly accessible bottoms garment URL (or get a temporary URL): - File size: 5 KB to 5 MB - Resolution: 150-4096 pixels (width and height) - Formats: JPG, JPEG, PNG, BMP, HEIC - Flat-lay image: only one garment, fully visible, clean background, minimal white space - HTTP/HTTPS URLs only (no local paths) See Garment image requirements for examples. ** **Note ** - Provide at least one of top_garment_url or bottom_garment_url. - If omitted, generates random bottoms.http://aaa/3.jpg
parameters.resolutionIntBodyNoThe output image resolution preset. Recommended values: - -1 (default): Same dimensions as the input person image. - 1024: 576x1024 - 1280: 720x1280 ** **Note ** The API may accept other values, but these recommended values provide the best results.-1
parameters.restore_faceBoolBodyNoWhether to preserve the face from the person image. - true (default): Keeps the original face. - false: Generates a new, random face.true

Response parameters ​

FieldTypeDescriptionExample
output.task_idStringUnique ID of async task.a8532587-fa8c-4ef8-82be-0c46b17950d1
output.task_statusStringTask status after submission.PENDING
request_idStringUnique ID of this request.7574ee8f-38a3-4b1e-9280-11c33ab46e51

Request examples ​

Try on a top ​
  • Try on a top : Pass top_garment_url for the top to try on. The AI model randomly generates bottoms.
HELPCODEESCAPE-bash
curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis/' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "aitryon-plus",
    "input": {
        "person_image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250626/ubznva/model_person.png",
        "top_garment_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250626/epousa/short_sleeve.jpeg"
    },
    "parameters": {
        "resolution": -1,
        "restore_face": true
    }
 }'

  • Keep the person's original bottoms: This involves two steps:

    1. Call the OutfitAnyone - Image Segmentation API to get the image URL of the person's bottoms.

    2. Call the try-on API in this topic, passing top_garment_url for the top to try on and bottom_garment_url obtained from segmentation.

HELPCODEESCAPE-bash
curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis/' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "aitryon-plus",
    "input": {
        "person_image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250626/ubznva/model_person.png",
        "top_garment_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250626/epousa/short_sleeve.jpeg",
        "bottom_garment_url": "Image URL from the Image Segmentation API output"
    },
    "parameters": {
        "resolution": -1,
        "restore_face": true
    }
 }'
Try on bottoms ​
  • Try on bottoms : Pass bottom_garment_url for the bottoms to try on. The AI model randomly generates a top.
HELPCODEESCAPE-bash
curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis/' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "aitryon-plus",
    "input": {
        "person_image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250626/ubznva/model_person.png",
        "bottom_garment_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250626/rchumi/pants.jpeg"
    },
    "parameters": {
        "resolution": -1,
        "restore_face": true
    }
}'

  • Keep the person's original top: This involves two steps:

    1. Call the OutfitAnyone - Image Segmentation API to get the image URL of the person's top.

    2. Call the try-on API in this topic, passing top_garment_url obtained from segmentation and bottom_garment_url for the bottoms to try on.

HELPCODEESCAPE-bash
curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis/' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "aitryon-plus",
    "input": {
        "person_image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250626/ubznva/model_person.png",
        "top_garment_url": "Image URL from the Image Segmentation API output",
        "bottom_garment_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250626/rchumi/pants.jpeg"
    },
    "parameters": {
        "resolution": -1,
        "restore_face": true
    }
 }'
Try on a top and bottoms ​

Pass top_garment_url for the top and bottom_garment_url for the bottoms.

HELPCODEESCAPE-bash
curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis/' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "aitryon-plus",
    "input": {
        "person_image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250626/ubznva/model_person.png",
        "top_garment_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250626/epousa/short_sleeve.jpeg",
        "bottom_garment_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250626/rchumi/pants.jpeg"
    },
    "parameters": {
        "resolution": -1,
        "restore_face": true
    }
}'
Try on a dress or jumpsuit ​

For a dress or jumpsuit, pass only top_garment_url.

HELPCODEESCAPE-bash
curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis/' \
--header 'X-DashScope-Async: enable' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "aitryon-plus",
    "input": {
        "person_image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250626/ubznva/model_person.png",
        "top_garment_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250626/odngby/dress.jpg"
    },
    "parameters": {
        "resolution": -1,
        "restore_face": true
    }
}'

Response examples ​

Successful response ​

Save the task_id to query the task status and result.

HELPCODEESCAPE-json
{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}
Error response ​

Task creation failed. See Error messages to resolve the issue.

HELPCODEESCAPE-json
{
    "code": "InvalidApiKey",
    "message": "No API-key provided.",
    "request_id": "7438d53d-6eb8-4596-8835-xxxxxx"
}

Step 2: Query the result by task ID ​

Use the task_id from Step 1 to send a GET request. Replace {task_id} in the URL with actual task ID.

HELPCODEESCAPE-http
GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}

Request parameters ​

FieldTypeLocationRequiredDescriptionExample
AuthorizationStringHeaderYesAPI key format: Bearer sk-xxx.Bearer sk-xxx
task_idStringURL PathYesThe ID of the task to query.a8532587-fa8c-4ef8-82be-0c46b17950d1

Response parameters ​

FieldTypeDescriptionExample
output.task_idStringThe ID of the queried task.a8532587-fa8c-4ef8-82be-0c46b17950d1
output.task_statusStringThe task status. Possible values: - PENDING - PRE-PROCESSING - RUNNING - POST-PROCESSING - SUCCEEDED - FAILED - UNKNOWN: The task does not exist or its status is unknown. - CANCELEDSUCCEEDED
output.image_urlStringGenerated try-on image URL. Valid for 24 hours --- download promptly.https://.../result.jpg?Expires=xxx
output.submit_timeStringTask submission time.2024-07-30 15:39:39.918
output.scheduled_timeStringTask execution start time.2024-07-30 15:39:39.941
output.end_timeStringTask completion time.2024-07-30 15:39:55.080
output.codeStringError code (returned only on failure).InvalidParameter
output.messageStringError details (returned only on failure).The request is missing required parameters or in a wrong format
usage.image_countIntNumber of images generated.1
request_idStringUnique ID of this request.7574ee8f-38a3-4b1e-9280-11c33ab46e51

Request example ​

Replace 86ecf553-d340-4e21-xxxxxxxxx with the actual task ID.

HELPCODEESCAPE-bash
curl -X GET https://dashscope.aliyuncs.com/api/v1/tasks/86ecf553-d340-4e21-xxxxxxxxx \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

Task results are queryable for 24 hours after creation, then automatically purged.

Response examples ​

Successful response ​

Task data is retained for 24 hours, then purged. Download image promptly.

HELPCODEESCAPE-json
{
    "request_id": "98d46cd0-1f90-9231-9a6c-xxxxxx",
    "output": {
        "task_id": "15991992-1487-40d4-ae66-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-06-30 14:37:53.838",
        "scheduled_time": "2025-06-30 14:37:53.858",
        "end_time": "2025-06-30 14:38:11.472",
        "image_url": "http://dashscope-result-hz.oss-cn-hangzhou.aliyuncs.com/tryon.jpg?Expires=xxx"
    },
    "usage": {
        "image_count": 1
    }
}
Failed response ​
HELPCODEESCAPE-json
{
    "request_id": "6bf4693b-c6d0-933a-b7b7-xxxxxx",
    "output": {
        "task_id": "e32bd911-5a3d-4687-bf53-xxxxxx",
        "task_status": "FAILED",
        "code": "InvalidParameter",
        "message": "The request is missing required parameters xxxxx"
    }
}

Error codes ​

For general status codes, see Error messages.

The following error codes are specific to the OutfitAnyone-Plus model:

HTTP return codecodemessageDescription
400InvalidParameterThe request is missing required parameters or has an incorrect format. Check the parameters in your request.A required parameter is missing or the format is incorrect. Verify that the request body conforms to the API specification.
400InvalidParameterDownload the media resource timed out during the data inspection process.The image download timed out. Possible causes and solutions: - Network issue: The network connection between the server and the Alibaba Cloud Model Studio service is unavailable. Check the network connection. - OSS internal URL: The Alibaba Cloud Model Studio service cannot access internal URLs. Use an OSS public URL instead. - Resource outside the Chinese mainland: Cross-border network access is unstable. Use a storage service in the Chinese mainland.
400InvalidURLThe request URL is invalid. Check that the URL is available and the image format is one of the following: JPEG, JPG, PNG, BMP, or WEBP.The image URL is invalid. Verify that the URL is publicly accessible and the image format meets the requirements.
400InvalidPersonThe input image does not contain a person or contains multiple people. Upload an image that contains only one person.The person image does not meet requirements. Ensure the input image contains exactly one complete person.
400InvalidGarmentA garment image is missing. Provide an image for at least a top or bottoms.A garment image is missing. Provide at least one image: a top (top_garment_url) or bottoms (bottom_garment_url).
400InvalidInputLengthThe image resolution is invalid. Make sure that the longest side of the image is less than 4096 pixels, the shortest side is greater than 150 pixels, and the file size is between 5 KB and 5 MB.The image dimensions or file size do not meet the requirements. See the Input image requirements section.

FAQ ​

How to prepare person photos and garment images ​

  1. Why are flat-lay garment images required? Flat-lay images provide the clearest view of a garment's cut, pattern, and silhouette. This helps the AI accurately understand the garment's structure and generate a more fitted, realistic try-on result.

  2. What if I do not have a flat-lay garment image? Place the garment flat on a clean background, such as a floor or wall, and photograph it from above. Alternatively, take a front-facing photo of a person or mannequin wearing the garment. Ensure the garment is fully visible, flat, and not obstructed.

  3. How do I choose a suitable person photo? Choose a clear, front-facing, full-body photo. The person should wear simple, form-fitting clothes, such as a T-shirt and shorts. Avoid long dresses, wide-sleeved robes, or multiple layers. Ensure the person's hands and feet are visible and not blocked by accessories such as bags or umbrellas.

  4. What if I do not have a suitable person photo? Reference person photos that meet the requirements are available for download. Click here to download them.

Unsatisfactory results ​

  1. Why is the generated image low quality or lacking detail? The most common cause is a low-quality input garment image. Ensure the garment image is high resolution and complete. Details should not be lost due to folds or poor camera angles. High-quality input produces high-quality output.

Feature usage ​

  1. How do I generate a try-on image for a dress or jumpsuit? Pass the dress or jumpsuit image URL in the input.top_garment_url field. Leave the input.bottom_garment_url field empty or omit it from the request.

Mirror of Alibaba Cloud Model Studio docs for reference and RAG. Not affiliated with Alibaba Cloud.

Source: alibabacloud.com/help/en/model-studio