Video Colorizer API Documentation

Video Colorizer API Documentation

Playground

Video Colorizer restores natural color to black-and-white, monochrome or faded footage while keeping every subject, the framing and the motion exactly as they are. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

Video Colorizer restores natural, believable color to grayscale, monochrome, or heavily faded video while preserving the original subjects, framing, and motion. Colors are inferred from the footage automatically, and you can optionally use a prompt to guide specific color choices.

Why Choose This?

• Video colorization workflow
  Add natural color to black-and-white, monochrome, or desaturated footage.

• Content-preserving enhancement
  Preserve the original subject identity, framing, background geometry, and motion while adding color.

• Automatic color inference
  Let the model infer realistic colors for skin tones, clothing, foliage, sky, water, buildings, and lighting.

• Prompt-guided color control
  Use prompt to specify colors for important objects, clothing, environments, or lighting.

• Multiple output resolutions
  Choose 480p, 720p, or 1080p while preserving the original aspect ratio.

• Seed support
  Set a seed when reproducible colorization results are needed.

Parameters

How to Use

1. Upload a video — Provide the grayscale, monochrome, faded, or desaturated footage you want to colorize.
2. Add a prompt optional — Describe specific colors when you want to guide the result.
3. Choose target resolution — Select 480p, 720p, or 1080p.
4. Set seed optional — Use a fixed seed when reproducibility is needed.
5. Submit — Generate the colorized video output.

Pricing

Pricing is based on input video duration and selected target_resolution.

Billed duration is rounded up to the next whole second, with a minimum billed duration of 3 seconds and a maximum billed duration of 120 seconds.

Example Costs

prompt and seed do not add separate charges.

Best Use Cases

• Black-and-white video colorization — Add color to monochrome footage while preserving the original video structure.
• Old footage restoration — Restore believable colors to faded or archival-looking clips.
• Creative enhancement — Apply guided color direction to stylized or desaturated videos.
• Social media assets — Prepare colorized clips for posts, reels, ads, and short-form content.
• Historical and documentary workflows — Colorize older footage for presentation and storytelling.
• Restoration preprocessing — Use colorization after basic cleanup or restoration when the source is heavily degraded.

Pro Tips

• Use prompt when specific colors matter, such as red jacket, blue sky, or warm golden street lights.
• Leave prompt empty when you want the model to infer natural colors automatically.
• Name both the object and the color for stronger control.
• Use clean source footage when possible; this endpoint colorizes video and is not primarily a denoiser.
• Keep the same seed when you want to reproduce a colorization result.
• Use 480p for quick tests and 1080p when higher-resolution output is needed.
• For heavily damaged sources, restore or clean the video before colorization.

Limits and Performance

• Maximum processed video length per job: 120 seconds.
• Input beyond 120 seconds is not processed or billed.
• Processing time can vary by resolution and video content.
• Higher output resolutions generally take longer to process.

Notes

• video is required.
• target_resolution defaults to 720p.
• Aspect ratio is preserved.
• Billed duration is rounded up and clamped to 3–120 seconds.
• Very short videos are billed as 3 seconds.
• This endpoint adds or restores color; it does not intentionally change subject identity, framing, or motion.

Related Models

• Video Restorer — Restore damaged footage by reducing compression artifacts or improving soft-focus video.
• Video Colorizer — Add or restore color in video footage for restoration and creative enhancement workflows.
• Video Cleaner — Clean up video noise, artifacts, and visual imperfections for clearer output.
• Video Relighter — Adjust or improve video lighting while preserving the original scene and motion.

Authentication

For authentication details, please refer to the Authentication Guide.

API Endpoints

Submit Task & Query Result

set -euo pipefail

export WAVESPEED_API_KEY="your-api-key"

REQUEST_BODY=$(cat <<'JSON'
{
  "video": "https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4",
  "target_resolution": "720p"
}
JSON
)

# 1. Submit the prediction.
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  -X POST "https://api.wavespeed.ai/api/v3/wavespeed-ai/video-colorizer" \
  -H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}")

TASK=$(printf '%s' "${SUBMIT_RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
PREDICTION_ID=$(printf '%s' "${TASK}" | jq -r '.id // empty')
if [ -z "${PREDICTION_ID}" ]; then
  printf 'Submission response did not contain a prediction id
' >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

# 2. Poll until the prediction finishes.
while true; do
  RESPONSE=$(curl --silent --show-error --fail-with-body \
    "${RESULT_URL}" \
    -H "Authorization: Bearer ${WAVESPEED_API_KEY}")
  RESULT=$(printf '%s' "${RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
  STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')

  case "${STATUS}" in
    completed) printf '%s\n' "${RESULT}" | jq '.outputs'; break ;;
    failed|cancelled|timeout|deleted) printf '%s\n' "${RESULT}" | jq . >&2; exit 1 ;;
    *) sleep 2 ;;
  esac
done

Parameters

Task Submission Parameters

Request Parameters

Response Parameters

Result Request Parameters

Result Response Parameters