Guides

Composition JSON

Reference schema for composition payload used by /v1/jobs/{job_id}/start.

Schema Overview

Composition controls foreground placement on the output canvas.

Use this payload when you want deterministic positioning and model-safe defaults for enterprise workflows.

{
  "composition": {
    "canvas": { "width": 1920, "height": 1080 },
    "foreground": {
      "anchor": "center",
      "scale": 1,
      "offset": { "x": 0, "y": 0 }
    }
  }
}

Field Reference

Field	Type	Description
canvas.width	number	Output width in pixels
canvas.height	number	Output height in pixels
foreground.anchor	string	Anchor point, e.g. center, top-left
foreground.scale	number	Foreground scaling ratio
foreground.offset.x/y	number	Pixel offset from anchor

Background Types

type	Required Fields	Notes
transparent	none	Use WebM/MOV/GIF/WebP/PNG sequence for alpha
color	color (hex or RGB normalized)	Best for MP4 exports
image	image_url	Match aspect ratio to avoid stretching

Full Start Payload Example

curl -X POST https://api.removebgvideo.com/v1/jobs/{JOB_ID}/start \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "pro",
    "text_prompt": "person, clothing accessories, glowing ring",
    "background": { "type": "transparent" },
    "composition": {
      "canvas": { "width": 1920, "height": 1080 },
      "foreground": {
        "anchor": "center",
        "scale": 1,
        "offset": { "x": 0, "y": 0 }
      }
    }
  }'

Quality Guardrails

Prefer representative source clips when tuning model defaults.
Keep input compression moderate to preserve edge details.
Use explicit output format policy for transparent vs non-transparent workflows.
Run A/B validation with the same clip set before changing defaults.

Implementation Checklist

Define payload schema validation in backend before forwarding requests.
Store model/output_format/background settings with each job record.
Add internal quality review for difficult scenes (hair, glass, motion blur).
Create runbook entries for model-specific failure cases.

Anchor Behavior Guidance

Anchor	Typical Use	Risk
center	General subject centering	Can crop tall subjects if scale too high
top-left	UI-like fixed placement	Less natural for portrait content
bottom-center	Talking head over lower third	Can overlap caption area

Composition Validation Rules

Require canvas width/height > 0 and reasonable aspect ratio.
Constrain scale to safe range (e.g. 0.1 - 3.0) in your backend.
Clamp offset values to avoid moving subject outside visible frame.

Image Background

Webhooks