🕺 Seedance Motion Control API

September 7, 2026 · View on GitHub

The complete developer guide to the Seedance 2 Motion Control and Seedance 2.5 Motion Control APIs — recast an existing performance video (dance, choreography, sports, any blocked movement) with new performers while automatically preserving the original motion, camera work, and location. Covers both endpoints' request/response schemas, integration code, and 20+ curated recast examples.

Seedance Motion Control Powered by MuAPI Stars License: MIT

Table of Contents

What is Seedance Motion Control?

Seedance Motion Control (built on ByteDance's Seed video foundation) recasts an existing performance video with new performers — while automatically preserving:

  • Motion & choreography — every step, gesture, and beat of the original performance
  • Blocking & camera work — framing, camera moves, and cuts stay identical
  • Location — the original room, stage, or outdoor setting is kept intact

You upload a reference video (the performance to preserve) and one or more character reference images (the new performers to recast into it). An optional short prompt can clarify who swaps with whom — if you omit it, roles are inferred automatically from the video and images. This is the same idea popularized by Higgsfield's Genjutsu feature, exposed here as a plain REST API you can call from any stack.

Typical uses: swapping a dance influencer into a viral choreography clip, putting a brand mascot or client's likeness into an existing ad performance, localizing a performance with region-appropriate talent, or generating consistent-motion content variations without re-shooting.

Seedance 2 vs Seedance 2.5 Motion Control

FeatureSeedance 2 Motion ControlSeedance 2.5 Motion Control
Endpointseedance-2-motion-controlseedance-2.5-motion-control
ProviderKinoviSeegen
Cost$1.00 base$1.50 base
Max duration15s30s
Character reference imagesup to 9up to 30
Aspect ratios21:9 16:9 4:3 1:1 3:4 9:1621:9 16:9 4:3 1:1 3:4 9:16 9:21 adaptive
Quality/bitrate controlquality: high / basichigh_bitrate: boolean
Seed control—seed (reproducible generation)
Generate audio✅ (off by default)✅ (off by default)

Both endpoints share the same request shape for prompt, video_url, and images_list — 2.5 simply raises the ceiling on duration and reference-image count, and adds seed/high_bitrate controls.

How It Works

Reference video (performance to preserve)
        +
Character reference image(s) (new performer(s))
        +
Optional prompt ("swap the two dancers with the reference images")
        │
        ▼
   Seedance Motion Control
        │
        ▼
Recast video — same motion, camera, and location; new identities

No manual masking, no motion-capture rig, no per-frame rotoscoping — the model infers subject count and role assignment directly from the reference video and images.

API Reference (MuAPI)

The fastest way to access Seedance Motion Control is through MuAPI — a unified media API gateway with reliable uptime, competitive pricing, and no per-provider account setup.

Get your API key: muapi.ai

x-api-key: YOUR_MUAPI_KEY
Base URL: https://api.muapi.ai/api/v1

1. Seedance 2 Motion Control

Endpoint: POST https://api.muapi.ai/api/v1/seedance-2-motion-control ($1.00 base) Playground: muapi.ai/playground/seedance-2-motion-control

curl --location --request POST "https://api.muapi.ai/api/v1/seedance-2-motion-control" \
  --header "Content-Type: application/json" \
  --header "x-api-key: YOUR_API_KEY" \
  --data-raw '{
      "prompt": "Swap the two dancers with the people in the reference images, keep the same room.",
      "video_url": "https://example.com/source-performance.mp4",
      "images_list": ["https://example.com/performer-1.jpg", "https://example.com/performer-2.jpg"],
      "aspect_ratio": "16:9",
      "duration": 10,
      "quality": "high",
      "generate_audio": false
  }'

Python:

import requests

response = requests.post(
    "https://api.muapi.ai/api/v1/seedance-2-motion-control",
    headers={"x-api-key": "YOUR_API_KEY", "Content-Type": "application/json"},
    json={
        "prompt": "Swap the two dancers with the people in the reference images, keep the same room.",
        "video_url": "https://example.com/source-performance.mp4",
        "images_list": ["https://example.com/performer-1.jpg", "https://example.com/performer-2.jpg"],
        "aspect_ratio": "16:9",
        "duration": 10,
        "quality": "high",
        "generate_audio": False
    }
)
request_id = response.json()["request_id"]

2. Seedance 2.5 Motion Control

Endpoint: POST https://api.muapi.ai/api/v1/seedance-2.5-motion-control ($1.50 base) Playground: muapi.ai/playground/seedance-2.5-motion-control

