Kling 3

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

Generate 3–15 second videos from text or frames, with optional multi-shot and reusable-element controls up to 4K.

Supported modes

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.

Authorization

Authorization   string   required

Send your BeatAPI API key as a Bearer token. Create one on the Dashboard.

Authorization: Bearer <BEATAPI_API_KEY>

Keep permanent API keys on trusted servers. Content-Type: application/json is required for the request body. Idempotency-Key is optional when the endpoint exposes it and is recommended for safe retries with the exact same body.

Request body

model   string   required

Must be kling-3.

Value: kling-3

prompt   string   required

Video generation instructions.

Length: 1 to 5000 characters

images   string[]   optional

One first-frame image or first- and last-frame images as public HTTPS URLs. Multi-shot mode accepts exactly one.

Count: 1 to 2 items

duration   integer   optional

Requested output duration in seconds.

Default: 5
Range: 3 to 15

aspect_ratio   enum<string>   optional

Defaults to 16:9 for text generation. Omit it with frame images to adapt to the input aspect ratio.

Available options: 16:9, 9:16, 1:1

resolution   enum<string>   optional

Output quality tier.

Available options: std, pro, 4K
Default: "pro"

sound   boolean   optional

Generate synchronized sound. Defaults to true in multi-shot mode.

multi_shots   boolean   optional

Enable storyboard-style multi-shot generation.

Default: false

multi_prompt   object[]   optional

Shot definitions required when multi_shots=true.

Count: 1 to 5 items

multi_prompt.prompt   string   required with its parent

Instructions for this shot.

Length: 1 to 500 characters

multi_prompt.duration   integer   required with its parent

Shot duration in seconds. All shot durations must sum to the task duration.

Range: 1 to 12

elements   object[]   optional

Up to three reusable subject or object references.

Count: at most 3 items

elements.name   string   required with its parent

Stable name used to reference this element in the prompt.

Length: at least 1 characters

elements.description   string   optional

Optional description of the subject or object.

elements.element_input_urls   string[]   required with its parent

Two to four image URLs, or one video URL.

Count: 1 to 4 items

elements.element_input_audio_urls   string[]   optional

Optional audio URL used with a video element.

Count: 1 to 1 items

elements.start_time   integer   optional

Video element segment start time in milliseconds.

Range: 0 to 30000

elements.end_time   integer   optional

Video element segment end time in milliseconds. The segment must be 3-8 seconds.

Range: 0 to 30000

Request examples

Text to video

$
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",
>
  "prompt": "A dramatic product reveal with a slow orbiting camera move.",
>
  "duration": 5,
>
  "aspect_ratio": "16:9",
>
  "resolution": "pro",
>
  "sound": true
>
}'

First frame

$
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",
>
  "prompt": "Animate the product with a slow orbit and precise studio reflections.",
>
  "images": [
>
    "https://media.beatapi.io/samples/smart-bottle.png"
>
  ],
>
  "duration": 5,
>
  "resolution": "pro",
>
  "sound": true
>
}'

Multi-shot

$
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",
>
  "prompt": "A two-shot cinematic product reveal.",
>
  "duration": 6,
>
  "aspect_ratio": "16:9",
>
  "resolution": "pro",
>
  "sound": true,
>
  "multi_shots": true,
>
  "multi_prompt": [
>
    {
>
      "prompt": "Macro detail shot with moving reflections.",
>
      "duration": 3
>
    },
>
    {
>
      "prompt": "Wide hero reveal on a dark pedestal.",
>
      "duration": 3
>
    }
>
  ]
>
}'

Reusable element

$
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",
>
  "prompt": "Keep @product consistent during a slow cinematic camera orbit.",
>
  "duration": 5,
>
  "resolution": "pro",
>
  "elements": [
>
    {
>
      "name": "product",
>
      "description": "The featured bottle",
>
      "element_input_urls": [
>
        "https://media.beatapi.io/samples/smart-bottle.png",
>
        "https://media.beatapi.io/samples/neon-singer.png"
>
      ]
>
    }
>
  ]
>
}'

Response

A successful request returns HTTP 201.

1
{
2
  "data": {
3
    "id": "task_8K2qA",
4
    "object": "task",
5
    "task_kind": "video",
6
    "capability_id": "kling-3",
7
    "capability_version": null,
8
    "media_type": "video",
9
    "model": "kling-3",
10
    "status": "queued",
11
    "stage": "queued",
12
    "created_at": 1782210000,
13
    "updated_at": 1782210000,
14
    "completed_at": null,
15
    "output": null,
16
    "usage": {
17
      "credits_reserved": 0.65,
18
      "credits_charged": 0.65,
19
      "billable_duration_seconds": 5,
20
      "credits_settled": 0,
21
      "credits_refunded": 0
22
    },
23
    "request_id": "req_abc123",
24
    "error_code": null,
25
    "error_message": null
26
  }
27
}

Errors