Kling 3.0 Motion Control | BeatAPI API Documentation

curl -X POST https://api.beatapi.io/v1/videos/tasks \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "model": "kling-3-motion-control",
  "images": [
    "https://media.beatapi.io/samples/neon-singer.png"
  ],
  "reference_videos": [
    "https://media.beatapi.io/inputs/motion.mp4"
  ],
  "prompt": "Preserve the character and transfer the full-body motion precisely.",
  "resolution": "1080p",
  "character_orientation": "image",
  "background_source": "input_video"
}'

{
  "data": {
    "capability_id": "kling-3-motion-control",
    "capability_version": null,
    "completed_at": null,
    "created_at": 1782210000,
    "error_code": null,
    "error_message": null,
    "id": "task_8K2qA",
    "media_type": "video",
    "model": "kling-3-motion-control",
    "object": "task",
    "output": null,
    "request_id": "req_abc123",
    "stage": "queued",
    "status": "queued",
    "task_kind": "video",
    "updated_at": 1782210000,
    "usage": {
      "billable_duration_seconds": 15,
      "credits_charged": 2.1,
      "credits_refunded": 0,
      "credits_reserved": 2.1,
      "credits_settled": 0
    }
  }
}

Transfer full-body motion with selectable character orientation and background source at 720p or 1080p; image orientation supports up to 10 seconds and video orientation up to 30 seconds.

Supported modes

Mode	Required input	Rules
Motion transfer	`model`, `images`, `reference_videos`	Upload both assets through `/v1/files`; assets must exceed 340 px, use a 2:5–5:2 ratio, and follow the 10s image / 30s video orientation limits.

Async flow: Create the task, save data.id, then poll the Task with GET /v1/tasks/{task_id}. On succeeded, read data.output.media. On failed, read data.error_code and data.error_message, then follow the error and retry policy.

Using a local file? upload a local input first and pass the returned data.url.

Transfer full-body motion with selectable character orientation and background source at 720p or 1080p; image orientation supports up to 10 seconds and video orientation up to 30 seconds. ### Supported modes | Mode | Required input | Rules | | --- | --- | --- | | Motion transfer | `model`, `images`, `reference_videos` | Upload both assets through `/v1/files`; assets must exceed 340 px, use a 2:5–5:2 ratio, and follow the 10s image / 30s video orientation limits. | **Async flow:** Create the task, save `data.id`, then [poll the Task](/quick-guide#get-task-status) with `GET /v1/tasks/{task_id}`. On `succeeded`, read `data.output.media`. On `failed`, read `data.error_code` and `data.error_message`, then follow the [error and retry policy](/quick-guide#errors-and-retry-policy). **Using a local file?** [upload a local input](/quick-guide#upload-an-input-file) first and pass the returned `data.url`.

身份验证

AuthorizationBearer

Send your API key as Authorization: Bearer <BEATAPI_API_KEY>.

请求

This endpoint expects an object.

model"kling-3-motion-control"必需

Must be kling-3-motion-control.

imageslist of strings必需

Exactly one character-image URL returned by the current account’s /v1/files upload; maximum 10 MB.

reference_videoslist of strings必需

Exactly one 3–30 second MP4/MOV URL returned by the current account’s /v1/files upload; maximum 100 MB. Its detected duration determines billing.

promptstring可选<=2500 characters

Optional motion or scene guidance.

resolutionenum可选默认为 720p

Output resolution and per-second price tier.

character_orientationenum可选默认为 image

Image orientation supports motion videos up to 10 seconds; video orientation supports up to 30 seconds.

background_sourceenum可选默认为 input_video

Preserve the background from the motion video or character image.

响应

Video generation task accepted

错误

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

409

Conflict Error

429

Too Many Requests Error

Transfer full-body motion with selectable character orientation and background source at 720p or 1080p; image orientation supports up to 10 seconds and video orientation up to 30 seconds.

Supported modes

Mode	Required input	Rules
Motion transfer	`model`, `images`, `reference_videos`	Upload both assets through `/v1/files`; assets must exceed 340 px, use a 2:5–5:2 ratio, and follow the 10s image / 30s video orientation limits.

Using a local file? upload a local input first and pass the returned data.url.

Supported modes

身份验证

请求头

请求

响应

错误

Supported modes