Kling motion control duration_seconds: it sets the credit hold

duration_seconds on Sume's Kling 3.0 Motion Control is the number of seconds used to reserve credits when the job is admitted. The OpenAPI description gives the formula: ceil of the seconds, times the per-second rate, times the margin. It is required, from 1 to 30, and the output length still follows the driving video.

What does duration_seconds control?

Only the hold at admission. The schema calls it the 'motion video duration seconds used to reserve credits at admit' and adds that output length follows the driving video. The field does not trim or stretch the clip.

The driving video itself is capped at 30 seconds (motion_video_url: maximum 30 seconds), which is why duration_seconds also stops at 30.

What happens if my balance is short?

The 402 response in the OpenAPI says the workspace has a balance row but not enough USD balance for the estimated billable amount, and that no generation job is started. Generation admission says the same in its error table: insufficient_credits is returned before provider work starts.

Because the hold scales with duration_seconds, a 30-second reference needs a bigger balance than a 6-second one even before the clip is made.

What value should I send?

Send the real length of your driving video, rounded the way the schema rounds it: Sume applies the ceiling. Measure the file with your own tooling before you submit rather than guessing.

The schema does not say what happens when the value and the file disagree, so do not rely on a mismatch behaving any particular way. Keep them equal.

Docs say failed jobs and failed queue admission release or refund the reservation, so a rejected request does not keep the hold. Retry safely with the same Idempotency-Key.