{"templateId":"openapi_docs","sharedDataIds":{"openAPIDocsStore":"oas-reference/ai_bag.yaml","sidebar":"sidebar-reference/sidebars.yaml"},"props":{"definitionId":"reference/ai_bag.yaml","dynamicMarkdocComponents":[],"baseSlug":"/reference/ai_bag","seo":{"title":"AI Bag Virtual Try-On","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"itemId":"","disableAutoScroll":true,"metadata":{"type":"openapi","title":"AI Bag Virtual Try-On","description":"# Overview\nAR makes luxury bag shopping a tangible experience! AR tech empowers brands to showcase handbags with unmatched realism. From strap length to bag pairing, customers can visualize products instantly through camera.\n\n## Integration Guide\nThis guide walks you through:\n\n* **Endpoint:** `/s2s/v2.0/file/bag`\n* **Authentication:** All requests require an `Authorization: Bearer YOUR_API_KEY`\n* **Workflow:**\n 1. **Prepare a selfie image:** Uploading an image or providing a valid image URL of yourself as the virtual try-on target.\n 1. **Prepare a bag image:** Uploading an image or providing a valid image URL of a bag product or a person carrying a bag without any obstruction.\n 1. **Select a style and a gender:** Select a preferred style and the gender you wish to visualize.\n 1. **Fire an AI task and Retrieve Task ID:** Capture the `task_id` from the response.\n 1. **Poll Status (`GET`):** Use the `task_id` to check the status of the task. Continue polling until `task_status` is `\"success\"` or `\"error\"`.\n\n---\n\n* Authentication\n- Include your API key in the request header using **Bearer Token**:\n```\nAuthorization: Bearer YOUR_API_KEY\n```\nYou can find your API Key at https://yce.makeupar.com/api-console/en/api-keys/.\n\n---\n\n* AI Bag API Usage Guide\n\nThis guide explains how to upload images, prepare reference bags, and create virtual try-on tasks using the AI Bag API.\n\n***\n\n * Step 1. Upload a File Using the File API\n\nUse the **File API** (`/s2s/v2.0/file/bag`) to upload a target user image.\n\n**Image Requirements:**\n\n* Upload a selfie photo.\n* Ensure the photo clearly shows the upper body.\n* Avoid backgrounds with multiple people or distracting objects.\n\n**Example Request:**\n\n```bash\ncurl --request POST \\\n --url https://yce-api-01.makeupar.com/s2s/v2.0/file/bag \\\n --header 'Authorization: Bearer YOUR_API_KEY' \\\n --header 'content-type: application/json' \\\n --data '{\n \"files\": [\n {\n \"content_type\": \"image/jpg\",\n \"file_name\": \"selfie_photo_01_3dbd1b6683.jpg\",\n \"file_size\": 547541\n }\n ]\n }'\n```\n\n***\n\n * Step 2. Retrieve File API Response\n\nThe response includes:\n\n* `file_id` for creating an AI task.\n* `requests.url` for uploading the actual image file.\n\n**Sample Response:**\n\n```json\n{\n \"status\": 200,\n \"data\": {\n \"files\": [\n {\n \"content_type\": \"image/jpg\",\n \"file_name\": \"selfie_photo_01_3dbd1b6683.jpg\",\n \"file_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud\",\n \"requests\": [\n {\n \"method\": \"PUT\",\n \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\",\n \"headers\": {\n \"Content-Length\": \"547541\",\n \"Content-Type\": \"image/jpg\"\n }\n }\n ]\n }\n ]\n }\n}\n```\n\n***\n\n * Step 3. Upload Image to Provided URL\n\nUse the `requests.url` from the File API response to upload the image:\n\n```bash\ncurl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \\\n --header 'Content-Type: image/jpg' \\\n --header 'Content-Length: 547541' \\\n --data-binary @'./selfie_photo_01_3dbd1b6683.jpg'\n```\n\n***\n\n * Step 4. Prepare a Reference Bag Image\n\nYou can:\n\n* Upload a bag image using the File API (`/s2s/v2.0/file/bag`), or\n* Provide a valid image URL.\n\n**Supported Bag Images:**\n\n* Product image of the bag.\n* A person carrying a bag without any obstruction as a bag reference.\n\nRefer to **[File Specs and Errors](#section/overview/File-Specs-and-Errors)** for detailed specifications.\n\n***\n\n * Step 5. Create an AI Task\n\nSelect a preferred style and the gender you wish to visualize.\nUse the **AI Task API** (`/s2s/v2.0/task/bag`) to create a virtual try-on task.\n\n**Parameters:**\n\n* For the user image: `src_file_id` or `src_file_url`.\n* For the bag image: `ref_file_id`, or `ref_file_url`.\n\n**Example Request:**\n\n```bash\ncurl --request POST \\\n --url https://yce-api-01.makeupar.com/s2s/v2.0/task/bag \\\n --header 'Authorization: Bearer YOUR_API_KEY' \\\n --header 'content-type: application/json' \\\n --data '{\n \"src_file_url\": \"https://example.com/selfie.jpg\",\n \"ref_file_url\": \"https://example.com/accessory.jpg\",\n \"gender\": \"female\",\n \"style\": \"random\"\n}'\n```\n\n**Sample Response:**\n\n```json\n{\n \"status\": 200,\n \"data\": {\n \"task_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT\"\n }\n}\n```\n\n***\n\n * Step 6. Poll for Task Result\n\nUse the task ID to check the status:\n\n```bash\ncurl --request GET \\\n --url https://yce-api-01.makeupar.com/s2s/v2.0/task/bag/SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT \\\n --header 'Authorization: Bearer YOUR_API_KEY' \\\n --header 'content-type: application/json'\n```\n\n***\n\n * Step 7. Retrieve Result\n\nA successful response includes a download URL for the result image:\n\n```json\n{\n \"status\": 200,\n \"data\": {\n \"error\": null,\n \"results\": {\n \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\"\n },\n \"task_status\": \"success\"\n }\n}\n```\n\nInvalid API Key error response:\n\n```json\n{\n \"status\": 401,\n \"error\": \"Unauthorized\",\n \"error_code\": \"InvalidAccessToken\"\n}\n```\n\n---\n\n## File Specs & Errors\n\n* AI Bag Virtual Try-On Specification\n\n**Supported Bag Image**\n\n* Product Image Requirements\n * Minimum resolution: 512 × 512 pixels\n * Only one product per image\n * The product should cover more than 25 per cent of the image height\n\n\n\n* Worn Image Requirements\n * Minimum resolution: 800 × 800 pixels\n\n\n\n**Supported Selfie View**\n\n* Recommended image resolution: at least 512 × 512 pixels.\n* Recommended face coverage: more than 15 per cent of the image height.\n* The image must clearly show a single human subject with the face fully visible and at least a head shot included in the frame, from head to chest. A half-body shot is preferred.\n\n\n\n**Try-on Styles**\n\n* There are four predefined styles for generating the virtual try-on output: \"style_parisian_chic\", \"style_urban_chic\", \"style_mediterranean_chic\" and \"style_art_deco_style\". You can specify this style parameter when creating an AI task or allow the system to randomly select a style by default.\n\n\n\n---\n\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n|AI Bag Virtual Try-On|Input: long side <= 4096
Output: 1104 x 1472 |< 10MB|jpg/jpeg/png/heic|\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n| error_download_image | Download srcKeys/refKeys error |\n| error_inference | Inference pipeline error |\n| error_no_face | No face detected in source image |\n| error_nsfw_content_detected| NSFW content detected in result image |\n| exceed_max_filesize | Input file size exceeds the maximum limit (10 MB) |\n| invalid_parameter | Invalid gender option value
Invalid style option value |\n| unknown_internal_error | Others |\n\n\n* Environment & Dependency\n\n| Sample Code Language / Tool | Recommended Runtime Versions |\n|---|---|\n| cURL | - bash >= 3.2 - curl >= 7.58 (modern TLS/HTTP support) - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80 - Firefox >= 74 - Safari >= 13.1 |\n| PHP | PHP >= 7.4 (for modern TLS/compat), ext-curl (recommended) or allow_url_fopen=On + ext-openssl, ext-json |\n| Python | Python >= 3.10 (for f-strings), requests >= 2.20.0 |\n| Java | Java 11+ (for HttpClient), Jackson Databind >= 2.12.0 |\n\n---\n"},"compilationErrors":[],"markdown":{"partials":{},"variables":{"rbac":{"teams":["anonymous"]},"user":{},"remoteAddr":{"hostname":"docs.perfectcorp.com","port":4000,"ipAddress":"216.73.217.22"},"lang":"default_locale","env":{"PUBLIC_REDOCLY_BRANCH_NAME":"master"}}},"pagePropGetterError":{"message":"","name":""}},"slug":"/reference/ai_bag","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}