Kling 3.0 Motion Control

Make the character in one image repeat the motion of one 3–30 second video at 720p or 1080p, and choose whether the background comes from the video or the image; the result is up to 10 seconds with image orientation and up to 30 seconds with video orientation.

• Asynchronous: the create call returns a task ID; the video arrives when the task succeeds.
• Two inputs, both required: one character image and one motion video of 3 to 30 seconds. The character in the image performs the motion of the video.
• character_orientation sets what the character faces follow and how long the result can be: at most 10 seconds with image (the default), at most 30 seconds with video.
• There is no duration field: the result is as long as your motion video, up to the limit of the orientation you chose.
• Billed per second of the finished video, settled from the amount held at create, at 720p or 1080p. A failed task costs nothing.

Opens this model in the API Explorer. Enter your BeatAPI API key to create a task: the call is real and is billed to your own balance.

Model IDs

Two models share this endpoint and the same inputs. The values below come straight from the gateway contract; only Kling 3.0 Motion Control accepts background_source.

Endpoint and authentication

POST https://api.beatapi.io/v1/videos/tasks

Send the body as JSON with Content-Type: application/json. Idempotency-Key is optional: send a unique value (at most 255 characters) per logical request and reuse it only to retry that exact body. Within 24 hours a retry with the same key and body returns the first response again with Idempotent-Replayed: true; the same key with a different body returns 409 idempotency_conflict. Responses other than 2xx are not stored, so a retry after a 400 or 402 runs again.

How a request works

Input modes

Request parameters

The gateway also checks these combinations before creating the task:

• exactly one character image and one uploaded motion video of 3 to 30 seconds; with character_orientation image the output is at most 10 seconds

Input media limits

The gateway reads every input before the task is created and refuses one outside these limits with a 400 bad_request that names the input. Nothing is charged.

• Only the motion video is checked against a length limit when the task is created: 3 to 30 seconds, measured from the file header with a 0.1-second tolerance. The message names the input by position, counting from 0 like the field errors: reference_videos[0] is 45 seconds long; this model takes reference video of 3 to 30 seconds.
• A clip whose length cannot be read (the host does not allow byte-range requests, or the file is not an MP4 or MOV) is not refused at this step and is not measured. The create call is refused only when the host answers with an error or an empty file, for example reference_videos[0] could not be downloaded: the URL returned HTTP 404.
• Use image with clips of up to 10 seconds. For a motion video longer than 10 seconds, send character_orientation: "video".
• Image size, format and dimensions are not checked when the task is created.
• Have a local file? Upload it with POST /v1/files (png, jpg, jpeg or webp images up to 50 MB; mp4 or mov video up to 100 MB) and pass the returned data.url.

How the orientation sets the length

There is no duration field. The result is as long as your motion video, and character_orientation caps it.

• The amount is settled when the task finishes from the usage reported for the video that was produced, normally the list rate per second for its length; the difference to the amount held is returned. If no usage is reported, the amount held is charged. See Billing.

Fields this model does not accept

Sending one of these is refused before anything is charged, instead of being ignored:

• duration, aspect_ratio, generate_audio, seed, task_type, output_format, reference_images, reference_audios, quality, sound, watermark and any other field of the other video models → field "duration" is not supported by model kling-3-motion-control (with the field you sent).
• Any field the API does not know at all → unknown field: <name>.

Request examples

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-3-motion-control",
  "prompt": "Keep the singer’s look and outfit; follow the movement of the video.",
  "images": [
    "https://media.beatapi.io/samples/neon-singer.png"
  ],
  "reference_videos": [
    "https://your-cdn.example.com/clips/source.mp4"
  ],
  "resolution": "720p"
}'

Motion transfer

Replace the video link with your own MP4 or MOV of 3 to 30 seconds (there is no public sample video). character_orientation is left out, so image applies and the result is at most 10 seconds.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-3-motion-control",
  "prompt": "Keep the singer’s look and outfit; follow the movement of the video.",
  "images": [
    "https://media.beatapi.io/samples/neon-singer.png"
  ],
  "reference_videos": [
    "https://your-cdn.example.com/clips/source.mp4"
  ],
  "resolution": "720p"
}'

1080p, orientation follows the video

For a clip longer than 10 seconds: video allows a result of up to 30 seconds. Replace the video link with your own clip. A longer result holds more on your balance when the task is created.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-3-motion-control",
  "images": [
    "https://media.beatapi.io/samples/neon-singer.png"
  ],
  "reference_videos": [
    "https://your-cdn.example.com/clips/source.mp4"
  ],
  "resolution": "1080p",
  "character_orientation": "video"
}'

Keep the background of the character image

The result keeps the background of the character image instead of the one in the motion video. Replace the video link with your own clip.

curl --request POST \
  --url https://api.beatapi.io/v1/videos/tasks \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "kling-3-motion-control",
  "images": [
    "https://media.beatapi.io/samples/neon-singer.png"
  ],
  "reference_videos": [
    "https://your-cdn.example.com/clips/source.mp4"
  ],
  "resolution": "720p",
  "background_source": "input_image"
}'

Responses

Create a task (201)

The task object. output is null until the task succeeds. Fields marked “while running” disappear once the task finishes.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "kling-3-motion-control",
    "capability_version": 1,
    "media_type": "video",
    "model": "kling-3-motion-control",
    "status": "queued",
    "stage": "queued",
    "created_at": 1791993600,
    "updated_at": 1791993600,
    "completed_at": null,
    "poll_after_seconds": 8,
    "output": null,
    "usage": {
      "credits_reserved": 1.1,
      "credits_settled": 0,
      "credits_refunded": 0,
      "credits_charged": 1.1,
      "billable_duration_seconds": 10
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}

