Kling 3.0 Multi-Shot Storyboard API Guide

The short answer: Kling 3.0 can render several shots in one clip, and you control them through a structured shots object in the request. On HopBase, multi-shot works on kling-v3 and kling-v3-omni, both of which produce clips of 3-15 seconds at 720p, 1080p, 2K or 4K. There are two modes. With "mode": "intelligence", the model splits your prompt into shots itself. With "mode": "customize", you write up to 6 numbered segments. Each segment has its own prompt of up to 512 characters and lasts at least 1 second, and the segment durations must add up exactly to the request's duration. To keep the same character in every shot, create a custom subject once with POST /v1/kling/subjects, which is free. Then pass its ID in subjects and refer to it as <<<element_1>>> in the prompt. Shots and subjects do not change the per-second price. Only resolution, audio, and a reference video do.

Which Kling models support shots and subjects

Model	Duration	Shots (multi-shot)	Subjects	Reference images
kling-v3-omni	3-15 s	Yes	Yes	Reference images + subjects ≤ 7 (≤ 4 with a reference video)
kling-v3	3-15 s	Yes	Yes, but needs at least one reference image	Up to 6
kling-v3-turbo	3-15 s	No	Yes	No

Older Kling models (o1, 2.6, 2.5 Turbo, 2.1, 1.6) support neither. Sending shots to them returns model ... does not support shots (multi-shot storyboard). Always confirm the model IDs your key can reach with GET /v1/models.

The shots object

Every request goes to POST https://api.hop-base.com/v1/video/generate. Multi-shot adds one field, shots, with these rules:

• mode is intelligence or customize.
• In intelligence mode, leave out segments. The model decides where to cut.
• In customize mode, segments is required: at most 6, with index numbered 1, 2, 3 and so on with no gaps.
• Each segment prompt must not be empty and can be at most 512 characters.
• Each segment duration is at least 1 second, and the durations must add up exactly to the top-level duration. Always set duration explicitly when you use segments.
• Use the structured shots object. Kling's raw extra.multi_shot, extra.shot_type and extra.multi_prompt are rejected.

Intelligence mode: let the model cut

curl https://api.hop-base.com/v1/video/generate \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3",
    "prompt": "A barista grinds coffee, pours latte art, then slides the cup across the counter to a smiling customer",
    "duration": 10,
    "resolution": "1080p",
    "audio": true,
    "shots": { "mode": "intelligence" }
  }'

Customize mode: write the storyboard yourself

curl https://api.hop-base.com/v1/video/generate \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-omni",
    "prompt": "A 10-second product story for a pair of trail running shoes",
    "duration": 10,
    "resolution": "1080p",
    "audio": true,
    "shots": {
      "mode": "customize",
      "segments": [
        { "index": 1, "prompt": "Wide shot: a runner laces up the shoes at a misty trailhead at dawn", "duration": 3 },
        { "index": 2, "prompt": "Low tracking shot: the shoes hit wet rocks, water splashes in slow motion", "duration": 3 },
        { "index": 3, "prompt": "Close-up: the runner stops on a ridge, sunlight on the shoe logo", "duration": 4 }
      ]
    }
  }'

3 + 3 + 4 = 10, which matches duration. If the numbers do not match, the request is rejected before a task is created, with sum of shot durations (9 s) must equal the total duration (10 s), and you are not billed.

Keeping one character across shots with custom subjects

When a story cuts between shots, the hard part is keeping the character looking the same in each one. Kling handles this with subjects: a saved character or object that you build once from reference media and then reuse by ID.

Step 1: create the subject (free, asynchronous)

curl https://api.hop-base.com/v1/kling/subjects \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Luna mascot",
    "description": "Orange fox mascot wearing a blue hoodie",
    "reference_type": "image_refer",
    "frontal_image_url": "https://cdn.example.com/luna-front.png",
    "reference_image_urls": [
      "https://cdn.example.com/luna-side.png",
      "https://cdn.example.com/luna-back.png"
    ]
  }'

• image_refer needs one front-facing image plus 1-3 more reference images. They must not repeat the front image or each other.
• video_refer builds the subject from a single video_url instead, and can optionally attach a voice_id. The two methods cannot be mixed in one request.
• name can be up to 20 characters and description up to 100. Every URL must be a public http(s) address.

The call returns 202 with an id (its object is kling.subject.task). Poll it like any video task with GET /v1/video/tasks/{task_id}. When it completes, the result includes element_ids: those are your subject IDs. GET /v1/kling/subjects lists every subject you have created. Creating a subject is currently free.

Step 2: use the subject in a multi-shot request

curl https://api.hop-base.com/v1/video/generate \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v3-omni",
    "prompt": "Medium shot: <<<element_1>>> sits on a sofa holding a red gift box. Then a close-up: <<<element_1>>> lifts the lid and its eyes light up",
    "duration": 8,
    "resolution": "1080p",
    "subjects": [{ "id": "subject-92951593344", "name": "luna" }],
    "shots": { "mode": "intelligence" }
  }'

