Introduction
What this endpoint does
It repairs one video in one of two modes: decompress removes macroblocks, ringing, banding and color bleed; deblur sharpens footage that is out of focus. The picture keeps its framing, motion, length and audio.
Inputs that matter
video_url is the clip, up to 120 seconds. restore_mode picks the repair, resolution the output size (never larger than the source). prompt and seed are optional.
What you get back
One MP4 with the source aspect ratio, frame rate and sound track.
| Field | Value |
|---|---|
| Input | Video |
| Output | Video |
| Endpoint | Video edit |
| Modes | Decompress (encoding damage) or deblur (soft focus) |
| Optional | Scene description and seed |
| Billing | Per second of source by resolution, 3-second minimum |
Key features & highlights
Macroblocks gone, faces rebuilt
We squeezed a 4-second greenhouse clip down to 116 kbps until the woman's face broke into blocks. Decompress mode returned a clean 854×480 clip with her curls, smile and the orchids sharp again, at the same length and frame rate.
A soft two-shot pulled back into focus
A wine-cellar conversation blurred as if the lens had missed focus came back with crisp faces, hair and wooden barrels. Both people kept their positions and movements.
Restore first, upscale second
Restoration works at or below the source size. If the repaired clip also needs to be bigger, send it on to Video Upscaler; enlarging a blocky clip only makes the blocks bigger.
Request parameters
| Parameter | Required | Description |
|---|---|---|
video_url | Yes | The clip to restore, up to 120 seconds: an MP4 or WebM upload, or a direct link to the file. Longer clips are refused at submission and not charged. at least 1 characters |
restore_mode | No | decompress (default) removes macroblocks, ringing, banding and color bleed from low-bitrate video. deblur sharpens footage that is out of focus; it does not fix motion blur. |
prompt | No | Optional. A short description of what the video shows, such as "a man and a woman talking in a wine cellar", to help keep the right details. at most 1000 characters |
resolution | No | Output resolution: 480p, 720p (default) or 1080p. The aspect ratio is kept and the output is never larger than the source. |
seed | No | Optional whole number for repeatable results; leave it empty for a random seed. Does not change the price. |
Pricing
Billed per second of the source clip at the selected output resolution, rounded up to the whole second, with a 3-second minimum. Clips longer than 120 seconds are refused at submission. The mode, prompt and seed do not change the price. Failed requests are not charged.
| Specification | Price |
|---|---|
| $0.024 / second |
| $0.048 / second |
| $0.12 / second |
Use cases
Rescuing re-shared clips
Videos that went through several apps and re-uploads pick up blocks and smearing. Decompress mode cleans faces, hair and textures back up.
Saving a soft take
When autofocus hunted or the subject stepped out of the focus plane, deblur mode can recover a usable take without a reshoot.
Before upscaling
Restore first at the source size, then send the clean clip to Video Upscaler if it needs to go to 1080p or 4K.
Prompt guide & pro tips
Pick the mode that matches the damage
Use decompress for macroblocks, banding and color bleed from heavy compression. Use deblur for footage that is soft because the lens missed focus; it does not fix motion blur.
Set the output resolution
Choose 480p, 720p or 1080p. The aspect ratio is kept and the output is never larger than the source, so pick a resolution at or below your clip's height; the price follows the resolution you choose.
Describe the scene if details matter
An optional prompt such as "a woman with curly hair in a greenhouse full of orchids" helps the model keep the right details. Add seed to repeat a result.
Introduction
Video Restorer cleans up damaged footage without changing what happens in it. Choose decompress for clips that were squeezed by low bitrates and repeated re-uploads, or deblur for clips where the lens missed focus. Subjects, framing and motion stay where they were.
Request
{
"video_url": "https://example.com/clip.mp4",
"restore_mode": "decompress",
"resolution": "720p",
"prompt": "a woman with curly hair in a greenhouse full of orchids"
}
Only video_url is required. restore_mode defaults to decompress and resolution to 720p. The aspect ratio is preserved and the output is never larger than the source, so a 480p clip comes back at 480p even if you ask for more.
What we saw in testing
We compressed a 4-second 854×480 greenhouse clip to 116 kbps, enough to turn the woman's face into blocks. In decompress mode at 480p it came back after about 55 seconds with her face, curls and the orchids clean, still 4 seconds at 24 fps with the stereo audio. A 4-second wine-cellar clip blurred to imitate missed focus came back in deblur mode after about 72 seconds with sharp faces and barrels.
Task flow
The call is asynchronous: create the task, poll until it finishes, then download the MP4 from SpicyAPI storage. Billing is per second of the source at the resolution you chose, and failed requests are not charged.
Tips
- Pick a
resolutionat or below the source height; a higher setting costs more without adding pixels. debluris for focus blur. Motion blur and shaky footage are outside what it fixes.- To make a repaired clip bigger, send it to Video Upscaler (
/models/video-upscaler-v1) afterwards.
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": "spicyapi/video-restorer-v1/video-edit",
"input": {
"resolution": "720p",
"restore_mode": "decompress",
"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.


