{
"openapi": "3.0.0",
"info": {
"title": "AI 肌改善シミュレーション",
"description": "# 概要\n**AI 駆動の肌シミュレーション**\n\nAI 肌シミュレーションでは、顔の肌状態のビフォーアフターを可視化します。\n最大 10 種類の肌悩み（輝き、ニキビ、皮脂、目の下のたるみ、クマ、シミ、毛穴、肌質、しわ、赤み）を可視化できます。\n\n\n\n各シミュレーションは数秒で生成されます。\n\n\n\ne コマースウェブサイト、モバイルアプリケーションなどで使えます。\n\n\n\n\n\n---\n\n## 統合ガイド\nこのガイドでは、以下を説明します。\n\nAI 肌改善シミュレーション API のワークフロー：\n\n**エンドポイント:** `/s2s/v2.0/task/skin-simulation`\n\n**認証必須:** `Authorization: Bearer YOUR_API_KEY`\n\n**ワークフロー手順:**\n\n1. **画像アップロードの準備:**\n - プロセスはセルフィー画像の準備から始まります。\n\n2. **AI 肌改善シミュレーション設定**\n 各肌悩み（例：しわ、毛穴、赤み）について、**シミュレーション強度**を **0.0 から 1.0** の値で調整します：\n\n - **0.0**: *元の*肌の外観を表示します—変更なし。\n - **1.0**: その悩みに対して AI が生成できる*最も自然で健康的に見える*強化を適用します。\n\n **仕組み:**\n - 低い設定（例：0.2～0.4）では、細かいしわや軽微な欠陥が微妙に緩和されます。\n - 高い設定（例：0.7～1.0）では、中程度または深いしわの大幅な軽減、滑らかな質感、トーンの改善など、より顕著な改善が、自然な肌のディテールを保持しながらも発生します。\n\n 望ましい見た目になるまで調整してください。\n\n3. **AI タスクの開始とタスク ID の取得:**\n - アップロードした画像と肌シミュレーション設定を HTTP POST リクエストで `/s2s/v2.0/task/skin-simulation` に送信します。\n - このやり取りを識別する一意のタスク ID をレスポンスで待ちます。\n\n4. **タスクステータスのポーリング（継続的な確認）:**\n - 取得した `task_id` を使用して、HTTP GET リクエスト（例：`GET /task/${task_id}`）でタスクステータスを定期的にポーリングします。\n - 以下を継続的に監視します：\n - `Task_status = \"success\"`（処理完了）。\n - `Task_status = \"error\"`（該当する場合、解決または再試行）。\n - ステータスが success に遷移したら、ワークフローを適切に更新します。\n\n\n\n---\n\n* 認証\n- リクエストヘッダーに **Bearer トークン** を使用して API キーを含めます：\n ```\n Authorization: Bearer YOUR_API_KEY\n ```\nAPI キーの確認場所: https://yce.makeupar.com/api-console/en/api-keys/.\n\n---\n\n* 画像のアップロード\n\nファイルをサーバーに直接アップロードするか、AI タスクペイロードに有効な画像 URL を提供できます。\n\n * アップロードエンドポイント\n\n```\nPOST /s2s/v2.0/file\n```\n\nすでに公開画像 URL がある場合は、この手順をスキップできます。\n\n---\n\n* AI 肌改善シミュレーション強度の調整\n**AI 肌改善シミュレーション設定**\n\n各肌悩み（例：しわ、毛穴、赤み）について、**シミュレーション強度**を **0.0 から 1.0** のスケールで調整します：\n\n- **0.0** → *元の外観* — AI 強化は適用されません。\n- **1.0** → その悩みに対する最大限の改善。\n\n**異なる強度レベルでの期待効果：**\n\n| 強度範囲 | 効果 |\n|-----------------|--------|\n| **0.1 – 0.3** | 微妙な改善: 細かいしわの軽微な平滑化、毛穴のわずかな軽減、赤みの穏やかな軽減。 |\n| **0.4 – 0.6** | 中程度の改善: 質感と透明感の改善。 |\n| **0.7 – 1.0** | 顕著な改善: 中程度から深いしわの大幅な軽減、トーンの均一化、毛穴と赤みの最小化。 |\n\n低め（例：0.2）から開始して調整します。\n\n---\n\n* AI 肌改善シミュレーション AI タスクの作成と結果のポーリング\n\n画像をアップロードし、**少なくとも 1 つ**の肌悩みのシミュレーション強度を 0.0 以上に設定した後、タスクを開始できます。API はリクエストを非同期で処理します。ステータスが `success` または `error` に達するまで、タスクステータスをポーリングする必要があります。\n\n * タスク作成エンドポイント\n\n```\nPOST /s2s/v2.0/task/skin-simulation\n```\n\n * ポーリングエンドポイント\n\n```\nGET /s2s/v2.0/task/skin-simulation/{task_id}\n```\n\n---\n\n## ファイル仕様とエラー\n\n* AI 肌改善シミュレーション仕様\n\n**カメラと撮影ガイドライン**\n\n**ライティング条件**\n環境が十分に明るく、均一に照明されていることを確認してください。強い逆光、局所的な露出オーバー、顔への大きな影を避けてください。可能な限り自然光または柔らかい屋内照明を使用してください。ピンク、ブルー、その他の色付き光源など、有色光は肌の色調の表現を歪める可能性があるため使用しないでください。\n\n**顔の位置と遮蔽**\n顔がカメラを直接向いている正面からのビューを撮影してください。頭の回転は最小限に抑え、過度な傾きや左右への向きを避けてください。額、頬、あごを含む顔全体が完全に可視であり、遮蔽されていないことを確認してください。髪、マスク、手、メガネのフレーム、携帯電話、または顔の特徴を部分的に覆うその他のオブジェクトは使用しないでください。\n\n**表情とポーズ**\n両目を開いた自然でリラックスした表情を保ってください。口は閉じたままでもわずかに開いていても構いませんが、ポーズを無理にしたり誇張したりしないでください。\n\n**フレーム内の顔サイズ**\n正確な分析に必要な十分なディテールを確保するために、顔は画像幅の少なくとも 60% を占める必要があります。被写体が小さすぎる、遠すぎる、または不適切にフレーミングされている画像の撮影は避けてください。\n\n\n\n\n---\n\n* サポートされる形式と寸法\n\n|AI 機能|サポートされる寸法|サポートされるファイルサイズ|サポートされる形式|\n| ---- | ---- | ---- | ---- |\n|AI 肌改善シミュレーション|短辺 >= 480, 長辺 <= 2560|< 10MB|jpg/jpeg/png|\n\n* エラーコード\n\n| **エラーコード** | **説明** |\n|------------------------------------|----------------|\n| `error_below_min_image_size` | 入力画像の解像度が最小必要サイズ未満です（例：< 256×256 ピクセル）。より高解像度の画像をアップロードしてください。 |\n| `error_exceed_max_image_size` | 入力画像の解像度が最大許容サイズを超えています（例：> 2560×2560 ピクセル）。アップロード前に画像をリサイズまたはダウンスケールしてください。 |\n| `error_invalid_params` | 無効なリクエストパラメータが提供されました。 |\n| `error_src_face_too_small` | 検出された顔が画像幅の 60% 未満を占めています—正確な肌分析には小さすぎます。フレーム中央に大きく鮮明な顔がある画像を使用してください。 |\n| `error_src_face_out_of_bound` | 検出された顔が画像境界の外側に部分的または完全に位置しています（例：顔が切り詰められすぎている）。額、頬、あごを含む顔全体が可視であり、適切にフレーミングされていることを確認してください。 |\n| `error_lighting_dark` | 画像内の環境光が信頼できる肌分析には不十分です（例：露出不足、顔に影が支配的）。顔に均一な照明がある明るく撮影された画像をアップロードしてください。 |\n\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 (グローバル 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* 肌シミュレーション\n\n| AI 機能 | 消費ユニット |\n|---|---|\n| 1～4 悩みの分析 | 4 |\n| 5～10 悩みの分析 | 6 |\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/skin-simulation": {
"post": {
"summary": "AI 肌改善シミュレーションタスクを実行します。",
"description": "このエンドポイントで肌改善シミュレーションプロセスを開始します。ソースファイル（URL または File ID 経由）を提供し、シミュレーションパラメータ（しわ、輝きなど）を指定する必要があります。少なくとも 1 つのパラメータはゼロ以外である必要があります。タスクは非同期で処理され、このレスポンスで返される `task_id` を使用してステータスを確認できます。\n",
"tags": [
"V1.0"
],
"security": [
{
"BearerAuthenticationV2": []
}
],
"requestBody": {
"required": true,
"description": "シミュレーション強度をすべてゼロにすることはできません。\n",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RunSkinSimulationTaskV2"
}
}
}
},
"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-simulation/{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": "タスクステータスの確認に成功しました",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TaskStatusResponseV2"
}
}
}
},
"400": {
"$ref": "#/components/responses/InvalidTaskId"
},
"401": {
"$ref": "#/components/responses/InvalidApiKey"
},
"500": {
"$ref": "#/components/responses/TaskTimeout"
}
}
}
}
},
"components": {
"securitySchemes": {
"BearerAuthenticationV2": {
"type": "http",
"scheme": "bearer",
"description": "標準の「Bearer 認証」を使用します。ヘッダーに `API Key` を `Authorization:Bearer YOUR_API_KEY` の形式で設定してください。`Bearer` と `YOUR_API_KEY` の間にスペースが 1 つあることに注意してください。"
}
},
"schemas": {
"RunSkinSimulationTaskV2": {
"title": "Run Skin Simulation Task V2",
"allOf": [
{
"$ref": "#/components/schemas/BasicRunTaskV2"
},
{
"type": "object",
"properties": {
"wrinkle": {
"type": "number",
"description": "しわや小じわの目立ちを抑えます。
0.0 で元の肌、1.0 で最もしわが除去された肌。",
"example": 1,
"minimum": 0,
"maximum": 1
},
"radiance": {
"type": "number",
"description": "肌の輝きと明るさを高めます。
0.0 で元の肌の明るさ、1.0 で最大の輝き/ツヤのある肌。",
"example": 1,
"minimum": 0,
"maximum": 1
},
"oiliness": {
"type": "number",
"description": "過剰なテカリを抑え、バランスが取れて快適なマットな質感の、清潔でテカリのない肌色に仕上げます。
0.0 で元の肌、1.0 で肌に最大の油分/テカリが追加されます。",
"example": 1,
"minimum": 0,
"maximum": 1
},
"acne": {
"type": "number",
"description": "ニキビや黒ずみを減らします。
0.0 で元の肌、1.0 で最もニキビ/吹き出物が除去された肌。",
"example": 1,
"minimum": 0,
"maximum": 1
},
"eye_bags": {
"type": "number",
"description": "目の下のむくみを目立たなくします。
0.0 で元の目の下の見た目、1.0 で最も目の下のたるみが除去された肌。",
"example": 1,
"minimum": 0,
"maximum": 1
},
"dark_circle": {
"type": "number",
"description": "クマを目立たなくします。
0.0 で元の目の下の色、1.0 で最もクマが除去された目元。",
"example": 1,
"minimum": 0,
"maximum": 1
},
"spots": {
"type": "number",
"description": "加齢によるシミを目立たなくします。
0.0 で元の肌、1.0 で最もシミ/そばかすが除去された肌。",
"example": 1,
"minimum": 0,
"maximum": 1
},
"pores": {
"type": "number",
"description": "毛穴を目立たなくします。
0.0 で元の毛穴の目立ち度、1.0 で最も整った/目立たない毛穴。",
"example": 1,
"minimum": 0,
"maximum": 1
},
"texture": {
"type": "number",
"description": "肌の質感を調整します。
0.0 で元の肌の質感、1.0 で最も滑らかな肌の質感。",
"example": 1,
"minimum": 0,
"maximum": 1
},
"redness": {
"type": "number",
"description": "赤みを抑えます。
0.0 で元の肌色、1.0 で最も赤み/刺激が除去された肌色。",
"example": 1,
"minimum": 0,
"maximum": 1
}
},
"not": {
"properties": {
"wrinkle": {
"type": "number",
"enum": [
0
]
},
"radiance": {
"type": "number",
"enum": [
0
]
},
"oiliness": {
"type": "number",
"enum": [
0
]
},
"acne": {
"type": "number",
"enum": [
0
]
},
"eye_bags": {
"type": "number",
"enum": [
0
]
},
"dark_circle": {
"type": "number",
"enum": [
0
]
},
"spots": {
"type": "number",
"enum": [
0
]
},
"pores": {
"type": "number",
"enum": [
0
]
},
"texture": {
"type": "number",
"enum": [
0
]
},
"redness": {
"type": "number",
"enum": [
0
]
}
}
}
}
]
},
"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"
},
"TaskStatusResponseBodySingleUrlResultsV2": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "この結果をダウンロードする URL。有効期間は 2 時間です",
"example": "https://example.com/sample-result-url"
}
}
},
"TaskStatusResponseV2": {
"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": null
}
}
},
"$ref": "#/components/schemas/TaskStatusResponseBodySingleUrlResultsV2"
}
},
"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"
}
}
}
}
}
}
}
}
}