How subject references work:

• Subjects are matched by position. subjects[0] is <<<element_1>>>, subjects[1] is <<<element_2>>>, and so on.
• Every subject you send must be referenced in the top-level prompt. Otherwise you get subjects[0] is not referenced in prompt as <<<element_1>>>.
• Referencing a subject you did not send, such as <<<element_3>>> when you sent only two, is also rejected.
• On kling-v3, a request with subjects also needs at least one images[] item with "usage": "reference". Without one it is rejected at submission, before the request ever reaches Kling.
• The example uses intelligence mode because the top-level prompt is then the script for every shot, so the subject token sits where the model reads it. Subjects also work with customize-mode segments. In our test on kling-v3-omni, the top-level prompt referenced <<<element_1>>> once and each segment only said "the man"; both shots showed the same subject, with matching face, glasses, lab coat and red tie. The reference has to be in the top-level prompt: putting it only in segments is rejected at submission with subjects[0] is not referenced in prompt as <<<element_1>>>. In one side-by-side run, repeating <<<element_1>>> in every segment put two copies of the character into the first shot (one walking, one already sitting on the bench), while the version with plain descriptions in the segments did not. Reference the subject once at the top level, describe it in plain words in each segment, and render a short 720p test before you scale up.

Polling and results

All of these are asynchronous. The submit returns 202 with a task ID like kt57x… and a billing_bucket, and you poll GET /v1/video/tasks/{task_id} until status is completed or failed:

curl https://api.hop-base.com/v1/video/tasks/kt57xYOUR_TASK_ID \
  -H "Authorization: Bearer sk-YOUR_KEY"

A completed task has outputs, a signed URL on api.hop-base.com valid for 24 hours from completion, and usage with billed_seconds and cost_usd (the amount actually deducted). A failed task has a stable error.code, such as input_sensitive, invalid_request, generation_failed or timeout, and is never billed. Tasks unfinished after 2 hours are failed automatically. Full field reference: Kling video API docs.

What multi-shot costs

Kling bills per second of output at the rate for the model, the resolution, and whether the clip is silent, has audio, or uses a reference video. Shots, subjects and reference images do not add to the price. Official list prices from the model cards include:

Model · tier	720p	1080p	2K
kling-v3 · silent	$0.0882 / s	$0.1176 / s	$0.1471 / s
kling-v3 · with audio	$0.1324 / s	$0.1765 / s	$0.2206 / s
kling-v3-omni · silent, no reference video	$0.0882 / s	$0.1176 / s	$0.1471 / s
kling-v3-omni · with audio, no reference video	$0.1176 / s	$0.1471 / s	$0.1765 / s

So the 10-second customize example above (kling-v3-omni, 1080p, audio) is 10 × $0.1471, about $1.47 at list price. 4K tiers and reference-video tiers are on the kling-v3 and kling-v3-omni model cards. The pricing page lists the same tiers in CNY, for example kling-v3 1080p with audio at ¥1.20 per second. Your actual rate depends on your group.

Tips for better storyboards

• Write each segment like a shot list entry. Start with the framing ("Wide shot", "Close-up", "Low tracking shot"), then the action. One action per segment works best.
• Give short beats at least 2 seconds. The minimum is 1 second, but very short segments leave little room for motion.
• Prototype in intelligence mode at 720p, then switch to customize mode and a higher resolution once the story works. The cost scales with seconds × resolution tier.
• Turn audio on only when you need it. On kling-v3 at 1080p, audio raises the rate from $0.1176 to $0.1765 per second.

FAQ

How many shots can one Kling 3.0 clip have?

Up to 6 custom segments in customize mode, within a total clip length of 3-15 seconds. In intelligence mode the model decides the number of shots itself.

Does kling-v3-turbo support multi-shot?

No. kling-v3-turbo supports subjects but not shots. Use kling-v3 or kling-v3-omni for storyboards.

Do shots or subjects cost extra?

No. The price per second depends on the model, the resolution, audio, and whether there is a reference video. Creating a custom subject is currently free.

Can I combine subjects with a custom storyboard?

Yes. Put the subject in subjects, reference it once in the top-level prompt as <<<element_1>>>, and describe the action in each of the segments with plain words such as "he" or "the man". The character stays consistent across shots. kling-v3 also needs one images[] item with "usage": "reference" when you use subjects.

Why was my storyboard rejected with "sum of shot durations must equal the total duration"?

The segment durations must add up exactly to the top-level duration. Always set duration explicitly when you write segments, and do not rely on the default.

Can I use Kling's raw multi_shot or element_list parameters?

No. HopBase accepts the structured shots and subjects fields. Raw extra.multi_shot, extra.multi_prompt, extra.shot_type and extra.element_list are rejected with a message that points you to the structured field.

How do I start?

Create a key in the HopBase console with a group that includes the Kling models, check GET /v1/models for kling-v3 or kling-v3-omni, and start with the intelligence-mode example above. For a different kind of control, where a person copies the movement in a video, see our Kling motion control API guide.