{
"openapi": "3.0.0",
"info": {
"title": "AI 发型发量密度检测",
"description": "# 概览\nAI 发密度检测用照片就能快速做出专业评估：通过观察头皮显露程度与头发分布形态，把发密度分成四档，给出近似毛发镜检查的洞察，不必借助任何实体工具。商家上传一张图即可规模化地提供专家级的个性化服务。\n\n\n\n## 接入指南\n* AI 发密度检测怎么拍照\n* 拍一张自拍\n - 请正对镜头、光线充足，然后把头低到 45 度。头发不要扎起来，整条发际线要清楚可见。\n\n \n\n - 也可以用 JS Camera Kit 拍照。\n\n* 如何用 AI 检测发密度\n* 请用 ***/s2s/v2.0/file*** 接口上传以下素材：\n - 您的自拍照片。\n\n* 执行 AI 任务 ***/s2s/v2.0/task/hair-density-detection*** \n送一张正脸、低头 45 度的自拍图片来执行检测任务，把它的文件 ID 作为 AI 的输入源。\n\n* 轮询任务状态，直到成功或报错\n用这个 ***task_id*** 轮询 GET 'task/hair-density-detection' 监控任务状态，取得引擎当前的处理进度。引擎完成任务之前，状态会一直是 'running'，这一阶段不消耗点数。\n\n\n## 发密度分级\n\n|缩略图|发密度分级|说明|\n| ---- | ---- | ---- |\n||第 1 级
极低密度|头发明显稀疏，大面积可见头皮。发丝细，覆盖度很低。|\n||第 2 级
低密度|稀疏可见，头顶与分缝处头皮尤其明显。头发缺少蓬松感与厚度。|\n||第 3 级
中等密度|强光下可部分看到头皮，但头发仍有一定蓬松度与覆盖度。发丝偏细，整体还算健康。|\n||第 4 级
高密度|头发饱满浓密，几乎看不到头皮。发丝排列紧密，蓬松充足、覆盖自然。|\n\n\n* 拍摄建议\n\n![Suggestions for How to Shoot](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/icon_S2_step1_20d0a161da.png \"Suggestions for How to Shoot\")\n\n\n\n## 文件规格与错误码\n* 支持的格式与尺寸\n\n|类型|支持尺寸|支持文件大小|支持格式|\n| ---- | ---- | ---- | ---- |\n|AI 发密度检测|图片宽高至少 100 像素，任一维度不超过 4096 像素。若某一边超过 1080 像素，会自动缩放到该上限以内进行分析。|< 10MB|jpg/png|\n\n* 错误码\n\n|错误码|说明|\n| ---- | ---- |\n|error_below_min_image_size|图片宽或高小于 100 像素，尺寸过小，无法使用|\n|error_face_position_invalid|脸部需完整可见，不能被裁掉一部分|\n|error_face_position_too_small|照片中的人脸过小，无法准确分析|\n|error_face_position_out_of_boundary|脸部过大，或部分超出照片边缘|\n|error_insufficient_lighting|光线太暗，分析起来很困难|\n|error_face_angle_invalid|脸部角度不太对。正脸拍摄时，头部偏离正向请在 10 度以内；侧脸拍摄时，角度应大于 15 度|\n\n* 运行环境与依赖\n\n| 示例代码语言 / 工具 | 建议运行时版本 |\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## 点数消耗\n\n| AI 功能 | 消耗点数 |\n|---|---|\n| AI 发密度检测 V1.0 | 1 |\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 发型发量密度检测功能。"
}
],
"paths": {
"/s2s/v2.0/task/hair-density-detection": {
"post": {
"summary": "执行 AI 发型发量密度检测 任务。",
"description": "需要轮询才能查到任务状态，细节请参见轮询指南。",
"tags": [
"V1.0"
],
"security": [
{
"BearerAuthenticationV2": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BasicRunTaskV2"
}
}
}
},
"responses": {
"200": {
"description": "任务执行成功",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BasicRunTaskResponseV2"
}
}
}
},
"400": {
"description": "任务执行失败",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/responses/RunError"
}
]
}
}
}
},
"401": {
"$ref": "#/components/responses/InvalidApiKey"
},
"429": {
"$ref": "#/components/responses/TooManyRequests"
}
}
}
},
"/s2s/v2.0/task/hair-density-detection/{task_id}": {
"get": {
"summary": "查询 AI 发型发量密度检测 任务的状态。",
"tags": [
"V1.0"
],
"security": [
{
"BearerAuthenticationV2": []
}
],
"parameters": [
{
"name": "task_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"example": "grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe"
},
"description": "要查询的任务 ID"
}
],
"responses": {
"200": {
"description": "AI 发型发量密度检测任务状态查询成功。",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "响应状态",
"example": 200
},
"data": {
"type": "object",
"properties": {
"task_status": {
"type": "string",
"enum": [
"running",
"success",
"error"
],
"description": "任务状态"
},
"error": {
"$ref": "#/components/schemas/EngineErrorCode"
},
"error_message": {
"type": "string",
"description": "错误的详细说明"
},
"results": {
"allOf": [
{
"type": "object",
"properties": {
"timed": {
"type": "number"
},
"hair_density": {
"$ref": "#/components/schemas/BasicHairDensityRespHairDensity"
}
}
}
]
}
}
}
}
}
}
}
},
"400": {
"$ref": "#/components/responses/InvalidTaskId"
},
"401": {
"$ref": "#/components/responses/InvalidApiKey"
},
"500": {
"$ref": "#/components/responses/TaskTimeout"
}
}
}
}
},
"components": {
"schemas": {
"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": "错误码：\n- `exceed_max_filesize` - 输入文件大小超出上限\n- `invalid_parameter` - 参数取值无效\n- `error_download_image` - 下载原图出错\n- `error_download_mask` - 下载蒙版图片出错\n- `error_decode_image` - 解码原图出错\n- `error_decode_mask` - 解码蒙版图片出错\n- `error_nsfw_content_detected` - 在原图中检测到不适宜内容（NSFW）\n- `error_no_face` - 原图中没有检测到人脸\n- `error_pose` - 原图的姿态检测失败\n- `error_face_parsing` - 原图的人脸分割失败\n- `error_inference` - 推理流程中出现错误\n- `exceed_nsfw_retry_limits` - 为避免生成不适宜内容， 重试次数已用尽\n- `error_upload` - 上传结果图片出错\n- `unknown_internal_error` - 其他错误\n"
},
"FileV1.1": {
"title": "File V1.1",
"description": "该对象表示一个文件。",
"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": "该文件的 MIME 类型。当前支持的取值见上方的枚举。"
},
"file_name": {
"type": "string",
"example": "my-selfie.jpg",
"description": "文件名"
},
"file_size": {
"type": "integer",
"example": 50000,
"description": "该文件的大小（字节）。不应超过 10MB。"
}
}
}
}
}
},
"BasicFileResponse": {
"type": "object",
"properties": {
"files": {
"type": "array",
"items": {
"type": "object",
"properties": {
"content_type": {
"type": "string",
"example": "image/jpg",
"description": "该文件的 MIME 类型。"
},
"file_name": {
"type": "string",
"example": "my-selfie.jpg",
"description": "文件名"
},
"file_id": {
"type": "string",
"example": "U8aqJbsXGT537jtGnEDFHqxdDXqh8+oTF/cSkLimzuvVwMP+Jb1XbjPsf7ZgUgLY",
"description": "该文件的 ID。其他运行任务的接口需要用到这个 `file_id`。"
},
"requests": {
"type": "array",
"description": "请用下面的 `url`、`headers`、`method` 上传文件。 上传完成后，用 `file_id` 继续调用运行任务接口。",
"items": {
"type": "object",
"properties": {
"headers": {
"type": "object",
"example": {
"Content-Type": "image/jpg",
"Content-Length": 50000
},
"description": "上传文件时需携带的请求头"
},
"url": {
"type": "string",
"example": "https://example.com/presigned-upload-url",
"description": "上传该文件的 URL"
},
"method": {
"type": "string",
"example": "PUT",
"description": "上传该文件所用的 HTTP 方法"
}
}
}
}
}
}
}
}
},
"FileResponseV2": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"example": 200,
"description": "响应状态"
},
"data": {
"$ref": "#/components/schemas/BasicFileResponse"
}
}
},
"BasicRunTaskResponseV2": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "响应状态",
"example": 200
},
"data": {
"type": "object",
"properties": {
"task_id": {
"type": "string",
"description": "该任务的 ID。凭这个 ID 可在 24 小时内查询任务结果。",
"example": "grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe"
}
}
}
}
},
"BasicRunTaskV2SrcFileId": {
"title": "用源文件 ID 运行任务",
"type": "object",
"required": [
"src_file_id"
],
"properties": {
"src_file_id": {
"type": "string",
"description": "用于运行任务的文件 ID，取自上传文件接口返回的 file_id。",
"example": "pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE="
}
}
},
"BasicRunTaskV2SrcFileUrl": {
"title": "用源文件 URL 运行任务",
"type": "object",
"required": [
"src_file_url"
],
"properties": {
"src_file_url": {
"type": "string",
"description": "用于运行任务的文件 URL，该 URL 需可公开访问。",
"example": "https://example.com/selfie.jpg"
}
}
},
"BasicRunTaskV2": {
"title": "BasicRunTaskV2",
"anyOf": [
{
"$ref": "#/components/schemas/BasicRunTaskV2SrcFileUrl"
},
{
"$ref": "#/components/schemas/BasicRunTaskV2SrcFileId"
}
]
},
"BasicHairDensityRespHairDensity": {
"type": "object",
"properties": {
"mapping": {
"type": "string",
"description": "以字符串表示的浮点数",
"minimum": "0",
"maximum": "3",
"example": "2.16"
},
"term": {
"type": "string",
"enum": [
"Extremely Low Density",
"Low Density",
"Medium Density",
"High Density"
]
}
}
}
},
"responses": {
"BadRequestAndInvalidParameters": {
"description": "因客户端错误或请求参数无效，无法处理该请求",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "响应状态"
},
"error": {
"type": "string",
"description": "错误信息",
"example": "The operation could not be completed"
},
"error_code": {
"type": "string",
"enum": [
"BadRequest",
"InvalidParameters"
],
"description": "错误码：\n * BadRequest - 请求参数或请求体不符合预期\n * InvalidParameters - 请求参数或请求体无效\n"
}
}
}
}
}
},
"InvalidApiKey": {
"description": "API 密钥无效、已停用或已过期",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"example": 401,
"description": "响应状态"
},
"error_code": {
"type": "string",
"enum": [
"InvalidApiKey",
"InactiveApiKey",
"ExpiredApiKey"
],
"description": "错误码：\n * InvalidApiKey - 未提供 API 密钥，或密钥无效\n * InactiveApiKey - API 密钥已被停用\n * ExpiredApiKey - API 密钥已过期\n"
}
}
}
}
}
},
"RunError": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "响应状态",
"example": 400
},
"error": {
"type": "string",
"description": "错误信息",
"example": "The operation could not be completed"
},
"error_code": {
"type": "string",
"enum": [
"CreditInsufficiency",
"InvalidStyleGroup",
"InvalidStyle",
"BadRequest",
"InvalidParameters"
],
"description": "错误码：\n * CreditInsufficiency - 点数不足，无法运行\n * BadRequest - 请求参数不符合预期\n * InvalidStyleGroup - 风格分组 ID 无效\n * InvalidStyle - 风格 ID 无效\n * InvalidParameters - 请求参数无效\n"
}
}
},
"InvalidTaskId": {
"description": "任务 ID 无效",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "响应状态",
"example": 400
},
"error_code": {
"type": "string",
"enum": [
"InvalidTaskId"
],
"description": "错误码：\n * InvalidTaskId - 任务 ID 无效\n"
}
}
}
}
}
},
"TooManyRequests": {
"description": "单位时间内请求过多"
},
"TaskTimeout": {
"description": "任务在预期时间内没有响应",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"description": "响应状态",
"example": 500
},
"error_code": {
"type": "string",
"enum": [
"TaskTimeout"
],
"description": "错误码：\n * TaskTimeout - 任务在预期时间内没有响应\n"
}
}
}
}
}
}
},
"securitySchemes": {
"BearerAuthenticationV2": {
"type": "http",
"scheme": "bearer",
"description": "使用标准的 Bearer 鉴权。把您的 API 密钥放进请求头： `Authorization:Bearer YOUR_API_KEY`。请注意 'Bearer' 与 'YOUR_API_KEY' 之间有一个空格。"
}
}
}
}