curl --location --request POST "https://api.muapi.ai/api/v1/seedance-2.5-motion-control" \
  --header "Content-Type: application/json" \
  --header "x-api-key: YOUR_API_KEY" \
  --data-raw '{
      "prompt": "Swap the two dancers with the people in the reference images, keep the same room.",
      "video_url": "https://example.com/source-performance.mp4",
      "images_list": ["https://example.com/performer-1.jpg", "https://example.com/performer-2.jpg"],
      "aspect_ratio": "16:9",
      "duration": 10,
      "seed": -1,
      "high_bitrate": false,
      "generate_audio": false
  }'

Python:

response = requests.post(
    "https://api.muapi.ai/api/v1/seedance-2.5-motion-control",
    headers={"x-api-key": "YOUR_API_KEY", "Content-Type": "application/json"},
    json={
        "prompt": "Swap the two dancers with the people in the reference images, keep the same room.",
        "video_url": "https://example.com/source-performance.mp4",
        "images_list": ["https://example.com/performer-1.jpg", "https://example.com/performer-2.jpg"],
        "aspect_ratio": "16:9",
        "duration": 10,
        "seed": -1,
        "high_bitrate": False,
        "generate_audio": False
    }
)
request_id = response.json()["request_id"]

Polling for Results

Both endpoints return a request_id. Poll until status is completed:

import time, requests

def wait_for_result(request_id, api_key, poll_interval=5, timeout=300):
    start = time.time()
    while time.time() - start < timeout:
        res = requests.get(
            f"https://api.muapi.ai/api/v1/predictions/{request_id}/result",
            headers={"x-api-key": api_key}
        ).json()
        if res["status"] == "completed":
            return res
        elif res["status"] == "failed":
            raise Exception(res.get("error", "Generation failed"))
        time.sleep(poll_interval)
    raise TimeoutError("Generation timed out")

result = wait_for_result(request_id, "YOUR_API_KEY")
output = result.get("output", {})
video_url = output.get("video") if isinstance(output, dict) else output
print(f"Recast video: {video_url}")

Status values: queued, pending, processing, completed, failed, cancelled.

MuAPI Parameters

ParameterTypeOptionsDefaultDescription
video_urlstring (URL)—requiredReference performance video — motion, choreography, blocking, and camera work are preserved
images_listarray (URLs)——Character reference images for the new performer(s), in appearance order. Max 9 (Seedance 2) / 30 (Seedance 2.5)
promptstring—auto-inferredOptional creative brief, e.g. "swap the two dancers with the reference images". Roles are inferred automatically if omitted
aspect_ratiostring16:9 9:16 1:1 4:3 3:4 21:9 (9:21, adaptive on 2.5 only)16:9Output video aspect ratio
durationint4–15 (Seedance 2) / 4–30 (Seedance 2.5)5Duration in seconds
qualitystringhigh / basichighSeedance 2 only. high uses the standard model, basic uses the faster model
seedint-1–4294967295randomSeedance 2.5 only. Reproducible generation seed (-1 = random)
high_bitratebooleantrue / falsefalseSeedance 2.5 only. Higher visual fidelity, larger output file
generate_audiobooleantrue / falsefalseGenerate audio (music/SFX) for the recast video. Off by default — a motion-control recast usually shouldn't have fabricated audio layered over the preserved performance
webhook_urlstring (URL)——Optional webhook to notify on completion

Playground: muapi.ai/seedance-motion-control

Recast Request Guide

The Recast Formula

  1. Reference video — the cleanest possible source: stable camera, clear framing of every performer, minimal occlusion
  2. Character reference image(s) — one clear, front-facing (or 3/4) image per new performer, in the same order they appear in the source video
  3. Prompt (optional) — only needed when role assignment is ambiguous (e.g. 3+ subjects, performers swap positions mid-clip, or you want to target one specific subject and leave others untouched)
[who swaps with whom] + [what stays the same, if you want to be explicit]

Character Reference Image Tips

  • Use a single clear photo per performer — avoid group photos as a single reference
  • Match rough body type/height proportions to the original performer being replaced for the most physically plausible recast
  • Order images_list to match the appearance order of subjects in the source video (leftmost/first-appearing subject first)
  • Higher-resolution, well-lit reference images produce cleaner identity transfer than cropped or low-light photos

Writing the Optional Prompt

Leave prompt empty for a straightforward 1:1 or 2:2 recast — role inference handles it. Add a prompt when you need to:

  • Target a specific subject: "Only replace the dancer on the left with the reference image; keep the other dancer unchanged."
  • Clarify ambiguous grouping: "Swap all three performers with the three reference images, in the order given."
  • Preserve a specific detail: "Swap the lead singer with the reference image, keep the same microphone and stage lighting."

Recast Examples

💃 Solo Dance Recast

