{ "openapi": "3.0.0", "info": { "title": "AI Hair Length Detection", "description": "# Overview\nAI Hair Length Measurement offers haircare brands and salons a quick solution to analyze and measure hair length, enabling informed decisions for personalized products and services.\nOur AI is meticulously trained on a vast dataset of diverse images to ensure precise and reliable hair length detection. By analyzing thousands of images of various hair types and styles, it precisely identifies and categorizes five distinct hair lengths, from above-the-ear to mid-back, with exceptional accuracy.\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/hair_length_S1_01_enu_b03bd393af.jpg)\n\n## Integration Guide\n* How to Take Photos for AI Hair Length Detection\n* Take a selfie facing forward\n - Just one clear shot, looking straight into the camera. Leave your hair down so it falls over your chest, and make sure you're staring directly ahead for that front-on view.\n - Instead, use the JS Camera Kit to take a photo. Just leave your hair down so it falls over your chest. Don't tie it up.\n\n* How to Detect Hair Length by AI\n* Using the ***/s2s/v2.0/file*** API, please upload the following assets:\n - Your selfie photo.\n\n* Execute AI task ***/s2s/v2.0/task/hair-length-detection***
\nRun the hair-length detection task by sending one front facing selfie image. Use it's file ID as the source input for the AI.\n\n* Polling to check the status of a task until it succeed or error
\nThis ***task_id*** is used to monitor the task's status through polling GET 'task/hair-length-detection' to retrieve the current engine status. Until the engine completes the task, the status will remain 'running', and no units will be consumed during this stage.\n\n## Hair Length Classification\n|Thumbnail|Hair Length Classification|Description|\n| ---- | ---- | ---- |\n|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/thumb_hair_lenth_above_the_ears.b41525da.png)|Above-Ear Length|Hair that falls just above the ear, offering a sleek and stylish look that frames the face nicely.|\n|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/thumb_hair_lenth_ear_length.0740b805.png)|Ear-Length|Hair that reaches the earlobe, providing a chic and versatile style that's easy to maintain.|\n|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/thumb_hair_lenth_short_hair.d7f24ddb.png)|Short Hair|Hair that is cut above the shoulders, ideal for a fresh, modern look that’s both bold and low-maintenance.|\n|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/thumb_hair_lenth_above_chest.1b624c17.png)|Medium-Length|Hair that falls around the collarbone, offering a balanced style that’s perfect for both updos and loose waves.|\n|![](https://d3ss46vukfdtpo.cloudfront.net/static/media/thumb_hair_lenth_longer_hair.7fbcc9d0.png)|Long Hair|Long hair that exudes elegance, providing a classic appearance with numerous styling options.|\n\n* Result Arguments\n* term: result is a string showing the detected hair length type. Here lists all the possible result strings in an array:\n ```json\n [\"above the ears\", \"ear length\", \"ear length or longer\", \"short hair\", \"short hair or longer\", \"above chest\", \"above chest or longer\", \"long hair\"]\n ```\n\n* Suggestions for How to Shoot\n![Suggestions for How to Shoot](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI%20Hair%20Length%20Detection_how%20to%20shoot.png \"Suggestions for How to Shoot\")\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/AI%20Skin%20Analysis_camera.png)\n\n## File Specs & Errors\n* Supported Formats & Dimensions\n\n|Type|Supported Dimensions|Supported File Size|Supported Formats|\n| ---- | ---- | ---- | ---- |\n|AI Hair Length Detection|The image must be at least 320 pixels wide and tall, and no more than 4096 pixels in either dimension. If one side of your image is longer than 1080 pixels, it will be resized automatically to fit within that limit for analysis.|< 10MB|jpg/png|\n\n* Error Codes\n\n|Error Code|Description|\n| ---- | ---- |\n|error_below_min_image_size|If your image is smaller than 320 pixels in width or height, it's too small to use|\n|error_face_position_invalid|Your face needs to be fully visible in the image, without any parts cut off|\n|error_face_position_too_small|The face in your photo is too small to analyze properly|\n|error_face_position_out_of_boundary|Your face is either too large or partially outside the edges of the photo|\n|error_insufficient_lighting|The lighting is too dim, which makes analysis difficult|\n|error_face_angle_invalid|Your face angle isn't quite right. For front-facing shots, keep your head within 10 degrees of straight. For side-facing shots, the angle should be more than 15 degrees|\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\n## JS Camera Kit\n{% partial file=\"/_partials/js-camera-kit.md\" /%}\n\n---\n\n## Unit Consumption\n\n| AI Feature | Unit Consumed |\n|---|---|\n| AI Hair Length Detection V1.0 | 2 |\n\n---\n", "version": "", "termsOfService": "https://www.makeupar.com/perfectbeauty/youcam/terms-of-service-api", "contact": { "email": "YouCamOnlineEditor_API@perfectcorp.com" }, "license": { "name": "Privacy policy", "url": "https://www.makeupar.com/perfectbeauty/youcam/privacy-policy-api" } }, "servers": [ { "url": "https://yce-api-01.makeupar.com" } ], "tags": [ { "name": "V1.0", "description": "AI Hair Length Detection API allows you to detect the length of hair in images." } ], "paths": { "/s2s/v2.0/task/hair-length-detection": { "post": { "summary": "Run an Hair Length Detection task.", "description": "Please refer to the polling guide for checking task status.", "tags": [ "V1.0" ], "security": [ { "BearerAuthenticationV2": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/BasicRunTaskV2" }, { "type": "object", "properties": {} } ] } } } }, "responses": { "200": { "description": "Successful execution of the task", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicRunTaskResponseV2" } } } }, "400": { "description": "Failed execution of task", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/responses/RunError" } ] } } } }, "401": { "$ref": "#/components/responses/InvalidApiKey" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/s2s/v2.0/task/hair-length-detection/{task_id}": { "get": { "summary": "Check an Hair Length Detection task status.", "tags": [ "V1.0" ], "security": [ { "BearerAuthenticationV2": [] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "example": "grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe" }, "description": "ID of task to check" } ], "responses": { "200": { "description": "Successful check of the task status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TaskStatusResponseHairLength" } } } }, "400": { "$ref": "#/components/responses/InvalidTaskId" }, "401": { "$ref": "#/components/responses/InvalidApiKey" }, "500": { "$ref": "#/components/responses/TaskTimeout" } } } } }, "components": { "schemas": { "FileV1.1": { "title": "File V1.1", "description": "This object represents a file.", "type": "object", "required": [ "files" ], "properties": { "files": { "type": "array", "items": { "type": "object", "required": [ "content_type", "file_name", "file_size" ], "properties": { "content_type": { "type": "string", "example": "image/jpg", "description": "Content MIME type for this file. Currently available values are listed in the enum." }, "file_name": { "type": "string", "example": "my-selfie.jpg", "description": "Name of this file" }, "file_size": { "type": "integer", "example": 50000, "description": "Content length for this file in bytes. Should not be larger than 10MB." } } } } } }, "BasicFileResponse": { "type": "object", "properties": { "files": { "type": "array", "items": { "type": "object", "properties": { "content_type": { "type": "string", "example": "image/jpg", "description": "Content MIME type for this file." }, "file_name": { "type": "string", "example": "my-selfie.jpg", "description": "Name of this file" }, "file_id": { "type": "string", "example": "U8aqJbsXGT537jtGnEDFHqxdDXqh8+oTF/cSkLimzuvVwMP+Jb1XbjPsf7ZgUgLY", "description": "ID of this file. Other run task API will need this `file_id`." }, "requests": { "type": "array", "description": "Using upload `url`, `headers`, `method` below to upload file. After completion, the `file_id` is used to proceed with calling run task API.", "items": { "type": "object", "properties": { "headers": { "type": "object", "example": { "Content-Type": "image/jpg", "Content-Length": 50000 }, "description": "Headers to include when uploading the file" }, "url": { "type": "string", "example": "https://example.com/presigned-upload-url", "description": "URL to upload this file" }, "method": { "type": "string", "example": "PUT", "description": "HTTP method to upload this file" } } } } } } } } }, "FileResponseV2": { "type": "object", "properties": { "status": { "type": "integer", "example": 200, "description": "Response status" }, "data": { "$ref": "#/components/schemas/BasicFileResponse" } } }, "BasicRunTaskV2SrcFileUrl": { "title": "Run task with src file url", "type": "object", "required": [ "src_file_url" ], "properties": { "src_file_url": { "type": "string", "description": "Url of the file to run task. The url should be publicly accessible.", "example": "https://example.com/selfie.jpg" } } }, "BasicRunTaskV2SrcFileId": { "title": "Run task with src file ID", "type": "object", "required": [ "src_file_id" ], "properties": { "src_file_id": { "type": "string", "description": "ID of file to run task. File ID from upload file API.", "example": "pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE=" } } }, "BasicRunTaskV2": { "title": "BasicRunTaskV2", "anyOf": [ { "$ref": "#/components/schemas/BasicRunTaskV2SrcFileUrl" }, { "$ref": "#/components/schemas/BasicRunTaskV2SrcFileId" } ] }, "BasicRunTaskResponseV2": { "type": "object", "properties": { "status": { "type": "integer", "description": "Response status", "example": 200 }, "data": { "type": "object", "properties": { "task_id": { "type": "string", "description": "ID of this task. Task result is valid to query by this ID for 24 hours.", "example": "grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe" } } } } }, "EngineErrorCode": { "type": "string", "nullable": true, "enum": [ "exceed_max_filesize", "invalid_parameter", "error_download_image", "error_download_mask", "error_decode_image", "error_decode_mask", "error_nsfw_content_detected", "error_no_face", "error_pose", "error_face_parsing", "error_inference", "exceed_nsfw_retry_limits", "error_upload", "unknown_internal_error" ], "description": "Errors:\n- `exceed_max_filesize` - Input file size exceeds the maximum limit\n- `invalid_parameter` - Invalid parameter value\n- `error_download_image` - Download source image error\n- `error_download_mask` - Download mask image error\n- `error_decode_image` - Decode source image error\n- `error_decode_mask` - Decode mask image error\n- `error_nsfw_content_detected` - NSFW content detected in source image\n- `error_no_face` - No face detected on source image\n- `error_pose` - Failed to detect pose on source image\n- `error_face_parsing` - Failed to do face segmentation on source image\n- `error_inference` - Inference pipeline error\n- `exceed_nsfw_retry_limits` - Exceed the retry limits to avoid generated NSFW image\n- `error_upload` - Upload result image error\n- `unknown_internal_error` - Others\n" }, "BasicFaceAttrReqHairLength": { "type": "object", "properties": { "term": { "type": "string", "description": "The result of hair length prediction", "enum": [ "above the ears", "ear length", "ear length or longer", "short hair", "short hair or longer", "above chest", "above chest or longer", "long hair" ] } } }, "TaskStatusResponseHairLength": { "type": "object", "properties": { "status": { "type": "integer", "description": "Response status", "example": 200 }, "data": { "type": "object", "properties": { "task_status": { "type": "string", "enum": [ "running", "success", "error" ], "description": "Status of this task" }, "error": { "$ref": "#/components/schemas/EngineErrorCode" }, "error_message": { "type": "string", "description": "Detailed description of error" }, "results": { "allOf": [ { "type": "object", "properties": { "hair_length": { "$ref": "#/components/schemas/BasicFaceAttrReqHairLength" } } } ] } } } } } }, "responses": { "InvalidParameters": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 400, "description": "Response status" }, "error": { "type": "string", "description": "Error message", "example": "The operation could not be completed" }, "error_code": { "type": "string", "enum": [ "InvalidParameters" ], "description": "Error code:\n * InvalidParameters - Invalid request parameters or body\n" } } } } } }, "InvalidApiKey": { "description": "Invalid API Key or Inactive API Key or Expired API Key", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 401, "description": "Response status" }, "error_code": { "type": "string", "enum": [ "InvalidApiKey", "InactiveApiKey", "ExpiredApiKey" ], "description": "Error code:\n * InvalidApiKey - API Key is not given or not valid\n * InactiveApiKey - API Key is inactivated\n * ExpiredApiKey - API Key is expired\n" } } } } } }, "RunError": { "type": "object", "properties": { "status": { "type": "integer", "description": "Response status", "example": 400 }, "error": { "type": "string", "description": "Error message", "example": "The operation could not be completed" }, "error_code": { "type": "string", "enum": [ "CreditInsufficiency", "InvalidStyleGroup", "InvalidStyle", "BadRequest", "InvalidParameters" ], "description": "Error code:\n * CreditInsufficiency - Insufficient unit to run\n * BadRequest - Unexpected request parameter\n * InvalidStyleGroup - Invalid style group id\n * InvalidStyle - Invalid style id\n * InvalidParameters - Invalid request parameters\n" } } }, "InvalidTaskId": { "description": "Invalid task id", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "Response status", "example": 400 }, "error_code": { "type": "string", "enum": [ "InvalidTaskId" ], "description": "Error code:\n * InvalidTaskId - Invalid task id\n" } } } } } }, "TooManyRequests": { "description": "Too many requests within a given amount of time" }, "TaskTimeout": { "description": "The task has no response in the expected time", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "Response status", "example": 500 }, "error_code": { "type": "string", "enum": [ "TaskTimeout" ], "description": "Error code:\n * TaskTimeout - The task has no response in the expected time\n" } } } } } } }, "securitySchemes": { "BearerAuthenticationV2": { "type": "http", "scheme": "bearer", "description": "Use the standard 'Bearer authentication'. Put your 'API Key' in header: `Authorization:Bearer YOUR_API_KEY`. Notice that there is ' ' a space between 'Bearer' and the 'YOUR_API_KEY'." } } } }