Introduction
Use the asynchronous video-edit endpoint with video_url and edit_target, plus prompt or reference_image_url. The change and background modes give edit_target opposite roles; the public input has no duration control.
| Field | Value |
|---|---|
| Input | Video |
| Output | Video |
| Publisher | ComfyUI |
| Endpoints | video-edit |
| Inputs | Video + target + prompt and/or one reference image |
| Source clip | One take; maximum 15 seconds |
| Resolution | 480p / 540p / 768p by default / 1080p |
| Audio | Source soundtrack preserved |
| Execution | Asynchronous task; billing follows input duration |
Key features & highlights
Separate a colour change from a haircut
The greenhouse trial requested short platinum-blonde hair. The result changed the colour but kept much of the original curl and length. Inspect those attributes independently: a successful colour treatment does not establish that the requested cut has been achieved.
Inspect the neighbour of the target
In the cellar trial, blouse is the selected target and a white linen shirt is the requested replacement. Compare the woman’s garment with the nearby man and the raised glasses. This isolates the wardrobe edit for review without assuming every unselected pixel will be identical.
Name what stays when the setting changes
For background mode, people is the protected target and the prompt describes a night-time rooftop terrace. The cellar example keeps the pair and their glasses while replacing the surroundings with city lights. Check the people’s outlines and the spaces around their arms where the old setting meets the new one.
Request parameters
| Parameter | Required | Description |
|---|---|---|
video_url | Yes | Required source video with no cuts, at most 15 seconds. Its duration is the billing basis; the original audio is kept. at least 1 characters |
edit_target | Yes | Required short label matching the visible element, such as hair, jacket or car; separate multiple targets with commas. In background mode these are the elements to retain. at least 1 characters · at most 120 characters |
edit_mode | No | change (default) replaces the target; background retains it and replaces everything around it. For people kept on a new set, use people as the target. |
prompt | No | Describe the replacement, or the new location in background mode. Supply this or |
reference_image_url | No | Optional visual reference for an outfit, hairstyle, product or location. at least 1 characters |
resolution | No | Select 480p, 540p, 768p (default) or 1080p. Rates rise with the tier; observed landscape outputs measured 864×480, 960×544, 1376×768 and 1920×1056. |
seed | No | Optional whole number from 0 to 2147483647. A shared random source makes comparisons of one changed setting easier, without assuring frame-for-frame repetition. |
Pricing
Object edits charge for input length, rounded up to complete seconds and subject to a 3-second minimum. Resolution changes the second rate; no extra reference-image fee applies. Failures are uncharged, and inputs above 15 seconds are refused before any charge.
| Specification | Price |
|---|---|
| $0.105 / second |
| $0.119 / second |
| $0.14 / second |
| $0.28 / second |
Use cases
Wardrobe alternatives
Compare a leather jacket or linen shirt on an authorised adult performer’s take.
Hair colour studies
Try platinum colouring, while checking whether the original length and curl remain.
A new setting for the cast
Keep people and their glasses while moving a cellar toast to a rooftop at night.
Brand object concepts
Explore a replacement product in an existing shot using an item reference and a clear description; check the result before campaign use.
Prompt guide & pro tips
Confirm your right to edit
Check permission for every face and every uploaded photo or video; all depicted people must be adults aged 18 or over.
Name what changes or stays
Use a short visual label in
edit_target. Select change to replace it, or background to keep it and rebuild the surrounding scene.Describe the destination look
Provide prompt,
reference_image_url, or both. For background mode describe the new location; for a garment, try an isolated item reference plus clear text.Inspect a draft
Submit a short shot and review the target, nearby details and sound after the asynchronous task finishes.
Introduction
Use the asynchronous video-edit endpoint with video_url and edit_target, plus prompt or reference_image_url. The change and background modes give edit_target opposite roles; the public input has no duration control.
How it works
Send the public input for openjutsu/object-swap/video-edit and save the task identifier. Poll its status to a terminal result; on success, obtain the edited video through the task’s result assets. Review that output before using it in your timeline.
Parameters
video_url: Required source video with no cuts, at most 15 seconds. Its duration is the billing basis; the original audio is kept.edit_target: Required short label matching the visible element, such as hair, jacket or car; separate multiple targets with commas. In background mode these are the elements to retain.edit_mode: change (default) replaces the target; background retains it and replaces everything around it. For people kept on a new set, use people as the target.- prompt: Describe the replacement, or the new location in background mode. Supply this or
reference_image_urlat minimum; both may be used together. reference_image_url: Optional visual reference for an outfit, hairstyle, product or location. A single-item image plus descriptive text is advisable; one whole-person reference did not reproduce the intended garment.- resolution: Select 480p, 540p, 768p (default) or 1080p. Rates rise with the tier; observed landscape outputs measured 864×480, 960×544, 1376×768 and 1920×1056.
- seed: Optional whole number from 0 to 2147483647. A shared random source makes comparisons of one changed setting easier, without assuring frame-for-frame repetition.
Billing
Object edits charge for input length, rounded up to complete seconds and subject to a 3-second minimum. Resolution changes the second rate; no extra reference-image fee applies. Failures are uncharged, and inputs above 15 seconds are refused before any charge.
Tips
Name the original item by its visible appearance; write the desired new appearance separately. An item-only reference with text is advisable. If an otherwise valid clip of another length gets a generic failure, trim it to an exact whole-second length before retrying.
Limits
- Object editing still requires permission: use your own face or consenting adults only. Celebrity photos, acquaintances’ images and pictures found online are not authorised merely because you can access them; never impersonate or mislead.
- Supply a single uninterrupted shot no longer than 15 seconds. Multi-shot edits are not supported, so separate the take before submitting it.
- The hair-colour test became platinum but retained the original curls and length despite asking for short hair; colour changes can be easier than reshaping.
- One reference-only attempt using a whole person’s portrait missed the requested garment. Prefer an image of a single item together with an explicit prompt; this is practical guidance, not a verified guarantee.
- For object editing, the platform automatically removes about 4 frames from the start of sources around 5.17 seconds long (5.13–5.20 seconds), leaving exactly 5 seconds for processing. No manual cut is needed: the initial hold covers 6 seconds. Once processing finishes, only 5 seconds count toward the charge and the difference is available again. If a source of another length fails with a generic error, cut it to an exact whole-second length and resubmit; unsuccessful object edits are not charged.
Upload only your own face or faces used with consent, and ensure everyone in all material is at least 18; publicly posted images are not permission. Impersonation and misleading uses are prohibited. The website requires a checked agreement before your first run, and an API call means you accept those same rules. Content that breaches them will be taken down and your account may be suspended.
API quick start
# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
-H "Authorization: Bearer $SPICY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
-d '{
"model": "comfyui/openjutsu-object-swap/video-edit",
"input": {
"edit_mode": "change",
"edit_target": "example",
"resolution": "768p",
"video_url": "https://example.com/reference.mp4"
}
}'
# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
-H "Authorization: Bearer $SPICY_API_KEY"
See the API reference for authentication, the complete schema, polling, and error handling.




