{"templateId":"api_docs","sharedDataIds":{"apiDocsStore":"api-docs-reference/ai_photo_background_blur.yaml","sidebar":"sidebar-reference/sidebars.yaml"},"props":{"definitionId":"reference/ai_photo_background_blur.yaml","settings":{"baseUrlPath":"/reference/ai_photo_background_blur"},"disableAutoScroll":true,"seo":{"title":"AI Photo Background Blur","description":"YouCam API documentation by Perfect Corp. Learn how to use Skin analysis API, Virtual try-on API, Image editing API, and Video generative AI APIs.","siteUrl":"https://docs.perfectcorp.com","keywords":"AI Skin Analysis, AI Clothes, AI Hairstyle, AI Outfits","image":"/assets/favicon.cd6fa4d833b2a573b3c6dae68386b293da205b203402cb0c97b80bd2acc07ea2.8351e24f.png"},"dynamicMarkdocComponents":[],"metadata":{"type":"openapi","title":"AI Photo Background Blur","version":"","description":"# Overview\nThe bokeh effect is a popular photographic technique used to blur the background of a photo and bring the subject into focus. It adds an artistic touch to a photograph, making it look more professional and eye-catching.\n\nCreate professional-looking photos with the AI Photo Background Blur API, which automatically isolates subjects and applies a natural background blur to draw attention where it matters most.\n\n\n**Sample Usage Scenarios:**\n\n* Portrait Enhancement\nApply a natural bokeh effect to make subjects stand out and improve the visual quality of profile or portrait photos.\n\n    Before:\n    ![](https://yce.makeupar.com/assets/images/sod/banner/blur/yce-topbanner-dt-before.jpg)\n\n    After:\n    ![](https://yce.makeupar.com/assets/images/sod/banner/blur/yce-topbanner-dt-after.jpg)\n\n* Professional Headshots\nCreate studio-like background blur effects from standard photos for business profiles and corporate directories.\n\n    Before:\n    ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_blur_bg_s3_poster_1_50a314e3f9.jpg)\n\n    After:\n    ![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_blur_bg_s3_poster_2_afb0548cb7.jpg)\n\n---\n\n## Integration Guide\n\n**Input Requirements & Processing Criteria:**\n\n- Upload an image containing a clear, prominent foreground subject.\n- The image's longest side must not exceed **4,096 px**.\n- The source file size must be under **10 MB**.\n- At least one clearly visible foreground subject is required.\n- Only single-subject analysis is supported. If multiple people are present, the API automatically selects the subject with the largest visible area.\n\n\n**Workflow:**\n\n1. Call the File API.\n2. Retrieve the signed upload URL from the response.\n3. Upload the actual image to the returned URL.\n4. Create an AI task.\n5. Setup a Webhook or Poll the task status until completion.\n6. Download the generated result image when processing is successful.\n\n---\n\n**Step 1 — Upload File Metadata Using the File API**\n\nUse `POST /s2s/v2.0/file` to create a file record and receive upload details for the source image.\n\n```bash\ncurl --request POST \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/file \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'content-type: application/json' \\\n  --data '{\n    \"files\": [\n      {\n        \"content_type\": \"image/jpg\",\n        \"file_name\": \"full_body_photo_01_3dbd1b6683.jpg\",\n        \"file_size\": 547541\n      }\n    ]\n  }'\n```\n\n**File API Sample Response:**\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"files\": [\n      {\n        \"content_type\": \"image/jpg\",\n        \"file_name\": \"full_body_photo_01_3dbd1b6683.jpg\",\n        \"file_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud\",\n        \"requests\": [\n          {\n            \"method\": \"PUT\",\n            \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\",\n            \"headers\": {\n              \"Content-Length\": \"547541\",\n              \"Content-Type\": \"image/jpg\"\n            }\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n---\n\n**Step 2 — Retrieve File API Response Details**\n\nThe response contains:\n\n| Field | Description |\n| --- | --- |\n| `file_id` | Identifier used to create the AI task. |\n| `requests.url` | Signed URL for uploading the actual image file. |\n| `requests.method` | Upload method, usually `PUT`. |\n| `requests.headers` | Required headers for the upload request. |\n\n---\n\n**Step 3 — Upload Image to Provided URL**\n\nUse the `requests.url` from the File API response to upload the source image.\n\n```bash\ncurl --location --request PUT 'https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...' \\\n  --header 'Content-Type: image/jpg' \\\n  --header 'Content-Length: 547541' \\\n  --data-binary @'./full_body_photo_01_3dbd1b6683.jpg'\n```\n\n---\n\n**Step 4 — Create an AI Task**\n\nUse `POST /s2s/v2.0/task/bg-blur` to create an AI task.\n\n| Parameter | Description | Example |\n| --- | --- | --- |\n| `src_file_id` | File ID returned from the File API upload flow. Required when using uploaded-file workflow. | `\"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9/13W5TOD8/u/FfjK3xgCQ+hRt9MJXBFaud\"` |\n| `src_file_url` | Direct URL of the source image. Use this alternative to `src_file_id`. | `\"https://example.com/selfie.jpg\"` |\n| `intensity` | Blue intensity. 0 means no blur, and 100 means the maximum blur. | 50 |\n\n**Example Request:**\n\n```javascript\nconst resp = await fetch(\n  'https://yce-api-01.makeupar.com/s2s/v2.0/task/bg-blur',\n  {\n    method: 'POST',\n    headers: {\n      'Content-Type': 'application/json',\n      Authorization: 'Bearer <YOUR_TOKEN_HERE>'\n    },\n    body: JSON.stringify({\n      src_file_url: 'https://example.com/selfie.jpg',\n      intensity: 50\n    })\n  }\n);\n\nconst data = await resp.json();\nconsole.log(data);\n```\n\n**AI Task API Response:**\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"task_id\": \"SaGaqpDgKwFrVBgMpQMA3HY0LeqdT9_13W5TOD8_u_GPi6NqQ3dhlmN-6ntFwhzT\"\n  }\n}\n```\n\n---\n\n**Step 5 — Setup a Webhook or Poll for Task Result**\n\nSee the [webhook integration guide](/develop/webhook.md) for setup and verification details.\n\nFor polling, use the returned `task_id` to check task status.\n\n```bash\ncurl --request GET \\\n  --url https://yce-api-01.makeupar.com/s2s/v2.0/task/bg-blur/<YOUR_TASK_ID> \\\n  --header 'Authorization: Bearer YOUR_API_KEY' \\\n  --header 'content-type: application/json'\n```\n\n---\n\n**Step 6 — Retrieve Result Image**\n\nWhen processing is successful, the response includes a download URL in `data.results.url`.\n\n```json\n{\n  \"status\": 200,\n  \"data\": {\n    \"error\": null,\n    \"results\": {\n      \"url\": \"https://yce-us.s3-accelerate.amazonaws.com/demo/ttl30/...signature...\"\n    },\n    \"task_status\": \"success\"\n  }\n}\n```\n\n**Invalid API Key Response:**\n\nIf the access token is invalid, the API returns a `401` response.\n\n```json\n{\n  \"status\": 401,\n  \"error\": \"Unauthorized\",\n  \"error_code\": \"InvalidAccessToken\"\n}\n```\n\n---\n\n## File Specs & Errors\n\n**File Specifications:**\n\n| Specification | Requirement |\n| --- | --- |\n| Image type | The image must contain one clear and prominent foreground subject or person. |\n| Maximum long-side resolution | Long side must not exceed **4096 px**. |\n| File size limit | Must be less than **10 MB**. |\n| Supported formats | `jpg`, `png`. |\n\n**Error Codes:**\n\n| Error Code | Description |\n| --- | --- |\n| `exceed_max_filesize` | The source image exceeds the maximum allowed dimensions or file size. The long side must not exceed 4096 px, and the file size must remain below 10 MB. |\n| `error_nsfw_content_detected` | Potential NSFW content was detected in the source image or generated result image. |\n| `invalid_parameter` | Invalid parameters were provided for source keys, destination keys, actions, mode values, intensity levels, or task configuration. |\n| `error_download_image` | The source image could not be downloaded successfully. |\n| `error_decode_image` | The source image could not be decoded successfully. |\n\n**Environment & Dependencies:**\n\n| Tool / Language | Recommended Runtime Versions |\n| --- | --- |\n| cURL | Bash ≥ 3.2; curl ≥ 7.58 with modern TLS/HTTP support; jq ≥ 1.6 for robust JSON parsing. |\n| Node.js | Node ≥ 18 for global `fetch` support. |\n| JavaScript Browser Support | Chrome / Edge ≥ 80, Firefox ≥ 74, Safari ≥ 13.1. |\n| PHP | PHP ≥ 7.4 with modern TLS compatibility; ext-curl recommended or `allow_url_fopen=On` with OpenSSL and JSON support. |\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## Unit Consumption\n\n| AI Feature | Unit Consumed |\n|---|---|\n| AI Photo Background Blur V2.0 | 1 |\n\n---\n"},"compilationErrors":[],"markdown":{"partials":{},"variables":{"rbac":{"teams":["anonymous"]},"user":{},"remoteAddr":{"hostname":"docs.perfectcorp.com","port":4000,"ipAddress":"216.73.216.26"},"lang":"default_locale","env":{"PUBLIC_REDOCLY_BRANCH_NAME":"master"}}},"pagePropGetterError":{"message":"","name":""}},"slug":"/reference/ai_photo_background_blur","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}