Setup: 1 reference video (solo dancer, static camera) + 1 character reference image Prompt: "" (empty — single-subject recast is inferred automatically)

Setup: Solo hip-hop freestyle clip + 1 character reference image Prompt: "Swap the dancer with the person in the reference image, keep the same street location and lighting."

Setup: Solo ballet performance, moving camera + 1 character reference image Prompt: "Replace the dancer with the reference image performer, preserve the camera pan and stage lighting."

👯 Duo / Group Choreography Recast

Setup: 2 reference videos-subjects (duo choreography) + 2 character reference images Prompt: "Swap the two dancers with the people in the reference images, keep the same room."

Setup: 4-person K-pop-style formation clip + 4 character reference images Prompt: "Swap all four performers with the four reference images, in the order given, preserve the formation and camera cuts."

Setup: Partner/couple dance (close contact) + 2 character reference images Prompt: "Replace both partners with the reference images while preserving their exact hold and lead/follow positioning."

🏀 Sports & Physical Action Recast

Setup: Basketball freestyle trick-shot clip + 1 character reference image Prompt: "Swap the player with the reference image, keep the same court and camera angle."

Setup: Skateboarding trick clip, handheld camera + 1 character reference image Prompt: "Replace the skater with the reference image performer, preserve the trick and handheld camera shake."

Setup: Martial arts kata/sparring demo + 2 character reference images Prompt: "Swap both practitioners with the reference images, keep the dojo and the exact sequence of strikes."

🎤 Performance & Stage Recast

Setup: Solo singer on stage, concert lighting + 1 character reference image Prompt: "Swap the singer with the reference image, keep the stage lighting and microphone."

Setup: Band performance, 3 musicians + 3 character reference images Prompt: "Swap all three musicians with the reference images in the order given, keep their instruments and stage positions."

📱 Social/UGC Trend Recast

Setup: Viral TikTok/Reels dance trend clip + 1 character reference image Prompt: "" (empty — let the model infer the single-subject recast)

Setup: Duo lip-sync/trend clip, front-facing camera + 2 character reference images Prompt: "Swap the two people with the reference images, keep the same background and framing."

Advanced Workflows

Reuse the same character reference image(s) across several different source performance videos to place one consistent brand ambassador or spokesperson into multiple existing choreography/trend clips without re-shooting each one.

Localizing a Global Campaign

Take one master performance video and run it through Motion Control once per target market with region-appropriate character reference images, producing localized variants that keep identical choreography, camera work, and pacing.

Clean-Plate Environment Preservation (for ambiguous scenes)

For scenes where the background itself risks being reinterpreted (busy or low-contrast environments), generate a clean environment reference still of the source location (e.g. with an image-editing model) and mention it explicitly in prompt — e.g. "keep the environment exactly as shown, only swap the performers" — to anchor the location more strongly than relying on the source video alone.

Tips & Best Practices

  • Stable source video wins — handheld shake, motion blur, and heavy occlusion in the reference video reduce recast fidelity
  • One subject per reference image — never pass a group photo as a single list entry
  • Match performer count exactly — the number of images_list entries should equal the number of subjects you intend to recast
  • Leave prompt empty for straightforward recasts — over-specifying can conflict with the model's own correct inference
  • Keep generate_audio off unless you specifically want new synthesized audio layered over the preserved performance
  • Use quality: "basic" (Seedance 2) for fast iteration, then re-run the final take on "high"
  • Use seed (Seedance 2.5) to lock in a result you like before trying prompt variations
  • Respect duration ceilings — trim the source video to 15s (Seedance 2) or 30s (Seedance 2.5) before submitting for best fidelity

FAQ

Do I need to write a prompt every time? No — prompt is optional on both endpoints. If omitted, the number of subjects and their roles are inferred automatically from the reference video and images_list.

Can I recast just one performer out of several and leave the rest unchanged? Yes — describe the target explicitly in prompt (e.g. "only replace the dancer on the left") and only include a reference image for that subject.

What happens to the original audio? The source performance's original audio is not automatically carried over. Set generate_audio: true if you want new synchronized audio generated for the recast; otherwise the output video has no audio track by default.

What's the difference between Seedance 2 and Seedance 2.5 Motion Control? 2.5 supports longer clips (up to 30s vs 15s), far more character reference images (30 vs 9), and adds seed/high_bitrate controls. See the comparison table.

Does this work with non-dance performances? Yes — anything with clear blocking and motion works: sports demos, stage performances, physical comedy, martial arts, and general UGC trend clips.

Contributing

PRs welcome! Add recast examples, correct parameters, share API code/SDK snippets, or link to new Seedance Motion Control resources. Open an issue to suggest a new category.

License

MIT