{"templateId":"openapi_docs","sharedDataIds":{"openAPIDocsStore":"oas-reference/ai_photo_background_change.yaml","sidebar":"sidebar-sidebar.yaml__reference_ai_photo_background_change"},"props":{"definitionId":"reference/ai_photo_background_change.yaml","dynamicMarkdocComponents":[],"baseSlug":"/reference/ai_photo_background_change","seo":{"title":"AI Photo Background Change","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"itemId":"","disableAutoScroll":true,"metadata":{"type":"openapi","title":"AI Photo Background Change","description":"# Overview\nThe AI Photo Background Change tool enhances images by isolating the subject from the original background, enabling a wide range of applications including product-focused use cases in business.\n\nThis API enables developers to replace the background using custom prompts.\n\n**Sample Usage**\n\nBefore:\n![](https://yce.makeupar.com/assets/images/sod/banner/change/yce-topbanner-dt-before.jpg)\n\nAfter:\n![](https://yce.makeupar.com/assets/images/sod/banner/change/yce-topbanner-dt-after.jpg)\n\n\nBefore:\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_change_bg_s5_poster_before_0753db3e02.jpg)\n\nAfter:\n![](https://bcw-media.s3.ap-northeast-1.amazonaws.com/yce_change_bg_s5_poster_after_7fb288fde2.jpg)\n\n---\n\n## Integration Guide\n\n**1. Upload Image**\n\nRequest upload URLs and file IDs via:\n\n```\nPOST /s2s/v2.0/file/bg-replace-v2\n```\n\nUpload the image using the returned URL.\nAlternatively, provide a publicly accessible image URL hosted on your own storage.\n\n\n**2. Execute Analysis Task**\n\n```\nPOST /s2s/v2.0/task/bg-replace-v2\n```\n\nSubmit the task using file IDs or image URLs as input, along with the desired background prompt.\nThe response returns a task_id for tracking and retrieving the result.\n\n\n**3. Retrieve Task Result**\n\n```\nGET /s2s/v2.0/task/bg-replace-v2/{task_id}\n```\n\nUse the task ID to track status and obtain results.\n\n[Webhooks](/develop/webhook.md) can be configured to receive asynchronous notifications on task completion with a success or error status. Polling is also supported by repeatedly calling the task endpoint until the status is updated from running to success or error.\n\nUsage is only charged when the task completes successfully.\n\n---\n\n## File Specs & Errors\n\n* Supported Formats & Dimensions\n\n|AI Feature|Supported Dimensions|Supported File Size|Supported Formats|\n|  ----  | ----  | ----  | ----  |\n| AI Photo Background Change | The length of the longer side shall not exceed 4096 pixels. | < 10MB | jpg/jpeg/png |\n\n* Error Codes\n\n|Error Code|Description|\n|  ----  | ----  |\n| exceed_max_filesize |\tThe input file size exceeds the maximum allowed limit. |\n| size_mismatch_on_input_image_and_mask | The input image size must match the input mask image dimensions. |\n| invalid_parameter | Invalid parameter value. The request parameter is missing, in an invalid format, or contains an unsupported value.|\n\n* Environment & Dependency\n\n| Sample Code Language / Tool | Recommended Runtime Versions |\n|---|---|\n| cURL | - bash >= 3.2</br>   - curl >= 7.58 (modern TLS/HTTP support)</br>   - jq >= 1.6 (robust JSON parsing) |\n| Node.js (JavaScript) | Node >= 18 (for global fetch) |\n| JavaScript | - Chrome / Edge >= 80</br>   - Firefox >= 74</br>   - Safari >= 13.1 |\n| PHP | PHP >= 7.4 (for modern TLS/compat), ext-curl (recommended) or allow_url_fopen=On + ext-openssl, ext-json |\n| Python | Python >= 3.10 (for f-strings), requests >= 2.20.0 |\n| Java | Java 11+ (for HttpClient), Jackson Databind >= 2.12.0 |\n"},"compilationErrors":[],"markdown":{"partials":{},"variables":{"rbac":{"teams":["anonymous"]},"user":{},"remoteAddr":{"hostname":"docs.perfectcorp.com","port":4000,"ipAddress":"216.73.217.22"},"lang":"default_locale","env":{"PUBLIC_REDOCLY_BRANCH_NAME":"master"}}},"pagePropGetterError":{"message":"","name":""}},"slug":"/reference/ai_photo_background_change","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}