MAKEUGC PLATFORM API · DOCS V2

Background Remover

Remove or replace a video background and download the processed output.

Workflow

Supply a public source video URL.
Choose transparency, a hex color or a replacement image.
Submit and poll for output_url.

This is a separate media-processing feature. The source video is not overwritten. No additional credit charge is applied for this operation.

Send X-Api-Key on every MakeUGC request. POST operations require an active paid subscription and a positive credit balance; custom voice creation also requires a plan with custom voices.

Requests are strict JSON: unknown fields, user_id and webhook_url are rejected. Use polling for jobs; these endpoints do not send webhooks.

The outer status boolean indicates request success. Most jobs use data.status: processing, completed or failed; Upscale documents its own statuses. Poll every 5–10 seconds and require a non-empty result URL (or voice_id) before using output.

API credit units × 100 = website display credits. A timeout, network error or 5xx may occur after acceptance: do not automatically resubmit a paid operation. If submission_unknown is true, check the project or contact support with x-request-id; reserved credits remain held until the result is resolved.

Example IDs and media URLs are placeholders. Replace them with values from your account and accessible media files.

Remove or replace a video background #

POST /background-remover/generate

Remove the background, apply a solid hex color, or composite the subject over an image. Creates a separate project job.

For a replacement image, supply background_image_url. position_x, position_y, width_scale and height_scale apply only to this image mode; background_color and transparent_format apply to removal/color mode.

webm_vp9 and mov_prores produce video; png_sequence and pro_bundle can produce a downloadable archive. Read output_url without assuming an MP4 file.

Request body

Parameter	Description
`project_id` string Optional	Existing project owned by your account. Omit to create one. Allowed: `At least 1 characters; Up to 256 characters`
`video_url` string Required	Public HTTP(S) media URL. Private addresses, credentials and data URIs are not accepted.
`background_image_url` string Optional	Public HTTP(S) media URL. Private addresses, credentials and data URIs are not accepted.
`background_color` string Optional	background color input. Allowed: `Pattern: ^(transparent\|#[0-9a-fA-F]{6})$` Default: `transparent`
`transparent_format` string Optional	transparent format input. Allowed: `webm_vp9 \| mov_prores \| png_sequence \| pro_bundle` Default: `webm_vp9`
`position_x` number Optional	position x input. Allowed: `Minimum -2; Maximum 2` Default: `0`
`position_y` number Optional	position y input. Allowed: `Minimum -2; Maximum 2` Default: `0`
`width_scale` number Optional	width scale input. Allowed: `Maximum 10; Greater than 0` Default: `1`
`height_scale` number Optional	height scale input. Allowed: `Maximum 10; Greater than 0` Default: `1`

Request example

cURL

curl --fail-with-body --max-time 120 -X POST "https://app.makeugc.ai/api/platform/background-remover/generate" \
  -H "X-Api-Key: $MAKEUGC_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "project_id": "project_123",
  "video_url": "https://your-cdn.example/reference.mp4",
  "background_color": "transparent",
  "transparent_format": "webm_vp9"
}'

JavaScript

// Run on your server with Node.js 20+.
const apiKey = process.env.MAKEUGC_API_KEY;
if (!apiKey) throw new Error("Set MAKEUGC_API_KEY first");

const response = await fetch("https://app.makeugc.ai/api/platform/background-remover/generate", {
  method: "POST",
  headers: {
    "X-Api-Key": apiKey,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "project_id": "project_123",
  "video_url": "https://your-cdn.example/reference.mp4",
  "background_color": "transparent",
  "transparent_format": "webm_vp9"
}),
  signal: AbortSignal.timeout(120000),
});
const text = await response.text();
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${text} (request ${response.headers.get("x-request-id")})`);
}
const result = JSON.parse(text);
console.log(result);

Python

# Install the requests package before running.
import os
import requests

payload = {
    "project_id": "project_123",
    "video_url": "https://your-cdn.example/reference.mp4",
    "background_color": "transparent",
    "transparent_format": "webm_vp9"
}

response = requests.post(
    "https://app.makeugc.ai/api/platform/background-remover/generate",
    headers={"X-Api-Key": os.environ["MAKEUGC_API_KEY"]},
    json=payload,
    timeout=120,
)
if not response.ok:
    raise RuntimeError(f"HTTP {response.status_code}: {response.text} "
                       f"(request {response.headers.get('x-request-id')})")
print(response.json())

200 response example

JSON response

{
  "status": true,
  "data": {
    "id": "job_123",
    "project_id": "project_123",
    "status": "processing"
  }
}

All requests require X-Api-Key. See errors & retries for unsuccessful responses.

Get background processing status #

GET /background-remover/status

Poll the MakeUGC data.id, not an upstream provider ID. The completed file or archive is in output_url.

Parameters

Parameter	Description
`id` string · query Required	id input. Allowed: `At least 1 characters; Up to 256 characters`