{ "openapi": "3.0.0", "info": { "title": "顔パーツの色分析", "description": "# 概要\n顔パーツの色分析では、肌の色調、目、眉毛、唇、髪の色を検出します。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/img_Face_Ratio_sec_02_02_enu_21a3d8d423.jpg)\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/shade_finder_s5_poster_2_8a8f9307d2.png)\n\n\n## 統合ガイド\n* 顔パーツの色分析用の写真撮影方法\n\n 正面を向いて自撮りしてください\n - カメラをまっすぐ見ている、1 枚のクリアな写真のみを使用してください。髪を下ろして胸にかかっている状態にし、真正面を向いていることを確認してください。\n - 代わりに、JS Camera Kit を使用して写真を撮影してください。髪を下ろして胸にかかっている状態にしてください。結ばないでください。\n\n* AI による肌トラブル検出方法\n1. **ソース画像のリサイズ**
\n サポートされている寸法に合わせて写真をリサイズします。詳細は **[ファイル仕様とエラー](#section/overview/File-Specs-and-Errors)** を参照してください。\n\n2. **File API を使用したファイルのアップロード**
\n ***/s2s/v2.0/file*** API を使用して、対象ユーザーの画像をアップロードします。\n - 画像要件\n - 詳細は **[ファイル仕様とエラー](#section/overview/File-Specs-and-Errors)** を参照してください。\n - ***重要***: File API を呼び出すだけではファイルはアップロードされません。File API のレスポンスで提供される **URL に手動でファイル** をアップロードする必要があります。その URL がアップロード先です。次に進む前に、ファイルが正常に転送されたことを確認してください。
\n AI API を呼び出す前に、ファイルが正常にアップロードされていることを確認してください。File API を使用してアップロード URL を取得し、その場所にファイルをアップロードします。アップロードが完了すると、レスポンスに ***file_id*** が返されます。この ID は、そのファイルに関連する AI 機能にアクセスするために使用します。\n\n > **警告:** File API のレスポンスで提供される URL にファイルをアップロードしない場合、AI API の使用時に 500 Server Error / unknown_internal_error または 404 Not Found エラーが発生します。\n\n3. **顔パーツの色分析タスクの実行**
\n アップロードが完了すると、AI はファイル ID を使用して、唇、目、眉毛、肌、髪の色調を調べます。詳細は **[入力と出力](#section/overview/Inputs-and-Outputs)** を参照してください。
\n 次に、File ID を指定して POST 'task/skin-tone-analysis' を呼び出すと、タスクが実行され、***task_id*** が取得されます。\n\n4. **タスクのステータスをポーリングして成功またはエラーを確認する**
\nこの ***task_id*** は、GET 'task/skin-tone-analysis' によるポーリングを通じてタスクのステータスを監視するために使用され、現在のエンジンステータスを取得します。エンジンがタスクを完了するまで、ステータスは 'running' のままであり、この段階ではユニットは消費されません。\n\n **警告:** タスクのステータスを保持期間に基づいてポーリングで確認することは必須です。保持期間内にポーリングリクエストがない場合、タスクが正常に処理されていてもタイムアウトします（ユニットが消費されます）。\n\n > **警告:** タイムアウトしたタスクのステータスを確認すると、***InvalidTaskId*** エラーが発生します。したがって、AI タスクを実行したら、ステータスが *success* または *error* になるまで、保持期間内にステータスを確認するために **ポーリング** する必要があります。\n\n5. **成功時に AI タスクの結果を取得する**
\nエンジンが入力ファイルを正常に処理し、結果画像を生成すると、タスクは 'success' ステータスに変更されます。処理済み画像の URL と、結果画像を再アップロードせずに別の AI タスクをチェーン実行できる dst_id が取得されます。\nユニットは、この場合のみ消費されます。エンジンがタスクの処理に失敗した場合、タスクのステータスは 'error' に変更され、ユニットは消費されません。
\nユニットを控除する際、システムは期限切れに近いものから優先的に控除します。期限が同じ場合は、最も早い日に取得されたユニットから控除されます。\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2022-08-19/2a1af800-7c69-44a5-a94c-70a4a9c4d2b0.jpg)\n\n---\n\n## 入力と出力\n* 入力\nAI は肌の色調を分析します。`face_angle_strictness_level` を調整して、入力された顔の角度のチェックの厳密さを、strict、high、medium、low、flexible の範囲で制御できます。厳密さレベルは、ピッチ、ヨー、ロールを含む顔の角度検出に適用されます。デフォルト設定は high です。\n\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/shade_finder_s4_poster_399f34c6ef.jpg)\n\n* 出力\n```json\n{\n \"status\": 200,\n \"data\": {\n \"task_status\": \"success\",\n \"results\": {\n \"color\": {\n \"eye_color\": \"#293F9B\",\n \"eye_color_name\": \"Blue\",\n \"lip_color\": \"#D23245\",\n \"eyebrow_color\": \"#5B2B31\",\n \"skin_color\": \"#b9947c\",\n \"hair_color\": \"#a0a0a0\",\n \"hair_color_name\": \"Auburn\"\n }\n }\n }\n}\n```\n\n| **結果パラメータ** | **結果タイプ** |\n| --- | --- |\n| `skin_color` | Hex 値 |\n| `eye_color`| Hex 値 |\n| `eye_color_name` | Amber, Brown, Green, Blue, Gray, Other |\n| `lip_color` | Hex 値 |\n| `eyebrow_color` | Hex 値 |\n| `hair_color` | Hex 値 |\n| `color.hair_color_name` | Auburn, Black, Blonde, Brown, Grey/White, Red |\n\n\n* 撮影方法のヒント:\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/strapi/assets/webp_AI%20Skin%20Analysis_camera_f93315b088.png)\n\n> **警告:** 顔の幅は画像の幅の 60% より大きくなければなりません。\n\n---\n\n## ファイル仕様とエラー\n* サポートされている形式と寸法\n\n| AI 機能 | サポートされている寸法 | サポートされているファイルサイズ | サポートされている形式 |\n| ---- | ---- | ---- | ---- |\n| 顔パーツの色分析 | 長辺 <= 4096、1 人のみ。1080px より長い辺を持つ画像は、分析のために自動的にリサイズされます。 | < 10MB | jpg/jpeg |\n\n* エラーコード\n\n|エラーコード|説明|\n| ---- | ---- |\n| error_below_min_image_size | ソース画像の寸法は少なくとも 320 ピクセルである必要があります。 |\n| error_face_position_invalid | 顔は完全に可視であり、正面を向いており、画像の中央にある必要があります。 |\n| error_face_position_too_small | 検出された顔が分析には小さすぎます。 |\n| error_face_position_out_of_boundary | 顔が画像の境界を超えています。 |\n| error_face_not_forward_facing | 顔はカメラを直接向いている必要があります。 |\n| error_face_angle_upward | 顔が上向きに傾きすぎています—頭をわずかに下げてください。 |\n| error_face_angle_downward | 顔が下向きに傾きすぎています—頭をわずかに上げてください。 |\n| error_face_angle_leftward | 顔が左に回りすぎています—頭をわずかに右に回してください。 |\n| error_face_angle_rightward | 顔が右に回りすぎています—頭をわずかに左に回してください。 |\n| error_face_angle_left_tilt | 顔が左に傾きすぎています—頭を優しく右に傾けてください。 |\n| error_face_angle_right_tilt | 顔が右に傾きすぎています—頭を優しく左に傾けてください。 |\n\n* 環境と依存関係\n\n| サンプルコード言語 / ツール | 推奨ランタイムバージョン |\n|---|---|\n| cURL | - bash >= 3.2
- curl >= 7.58 (モダンな TLS/HTTP サポート)
- jq >= 1.6 (堅牢な JSON パーシング) |\n| Node.js (JavaScript) | Node >= 18 (global fetch 用) |\n| JavaScript | - Chrome / Edge >= 80
- Firefox >= 74
- Safari >= 13.1 |\n| PHP | PHP >= 7.4 (モダンな TLS/互換性用), ext-curl (推奨) または allow_url_fopen=On + ext-openssl, ext-json |\n| Python | Python >= 3.10 (f-strings 用), requests >= 2.20.0 |\n| Java | Java 11+ (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| 顔パーツの色分析 V1.0 | 20 |\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" } ], "paths": { "/s2s/v2.0/task/skin-tone-analysis": { "post": { "summary": "顔パーツの色分析タスクを実行します。", "description": "このエンドポイントで肌色分析プロセスを開始します。ソースファイル（URL または File ID）を指定し、必要に応じて顔角度の厳密さレベルを指定してください。タスクは非同期で処理され、このレスポンスで返される task_id を使用してステータスを確認できます。", "tags": [ "V1.0" ], "security": [ { "BearerAuthenticationV2": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunSkinToneAnalysisTaskV2" } } } }, "responses": { "200": { "description": "タスクの実行に成功しました", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicRunTaskResponseV2" } } } }, "400": { "description": "タスクの実行に失敗しました", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/RunError" } ] } } } }, "401": { "$ref": "#/components/responses/InvalidApiKey" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/s2s/v2.0/task/skin-tone-analysis/{task_id}": { "get": { "summary": "肌色分析タスクのステータスを確認します。", "tags": [ "V1.0" ], "security": [ { "BearerAuthenticationV2": [] } ], "parameters": [ { "name": "task_id", "in": "path", "required": true, "schema": { "type": "string", "example": "grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe" }, "description": "確認するタスクの ID" } ], "responses": { "200": { "description": "タスクステータスの確認に成功しました", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SkinToneAnalysisTaskStatusResponseV2" } } } }, "400": { "$ref": "#/components/responses/InvalidTaskId" }, "401": { "$ref": "#/components/responses/InvalidApiKey" }, "500": { "$ref": "#/components/responses/TaskTimeout" } } } } }, "components": { "securitySchemes": { "BearerAuthenticationV2": { "type": "http", "scheme": "bearer", "description": "標準の 'Bearer authentication' を使用します。ヘッダーに 'API Key' を設定してください：`Authorization:Bearer YOUR_API_KEY`。'Bearer' と 'YOUR_API_KEY' の間にスペースが 1 つ必要です。" } }, "schemas": { "RunSkinToneAnalysisTaskV2": { "title": "肌色分析タスクの実行 V2", "allOf": [ { "$ref": "#/components/schemas/BasicRunTaskV2" }, { "type": "object", "properties": { "face_angle_strictness_level": { "$ref": "#/components/schemas/BasicFaceAttrReqFaceAngleStrictnessLevel" } } } ] }, "BasicFaceAttrReqFaceAngleStrictnessLevel": { "type": "string", "description": "顔角度検出（ピッチ、ヨー、ロール）の厳密さレベルです。\nより厳しいレベルを指定すると、顔属性の分析結果の精度が高まります。\n初期値は 'high' です。\noptions:\n - strict: pitch <= 4 degrees, yaw <= 6 degrees, roll <= 4 degrees\n - high: pitch, yaw, roll <= 10 degrees\n - medium: pitch, yaw, roll <= 15 degrees\n - low: pitch, yaw, roll <= 20 degrees\n - flexible: pitch, yaw, roll <= 30 degrees", "enum": [ "strict", "high", "medium", "low", "flexible" ], "example": "high" }, "BasicFaceAttrRespFaceQuality": { "type": "object", "properties": { "has_face": { "type": "boolean", "example": true }, "area": { "type": "string", "example": "good" }, "frontal": { "type": "string", "example": "good" }, "lighting": { "type": "string", "example": "good" }, "faceangle": { "type": "string", "example": "good" } } }, "BasicFaceAttrRespColor": { "type": "object", "properties": { "eye_color": { "type": "string", "description": "目の色の hex 値", "example": "#293F9B" }, "eye_color_name": { "type": "string", "enum": [ "Amber", "Brown", "Green", "Blue", "Gray", "Other" ], "example": "Blue" }, "lip_color": { "type": "string", "description": "唇の色の hex 値", "example": "#D23245" }, "eyebrow_color": { "type": "string", "description": "眉毛の色の hex 値", "example": "#5B2B31" }, "skin_color": { "type": "string", "pattern": "^#([A-Fa-f0-9]{6})$", "description": "肌の色の hex コード", "example": "#b9947c" }, "hair_color": { "type": "string", "format": "color", "enum": [ "#a0a0a0", "#722626", "#000000", "#FAF0BE", "#42280E", "#808080", "#B56637" ] }, "hair_color_name": { "type": "string", "enum": [ "Auburn", "Black", "Blonde", "Brown", "Grey/White", "Red" ] } } }, "SkinToneAnalysisTaskStatusResponseV2": { "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": { "face_quality": { "$ref": "#/components/schemas/BasicFaceAttrRespFaceQuality" }, "color": { "$ref": "#/components/schemas/BasicFaceAttrRespColor" } } } ] } } } } }, "BasicRunTaskV2SrcFileUrl": { "type": "object", "required": [ "src_file_url" ], "properties": { "src_file_url": { "type": "string", "description": "タスクを実行するファイルの URL。この URL は公開されている必要があります。", "example": "https://example.com/selfie.jpg" } } }, "BasicRunTaskV2SrcFileId": { "type": "object", "required": [ "src_file_id" ], "properties": { "src_file_id": { "type": "string", "description": "タスクを実行するファイルの ID。ファイルアップロード API から取得したファイル ID です。", "example": "pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE=" } } }, "BasicRunTaskV2": { "title": "BasicRunTaskV2", "anyOf": [ { "title": "src ファイル URL でタスクを実行", "allOf": [ { "$ref": "#/components/schemas/BasicRunTaskV2SrcFileUrl" } ] }, { "title": "src ファイル ID でタスクを実行", "allOf": [ { "$ref": "#/components/schemas/BasicRunTaskV2SrcFileId" } ] } ] }, "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" } } } } }, "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": [ "InvalidParameters", "CreditInsufficiency", "InvalidStyleGroup", "InvalidStyle", "BadRequest" ], "description": "エラーコード:\n * InvalidParameters - 無効なリクエストパラメータ\n * CreditInsufficiency - 実行に必要なユニットが不足しています\n * BadRequest - 予期しないリクエストパラメータ\n * InvalidStyleGroup - 無効なスタイルグループ ID\n * InvalidStyle - 無効なスタイル ID" } } }, "EngineErrorCode": { "type": "string", "nullable": true, "enum": [ "error_exceed_max_image_size", "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- `error_exceed_max_image_size` - 入力画像サイズが最大制限を超えています\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` - NSFW 画像の生成を避けるための再試行制限を超えました\n- `error_upload` - 結果画像のアップロードエラー\n- `unknown_internal_error` - その他\n" } }, "responses": { "InvalidApiKey": { "description": "無効または欠落している API キー", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 401, "description": "レスポンスステータス" }, "error": { "type": "string", "example": "Invalid API key" } } } } } }, "TooManyRequests": { "description": "リクエストが多すぎます", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 429, "description": "レスポンスステータス" }, "error": { "type": "string", "example": "Too many requests" } } } } } }, "InvalidTaskId": { "description": "無効なタスク ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 400, "description": "レスポンスステータス" }, "error": { "type": "string", "example": "Invalid task ID" } } } } } }, "TaskTimeout": { "description": "タスク実行タイムアウト", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 500, "description": "レスポンスステータス" }, "error": { "type": "string", "example": "Task execution timed out" } } } } } } } } }