Character Swap Overview

Overview

Character Swap puts a character created with the Character API into a customer-supplied video. You send an Instagram, TikTok, Threads or YouTube Shorts link — or a direct video URL — plus a character_id, and the person in the video is replaced by your character while the camera, motion, timing and (by default) the original audio are preserved.

Base URL: https://api.goodtake.ai/v1

Endpoints

Requirements

• The character must have a completed sheet — Character API status ready, or at least a finished sheet image. Otherwise the create returns 422.
• The source video has a maximum length, and it depends on the model in use — currently 4–30 seconds. The ceiling is a provider video-edit constraint, and swaps do not all run on the same provider, so read GET /character-swap/limits rather than hardcoding a number. The window is checked twice: an early advisory reject from the scraper's metadata, and an authoritative probe during ingest.
• There is also a minimum frame size, which varies with the model for the same reason. limits reports the current one.

Limits

GET /character-swap/limits returns the constraints a source video must satisfy right now:

{
  "model": "dreamina-seedance-2-5-260628",
  "min_source_seconds": 4,
  "max_source_seconds": 30,
  "min_billable_seconds": 4,
  "depth_guided_max_seconds": 15,
  "trim_to_seconds": 0,
  "depth_guided": false,
  "resolutions": ["480p", "720p", "1080p"]
}

min_billable_seconds is a pricing floor, not a gate: a shorter source is accepted and billed as that length.

trim_to_seconds is the length a longer source is cut to, or 0 when nothing is trimmed. It is 0 on this API: trimming only happens where depth guidance runs, and depth guidance is an in-app feature. Where it is non-zero, a source longer than it is still accepted — its first trim_to_seconds are swapped, and the depth pass is kept rather than dropped to fit the extra length.

depth_guided is false on this API for the same reason, so max_source_seconds here is the model's full window. depth_guided_max_seconds is reported for reference only: it is the ceiling that would apply if depth were in use, which is half the window, because a depth track is a second reference clip the same length as your video and the provider budgets reference video as a total across clips. Check a video against these before you submit it — the create returns 202 immediately and a too-long source only surfaces as a failed swap after the video has been fetched and processed.

Supported sources

Social hosts are classified by hostname, not by path, and resolved through a per-platform resolver. Direct video URLs skip that step entirely.

Cost

One swap = one Seedance 2.5 video generation, charged on completion. Cost is token-based and scales with source duration and resolution — a swap bills tokens for the source clip and the generated output, so cost is roughly 2 × duration × the per-second token rate.

At current settings:

Quote before you create

GET /v1/character-swap/estimate?resolution=1080p&duration_seconds=10

curl -s "https://api.goodtake.ai/v1/character-swap/estimate?resolution=720p&duration_seconds=12" \
  -H "Authorization: Bearer $GOODTAKE_API_KEY" | jq .

{
  "estimated_cost": 223,
  "resolution": "720p",
  "duration_seconds": 12,
  "model": "dreamina-seedance-2-5-260628"
}

Durations under the provider's 4-second billing minimum are priced as 4s. Durations over 30s return 422.

Where the quote shows up

Relationship to the Image API

Swap generations are visible in GET /image/generations — billed rows stay visible — but with an empty prompt, which is the only thing keeping the compiled prompt off the wire.

Explore