Motion control API: animate an image with a driving video

To animate a still image with the motion of a video, send POST /v1/kling/3.0/motion-control with the picture in image_url, the driving clip in motion_video_url, and that clip's length in duration_seconds. Kling 3.0 Motion Control runs as a Sume job, and the output length follows the driving video.

Field rules come from the request schema in the Sume API reference, the OpenAPI document the API reference docs treat as the source of truth, and the shared job lifecycle from the Models overview, read on 2026-09-26. The price is read from Sume's pricing code.

What does Kling 3.0 Motion Control do?

It takes one still, either a public image or a ready avatar, and animates it with the motion of a driving video you supply. The optional prompt only steers appearance details; the motion comes from the driving video. character_orientation decides whose framing wins: video (the default) keeps the driving video's orientation, and image keeps the still's.

Kling 3.0 is also in the video catalog as kling-3 on POST /v1/videos, a separate model id. Sume vs Kling compares calling Kling directly or through Sume. To make a still speak from an audio track instead, see the lip sync API guide.

How do I send a motion control request?

Send an Idempotency-Key with every create. Reusing the key with the same payload returns the original job with idempotency_hit: true, so a retry does not pay twice. This request animates a character still with a 12-second dance clip:

curl -X POST https://api.sume.com/v1/kling/3.0/motion-control \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: motion-clip-001" \
  -d '{
    "image_url": "https://example.com/character.png",
    "motion_video_url": "https://example.com/dance-reference.mp4",
    "duration_seconds": 12,
    "prompt": "Keep the red jacket and the studio backdrop",
    "character_orientation": "video"
  }'

Which fields does the request take?

motion_video_url and duration_seconds are required, plus exactly one visual source.

What is the face-control path?

POST /v1/avatar-1.0/motion-control is the face-control alias of the same endpoint. It takes the same body, and created jobs store the public model id kling/3.0/motion-control. Send avatar_id or avatar_handle in place of image_url to drive a ready avatar's identity still; How to create a reusable AI avatar covers making one.

Both paths also have model-run twins with the same body: POST /v1/models/kling/3.0/motion-control/runs and POST /v1/models/sume/avatar-1.0/motion-control/runs.

How do I get the clip, and what does it cost?

Store job.id, status_url, and result_url from the submit, poll the status, and fetch /result when result_ready is true; media jobs return Sume-hosted artifacts. A webhook_url gets terminal events only: job.completed, job.failed, or job.canceled.

Kling 3.0 Motion Control costs $0.1575 per output second, plus a 5.5% agent fee by default. It is priced per driving-video second, rounded up, and duration_seconds reserves that amount at submit. A 12-second driving video comes to $1.89 before the fee. Failed jobs, and jobs canceled before generation starts, are refunded before capture.

What are the limits?

The schema and the API reference set these rules:

• The driving video must be a fetchable public HTTPS URL of at most 30 seconds, and duration_seconds must be between 1 and 30.
• Exactly one visual source: image_url, or avatar_id / avatar_handle. They are mutually exclusive.
• Localhost, private-network, and non-HTTPS media URLs are rejected before generation submission.
• prompt is capped at 2,000 characters and does not change the motion.
• Provider queue ids are selected by Sume and are not accepted in the request.
• A 402 means the balance cannot cover the estimated amount, and no generation job is started.