# 背景ぼかし # 概要 背景ぼかし API では、写真の背景をぼかします。 背景ぼかし API で、被写体を自動的に切り出し、背景をぼかします。 **主な利用シーン:** * ポートレート強化 ボケ効果を適用して被写体を際立たせます。 Before: ![](https://yce.makeupar.com/assets/images/sod/banner/blur/yce-topbanner-dt-before.jpg) After: ![](https://yce.makeupar.com/assets/images/sod/banner/blur/yce-topbanner-dt-after.jpg) * プロフェッショナルな証明写真 標準的な写真からスタジオ風の背景ぼかし効果を作成します。 Before: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_blur_bg_s3_poster_1_50a314e3f9.jpg) After: ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_blur_bg_s3_poster_2_afb0548cb7.jpg) --- ## 統合ガイド **入力要件と処理基準:** - 明確で目立つ前景の被写体を含む画像をアップロードします。 - 画像の長辺は **4,096 px** を超えてはいけません。 - ソースファイルサイズは **10 MB** 未満である必要があります。 - 少なくとも 1 つの明確に視認できる前景の被写体が必要です。 - 単一被写体の分析のみサポートされています。複数の人物が存在する場合、API は可視面積が最大の被写体を自動的に選択します。 **ワークフロー:** 1. File API を呼び出します。 2. レスポンスから署名付きアップロード URL を取得します。 3. 返された URL に実際の画像をアップロードします。 4. AI タスクを作成します。 5. Webhook を設定するか、完了するまでタスクステータスをポーリングします。 6. 処理が成功したら、生成された結果画像をダウンロードします。 --- **ステップ 1 — File API を使用してファイルメタデータをアップロードする** `POST /s2s/v2.0/file` を使用してファイルレコードを作成し、ソース画像のアップロード詳細を取得します。 ```bash curl --request POST \ --url https://yce-api-01.makeupar.com/s2s/v2.0/file \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'content-type: application/json' \ --data '{ "files": [ { "content_type": "image/jpg", "file_name": "full_body_photo_01_3dbd1b6683.jpg", "file_size": 547541 } ] }' ``` **File API レスポンス例:** ```json { "status": 200, "data": { "files": [ { "content_type": "image/jpg", "file_name": "full_body_photo_01_3dbd1b6683.jpg", "file_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud", "requests": [ { "method": "PUT", "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...", "headers": { "Content-Length": "547541", "Content-Type": "image/jpg" } } ] } ] } } ``` --- **ステップ 2 — File API レスポンスの詳細を取得する** レスポンスには以下が含まれます: | フィールド | 説明 | | --- | --- | | `file_id` | AI タスクの作成に使用される識別子。 | | `requests.url` | 実際の画像ファイルをアップロードするための署名付き URL。 | | `requests.method` | アップロードメソッド。通常は `PUT`。 | | `requests.headers` | アップロードリクエストに必要なヘッダー。 | --- **ステップ 3 — 提供された URL に画像をアップロードする** File API レスポンスの `requests.url` を使用して、ソース画像をアップロードします。 ```bash curl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \ --header 'Content-Type: image/jpg' \ --header 'Content-Length: 547541' \ --data-binary @'./full_body_photo_01_3dbd1b6683.jpg' ``` --- **ステップ 4 — AI タスクを作成する** `POST /s2s/v2.0/task/bg-blur` を使用して AI タスクを作成します。 | パラメータ | 説明 | 例 | | --- | --- | --- | | `src_file_id` | File API アップロードフローから返されるファイル ID。アップロードファイルワークフローを使用する場合に必須。 | `"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud"` | | `src_file_url` | ソース画像の直接 URL。`src_file_id` の代替として使用します。 | `"https://example.com/selfie.jpg"` | | `intensity` | ぼかしの強度。0 はぼかしなし、100 は最大ぼかしを意味します。 | 50 | **リクエスト例:** ```javascript const resp = await fetch( 'https://yce-api-01.makeupar.com/s2s/v2.0/task/bg-blur', { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: 'Bearer ' }, body: JSON.stringify({ src_file_url: 'https://example.com/selfie.jpg', intensity: 50 }) } ); const data = await resp.json(); console.log(data); ``` **AI タスク API レスポンス:** ```json { "status": 200, "data": { "task_id": "SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT" } } ``` --- **ステップ 5 — Webhook の設定またはタスク結果のポーリング** 設定および検証の詳細については、[Webhook 統合ガイド](../develop/webhook.md) を参照してください。 ポーリングの場合は、返された `task_id` を使用してタスクステータスを確認します。 ```bash curl --request GET \ --url https://yce-api-01.makeupar.com/s2s/v2.0/task/bg-blur/ \ --header 'Authorization: Bearer YOUR_API_KEY' \ --header 'content-type: application/json' ``` --- **ステップ 6 — 結果画像を取得する** 処理が成功すると、レスポンスの `data.results.url` にダウンロード URL が含まれます。 ```json { "status": 200, "data": { "error": null, "results": { "url": "https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature..." }, "task_status": "success" } } ``` **無効な API キーのレスポンス:** アクセストークンが無効な場合、API は `401` レスポンスを返します。 ```json { "status": 401, "error": "Unauthorized", "error_code": "InvalidAccessToken" } ``` --- ## ファイル仕様とエラー **ファイル仕様:** | 仕様 | 要件 | | --- | --- | | 画像タイプ | 画像には、1 つの明確で目立つ前景の被写体または人物が含まれている必要があります。 | | 長辺の最大解像度 | 長辺は **4096 px** を超えてはいけません。 | | ファイルサイズ制限 | **10 MB** 未満である必要があります。 | | サポート形式 | `jpg`, `png`。 | **エラーコード:** | エラーコード | 説明 | | --- | --- | | `exceed_max_filesize` | ソース画像が許容される最大寸法またはファイルサイズを超えています。長辺は 4096 px を超えてはならず、ファイルサイズは 10 MB 未満である必要があります。 | | `error_nsfw_content_detected` | ソース画像または生成された結果画像に潜在的な NSFW コンテンツが検出されました。 | | `invalid_parameter` | ソースキー、宛先キー、アクション、モード値、強度レベル、またはタスク設定に対して無効なパラメータが提供されました。 | | `error_download_image` | ソース画像を正常にダウンロードできませんでした。 | | `error_decode_image` | ソース画像を正常にデコードできませんでした。 | **環境と依存関係:** | ツール / 言語 | 推奨ランタイムバージョン | | --- | --- | | cURL | Bash ≥ 3.2; curl ≥ 7.58 (モダンな TLS/HTTP サポート付き); jq ≥ 1.6 (堅牢な JSON 解析用)。 | | Node.js | グローバル `fetch` サポートのため Node ≥ 18。 | | JavaScript ブラウザサポート | Chrome / Edge ≥ 80, Firefox ≥ 74, Safari ≥ 13.1。 | | PHP | モダンな TLS 互換性のため PHP ≥ 7.4; ext-curl を推奨、または OpenSSL および JSON サポート付きで `allow_url_fopen=On`。 | | Python | f-strings のため Python ≥ 3.10; requests ≥ 2.20.0。 | | Java | HttpClient のため Java 11+; Jackson Databind ≥ 2.12.0。 | --- ## ユニット消費量 | AI 機能 | 消費ユニット | |---|---| | 背景ぼかし V2.0 | 1 | --- License: Privacy policy ## Servers ``` https://yce-api-01.makeupar.com ``` ## Security ### BearerAuthenticationV2 [object Object] Type: http Scheme: bearer ## Download OpenAPI description - [背景ぼかし](https://docs.perfectcorp.com/_bundle/@l10n/ja/reference/ai_photo_background_blur.yaml) ## V2.0 - [POST /s2s/v2.0/task/bg-blur](https://docs.perfectcorp.com/ja/reference/ai_photo_background_blur/v2.0/paths/~1s2s~1v2.0~1task~1bg-blur/post.md): AI タスクは非同期です。機能ごとに Webhook がサポートされている場合は、Webhook による完了処理を優先します。Webhook エンドポイントを設定し、Webhook 署名を検証したうえで、`success` または `error` の通知が来たら、受け取った `task_id` を使ってタスクの結果を照会します。設定と検証の詳細は [Webhook 統合ガイド](../develo - [GET /s2s/v2.0/task/bg-blur/{task_id}](https://docs.perfectcorp.com/ja/reference/ai_photo_background_blur/v2.0/paths/~1s2s~1v2.0~1task~1bg-blur~1%7Btask_id%7D/get.md)