{ "openapi": "3.0.0", "info": { "title": "AI 背景透過", "description": "# 概要\nAI 背景透過では、写真から背景を除去します。\n* 自動背景検出: AI を使用して被写体と背景を識別し、分離します。\n* 高精度編集: 被写体の周囲にクリーンで精密なエッジを提供します。\n* 多様なカテゴリに対応: 人物、製品、動物、車、グラフィックなどに対応します。\n* 他の AI タスクとの連携: 出力ファイル ID を他の AI タスクにチェーンできます。\n\n![](https://plugins-media.makeupar.com/smb/blog/post/2023-11-03/54285311-7c65-4658-9e27-11bf5c8dfe56.jpg)\n\n## 統合ガイド\n* AI 背景透過の実行方法\n1. **ソース画像のリサイズ
**\n サポートされている寸法に合わせて写真をリサイズします。詳細は **[ファイル仕様とエラー](#section/overview/File-Specs-and-Errors)** を参照してください。\n\n2. **ファイル API を使用したファイルのアップロード
**\n ***/s2s/v2.0/file*** API を使用して、対象ユーザーの画像をアップロードします。\n - 画像要件\n - 詳細は **[ファイル仕様とエラー](#section/overview/File-Specs-and-Errors)** を参照してください。\n - ***重要***: ファイル API を呼び出すだけではファイルはアップロードされません。**ファイル API のレスポンスで提供される URL** にファイルを**手動でアップロード**する必要があります。その URL がアップロード先です。次に進む前に、ファイルがそこに正常に転送されたことを確認してください。
\n AI API を呼び出す前に、ファイルが正常にアップロードされていることを確認してください。ファイル API を使用してアップロード URL を取得し、その場所にファイルをアップロードします。アップロードが完了すると、レスポンスに ***file_id*** が返されます。この ID は、そのファイルに関連する AI 機能にアクセスするために使用します。\n\n > **警告:** ファイル API のレスポンスで提供される URL にファイルをアップロードしない場合、AI API の使用時に 500 Server Error / unknown_internal_error または 404 Not Found エラーが発生する可能性があります。\n\n3. **AI タスクの実行
**\n アップロードが完了したら、ファイル ID を指定して POST 'task/sod' を呼び出し、AI タスクを実行して監視用の ***task_id*** を取得します。\n\n4. **Webhook またはポーリングを設定し、タスクが成功またはエラーになるまでステータスを確認する
**\n***task_id*** は、保持期間全体を通じてタスクのステータスを監視するための Webhook の設定やポーリングの実装に使用されます。AI エンジンがタスクを完了するまで、ステータスは running のままです。タスクが running 状態の間は、ユニットは消費されません。処理が完了すると、タスクのステータスは success または error に変わります。\n\n1. **成功時に AI タスクの結果を取得する
**\nエンジンが入力ファイルを正常に処理し、結果の画像を生成すると、タスクは 'success' ステータスに変わります。処理済み画像の URL と、結果画像を再アップロードせずに別の AI タスクにチェーンできる dst_id が得られます。\nユニットはこの場合のみ消費されます。エンジンがタスクの処理に失敗した場合、タスクのステータスは 'error' に変わり、ユニットは消費されません。
\nユニットを控除する際、システムは期限切れに近いものから優先的に控除します。期限日が同じ場合は、最も早い日に取得したユニットから控除されます。\n\n* デモシナリオ:\n一般的な実装ケース:\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/Transparen_Background_aca3cdbd83.jpg)\n\n## 入力と出力\n* 入力\n * `Image`\n- **型:** `image`\n- **説明:** 前景が明確な画像。\n\n実際のアプリケーション（入力）:\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_removal_bg_s4_poster_1_289b8eaf81.png)\n\n---\n\n* 出力\n * `Foreground image`\n- **型:** `image`\n- **説明:** 背景が除去された画像。\n\n実際のアプリケーション（出力）:\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_removal_bg_s4_poster_2_a6bc3c5f6a.png)\n\n## ファイル仕様とエラー\n* 対応フォーマットと寸法\n\n|AI 機能|対応寸法|ファイルサイズ|受け入れ可能な形式|\n| ---- | ---- | ---- | ---- |\n|AI 背景透過|入力画像と出力画像の両方に対する推奨事項と制限は以下の通りです:
解像度: 4096 × 4096 ピクセル（最長辺は 4096 ピクセルを超えてはなりません）|<10MB|JPG および PNG|\n\n* エラーコード\n\n|エラーコード|説明|\n| ---- | ---- |\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_download_video|ソース動画のダウンロードに失敗しました|\n|error_decode_video|ソース動画のデコードに失敗しました|\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|error_multiple_people|ソース画像で複数の人物が検出されました|\n|error_no_shoulder|ソース画像で肩が見えません|\n|error_large_face_angle|アップロードされた画像の顔の角度が大きすぎます|\n|error_hair_too_short|入力された髪が短すぎます|\n|error_unexpected_video_duration|動画の長さが dstDuration と等しくありません|\n|error_bald_image|入力されたヘアスタイルがハゲです|\n|error_unsupport_ratio|入力画像のアスペクト比がサポートされていません|\n|unknown_internal_error|その他|\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/sod": { "post": { "summary": "AI 背景透過タスクを実行します。", "description": "このエンドポイントは背景透過処理を開始します。ファイルアップロード API から取得したファイル ID を指定する必要があります。タスクは非同期で処理され、このレスポンスで返される task_id を使用してステータスを確認できます。\n", "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/sod/{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 authentication' を使用します。ヘッダーに 'API Key' を設定してください: `Authorization:Bearer YOUR_API_KEY`。'Bearer' と 'YOUR_API_KEY' の間にスペースが 1 つあることに注意してください。" } }, "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\n- `exceed_max_filesize` - 入力ファイルサイズが最大制限を超えています\n\n- `invalid_parameter` - 無効なパラメータ値です\n\n- `error_download_image` - ソース画像のダウンロードエラーです\n\n- `error_download_mask` - マスク画像のダウンロードエラーです\n\n- `error_decode_image` - ソース画像のデコードエラーです\n\n- `error_decode_mask` - マスク画像のデコードエラーです\n\n- `error_nsfw_content_detected` - ソース画像に NSFW コンテンツが検出されました\n\n- `error_no_face` - ソース画像に顔が検出されませんでした\n\n- `error_pose` - ソース画像のポーズ検出に失敗しました\n\n- `error_face_parsing` - ソース画像の顔セグメンテーションに失敗しました\n\n- `error_inference` - 推論パイプラインエラーです\n\n- `exceed_nsfw_retry_limits` - NSFW 画像生成を避けるための再試行制限を超えました\n\n- `error_upload` - 結果画像のアップロードエラーです\n\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 タイプです。現在利用可能な値は enum に記載されています。" }, "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。他のタスク実行 API ではこの `file_id` が必要です。" }, "requests": { "type": "array", "description": "以下の `url`、`headers`、`method` を使用してファイルをアップロードします。完了後、`file_id` を使用してタスク実行 API の呼び出しを進めます。", "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" } } }, "BasicRunTaskV2SrcFileUrl": { "title": "src file url でタスクを実行", "type": "object", "required": [ "src_file_url" ], "properties": { "src_file_url": { "type": "string", "description": "タスクを実行するファイルの URL。この URL は公開アクセス可能である必要があります。", "example": "https://example.com/selfie.jpg" } } }, "BasicRunTaskV2SrcFileId": { "title": "src file ID でタスクを実行", "type": "object", "required": [ "src_file_id" ], "properties": { "src_file_id": { "type": "string", "description": "タスクを実行するファイルの ID。ファイルアップロード API からのファイル ID です。", "example": "pfNK5PuRe0MrwLHcGA3DOmB1ahwfXTbYHjv+KoBIxbE=" } } }, "BasicRunTaskV2": { "title": "BasicRunTaskV2", "anyOf": [ { "$ref": "#/components/schemas/BasicRunTaskV2SrcFileUrl" }, { "$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" } } } } }, "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": { "$ref": "#/components/schemas/TaskStatusResponseBodySingleUrlResultsV2" } } } } } }, "responses": { "InvalidParameters": { "description": "無効なリクエストパラメータ", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 400, "description": "レスポンスステータス" }, "error": { "type": "string", "description": "エラーメッセージ", "example": "The operation could not be completed" }, "error_code": { "type": "string", "enum": [ "InvalidParameters" ] } } } } } }, "InvalidApiKey": { "description": "無効な API キー、非アクティブな API キー、または期限切れの API キー", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 401, "description": "レスポンスステータス" }, "error_code": { "type": "string", "enum": [ "InvalidApiKey", "InactiveApiKey", "ExpiredApiKey" ] } } } } } }, "TooManyRequests": { "description": "一定時間内にリクエスト数が多すぎます" }, "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" ] } } }, "TaskTimeout": { "description": "タスクが期待される時間内にレスポンスを返さなかった", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "レスポンスステータス", "example": 500 }, "error_code": { "type": "string", "enum": [ "TaskTimeout" ] } } } } } }, "InvalidTaskId": { "description": "無効なタスク ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "レスポンスステータス", "example": 400 }, "error_code": { "type": "string", "enum": [ "InvalidTaskId" ] } } } } } } } } }