Run an AI photo Background Change V2 task.

Request

AI tasks are asynchronous. Prefer webhook-based completion handling when the feature supports webhooks. Configure your webhook endpoint, verify webhook signatures, and use the received task_id to query the task result after a success or error notification. See the webhook integration guide for setup and verification details.

If webhooks are not supported or cannot be used in your integration, implement polling. After submitting an AI task, poll the status endpoint at regular intervals (e.g., every 10 seconds) until the task status is success or error.

Security

BearerAuthenticationV2

Bodyapplication/jsonrequired

Any of:

typestring

How the background is generated. With prompt (the default), the background is generated from prompt. With template, the background is generated from the predefined template specified by template_id, and prompt is ignored.
Note: If the type is set to prompt but no prompt is provided and a template_id is supplied, the template_id will be ignored and the system will apply the default configuration. Likewise, if the type is set to template but no template_id is provided, the default template will be used regardless of whether a prompt is supplied.

Default:"prompt"

Enum:"prompt""template"

promptstring

Prompt to generate image background.

Example:"A sunny beach with palm trees."

template_idstring

ID of the template. List predefined templates first, and use the id of a template.

Example:"nature_cherryblossom"

src_file_urlstringrequired

Url of the file to run task. The url should be publicly accessible.

Example:"https://example.com/selfie.jpg"

POST

/s2s/v2.0/task/bg-replace

curl -i -X POST \
  https://yce-api-01.makeupar.com/s2s/v2.0/task/bg-replace \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "src_file_url": "https://example.com/selfie.jpg",
    "type": "prompt",
    "prompt": "A sunny beach with palm trees.",
    "template_id": "nature_cherryblossom"
  }'

Responses

Successful execution of the task

Bodyapplication/json

statusinteger

Response status

Example:200

dataobject

Response

{
  "status": 200,
  "data": {
    "task_id": "grH0CvsgXuAIHLUzD0V1Ol34hoet3R1tvdbtiVHrDb6_UqCLKIejAIajwxrhOAfe"
  }
}