Finished task

GET /v1/tasks/{task_id} returns HTTP 200 with status: "succeeded" and the result in data.output.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "kling-3-motion-control",
    "capability_version": 1,
    "media_type": "video",
    "model": "kling-3-motion-control",
    "status": "succeeded",
    "stage": "succeeded",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": {
      "media": [
        {
          "type": "video",
          "url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.mp4",
          "mime_type": "video/mp4"
        }
      ],
      "r2_url": "https://media.beatapi.io/outputs/task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ/0.mp4"
    },
    "usage": {
      "credits_reserved": 1.1,
      "credits_settled": 1.1,
      "credits_refunded": 0,
      "credits_charged": 1.1,
      "billable_duration_seconds": 10
    },
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": null,
    "error_message": null
  }
}

Output fields

Failed task

A failed task is still HTTP 200 on GET /v1/tasks/{task_id}: the failure is in the body. The reservation is returned in full, so nothing is charged.

{
  "data": {
    "id": "task_7Qm2Xc9LpR4vT8sKa1Nf6YbH3eWdJ0uZ",
    "object": "task",
    "task_kind": "video",
    "capability_id": "kling-3-motion-control",
    "capability_version": 1,
    "media_type": "video",
    "model": "kling-3-motion-control",
    "status": "failed",
    "stage": "failed",
    "created_at": 1791993600,
    "updated_at": 1791993690,
    "completed_at": 1791993690,
    "output": null,
    "usage": {
      "credits_reserved": 1.1,
      "credits_settled": 0,
      "credits_refunded": 1.1,
      "credits_charged": 0,
      "billable_duration_seconds": 10
    },
    "retryable": true,
    "request_id": "req_5f0c2a9e4b7d4e31",
    "error_code": "processing_failed",
    "error_message": "The task failed during processing on our side. Retry; a failed task is refunded."
  }
}

Complete example

Create a task, wait for it with the server’s polling hint, and print the result URLs. Set BEATAPI_API_KEY in your environment and install requests.

import os
import time
import uuid
import requests
API = "https://api.beatapi.io"
HEADERS = {"Authorization": f"Bearer {os.environ['BEATAPI_API_KEY']}"}
def create_task(body: dict) -> dict:
    # One Idempotency-Key per logical request: a retry with the same key cannot create a second task.
    headers = {**HEADERS, "Idempotency-Key": str(uuid.uuid4())}
    for attempt in range(3):
        response = requests.post(f"{API}/v1/videos/tasks", headers=headers, json=body, timeout=60)
        if response.status_code in (429, 503) and attempt < 2:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        break
    try:
        payload = response.json()
    except ValueError:  # an edge error page is not JSON
        response.raise_for_status()
        raise
    if not response.ok:
        error = payload["error"]
        raise RuntimeError(f"{response.status_code} {error['code']}: {error['message']} (request_id={error.get('request_id')})")
    return payload["data"]
def wait_for_task(task_id: str, timeout_seconds: int = 1800) -> dict:
    deadline = time.monotonic() + timeout_seconds
    while time.monotonic() < deadline:
        response = requests.get(f"{API}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
        if response.status_code == 429 or response.status_code >= 500:
            time.sleep(int(response.headers.get("Retry-After", 10)))
            continue
        response.raise_for_status()
        task = response.json()["data"]
        if task["status"] in ("succeeded", "failed"):
            return task
        time.sleep(task.get("poll_after_seconds", 5))
    raise TimeoutError(f"task {task_id} is still running; keep polling later")
task = create_task({
  "model": "kling-3-motion-control",
  "prompt": "Keep the singer’s look and outfit; follow the movement of the video.",
  "images": [
    "https://media.beatapi.io/samples/neon-singer.png"
  ],
  "reference_videos": [
    "https://your-cdn.example.com/clips/source.mp4"
  ],
  "resolution": "720p"
})
print("created", task["id"])
task = wait_for_task(task["id"])
if task["status"] == "failed":
    raise SystemExit(f"{task['error_code']}: {task['error_message']}")
for item in task["output"]["media"]:
    print(item["url"])

Billing

• These prices apply once the model is listed; until then a create request is refused and nothing is charged.
• Billed per second of the finished video, by resolution. character_orientation and the prompt do not change the rate. The table below prices an 8-second result.
• The result is as long as your motion video, so the final price is not known when the task is created. The gateway holds the most the orientation allows: 10 seconds with image, 30 seconds with video, at the rate of the resolution. That is about $1.10 (720p) or$1.40 (1080p) with image, and about $3.30 (720p) or$4.20 (1080p) with video. The balance must cover that amount, or the create call fails with 402 insufficient_credits.
• When the task finishes, the amount is settled from the usage reported for the video that was produced, normally the list rate per second for its length, and the rest of the amount held is returned. If no usage is reported, the amount held is charged. usage.credits_charged and usage.credits_settled show what was charged. usage.billable_duration_seconds on this model reports the seconds held at create (10 or 30), not the length of the finished video; read the credits fields for what you paid.
• A failed task, including one refused by moderation after submission, is refunded in full. A request refused before a task exists costs nothing.

Current list prices, the same as on Pricing. An account with a negotiated discount pays less; data.usage on the task always shows the amount actually charged.

Common errors

HTTP errors at a glance

Errors before a task exists arrive as a non-2xx response, and nothing is charged. Branch on error.code or error.retryable; message names the problem. The full list and retry policy are on Errors.

{
  "error": {
    "code": "bad_request",
    "message": "\"prompt\" is required",
    "retryable": false,
    "request_id": "req_5f0c2a9e4b7d4e31"
  }
}

Differences between the two models