Skip to content
NEWNano Banana 2.1 is live — Google's latest image model, from $0.0336 per image, native 4K, about half the price of the previous generationView model
HopBase
← Back to blog

Kling 4.0 API (kling-v4): Parameters, Pricing and Code

HopBase Oct 30, 2026 30 min read

The short answer: Kling 4.0 is available on HopBase as the model kling-v4. It generates 3 to 30 seconds of video at 720p or 1080p, in 16:9, 9:16, 1:1 or 21:9, from a text prompt or from one first-frame image. Every result has an audio track: audio: false neither removes it nor lowers the price. Generation is an asynchronous task. Submit with POST https://api.hop-base.com/v1/video/generate, get back a task ID that starts with kt, then poll GET /v1/video/tasks/{task_id} until the status is completed or failed; a task usually takes a few minutes. The official list price is $0.1471 per second at 720p and $0.2206 per second at 1080p, billed on output seconds, and failed tasks are free. Reference images, reference video and 2K/4K are not available on kling-v4 yet. Result links stay valid for 24 hours, and the same HopBase key and USD balance you use for other models covers Kling, with no separate Kling account.

What Kling 4.0 adds, and when to stay on Kling 3.0

Kling 4.0 went live on HopBase on 2026-10-29. Compared with the Kling 3.0 models on the same key, it allows longer clips (up to 30 seconds in one task instead of 15), adds the 21:9 cinematic aspect ratio, and always delivers sound. It is a narrower model on the input side: only a text prompt and an optional first frame.

kling-v4 kling-v3 kling-v3-omni
Duration 3–30 s 3–15 s 3–15 s
Resolutions 720p / 1080p 720p / 1080p / 2K / 4K 720p / 1080p / 2K / 4K
Aspect ratios 16:9 / 9:16 / 1:1 / 21:9 16:9 / 9:16 / 1:1 16:9 / 9:16 / 1:1
Audio Always included With or without With or without
Image input First frame only First/last frame, up to 6 reference images First/last frame, reference images
Reference video No No Yes (feature)
Subjects / multi-shot shots No Yes Yes
List price, 1080p with audio $0.2206 / s $0.1765 / s $0.1471 / s

Choose kling-v4 for single clips longer than 15 seconds, for 21:9 output, or when you want a soundtrack on every result without managing an audio flag. Stay on kling-v3 or kling-v3-omni when you need reference images, a reference video, consistent characters through custom subjects, a multi-shot storyboard, or 2K/4K. Our Kling 3.0 multi-shot guide covers shots and subjects. We make no claims here about visual quality differences between versions; run the same prompt on both models and compare.

Pricing: per second of output

kling-v4 is billed per second of output video, at the rate for the resolution you request. With or without audio, the price is the same. These are the official list prices on the kling-v4 model card:

Resolution List price 5 s clip 10 s clip 30 s clip
720p $0.1471 / s ≈ $0.74 ≈ $1.47 ≈ $4.41
1080p $0.2206 / s ≈ $1.10 ≈ $2.21 ≈ $6.62

Your own rate depends on the groups on your key and is shown in the signed-in model catalog. Only a task that completes is billed; a failed task never is. After completion, usage.cost_usd in the task response is the exact amount deducted from your balance. Prices for the rest of the Kling family are on the pricing page.

Step 1a: text-to-video

All Kling models share one endpoint. Authenticate with your HopBase key as a Bearer token:

curl https://api.hop-base.com/v1/video/generate \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v4",
    "prompt": "A slow dolly shot along a rain-soaked neon street at night, reflections on the asphalt, distant traffic noise",
    "duration": 10,
    "resolution": "1080p",
    "aspect_ratio": "21:9"
  }'

Field by field:

  • model: kling-v4.
  • prompt: required when there is no image, up to 2,500 characters.
  • duration: integer seconds from 3 to 30. If you omit it, the gateway uses 5.
  • resolution: 720p or 1080p; it also selects the price. If you omit it, the gateway uses 720p.
  • aspect_ratio: 16:9, 9:16, 1:1 or 21:9. The gateway does not fill it in when it is missing, so set it explicitly for text-to-video.
  • audio: you can leave it out. The output always has sound and the price does not change.

A successful submit returns 202 with the task ID at the top level:

{
  "id": "kt57xYOUR_TASK_ID",
  "object": "video.generation.task",
  "model": "kling-v4",
  "status": "queued",
  "created": 1790000000,
  "billing_bucket": "1080p_..."
}

Step 1b: image-to-video from a first frame

To animate a still image, put it in images[] with usage: "first_frame":

curl https://api.hop-base.com/v1/video/generate \
  -H "Authorization: Bearer sk-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-v4",
    "prompt": "The camera pushes in slowly as steam rises from the coffee cup",
    "duration": 8,
    "resolution": "720p",
    "images": [
      { "url": "https://cdn.example.com/coffee.png", "usage": "first_frame" }
    ]
  }'
  • The output follows the aspect ratio of the input image, and aspect_ratio has no effect. Crop the image to 9:16 first if you want a vertical result.
  • Each image item takes exactly one of url or file_id. A url must be an absolute, publicly reachable http(s) address. Relative paths, file://, private or loopback IPs and URLs with embedded credentials are rejected at submission.
  • usage is required on every image. kling-v4 accepts a first frame only; an image with usage: "reference" returns 400 model kling-v4 does not support reference-based generation.

Step 2: poll until the task finishes

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

status moves from queued to processing and ends at completed or failed. Only those two are terminal; treat any other value as still running. A completed task looks like this:

{
  "id": "kt57xYOUR_TASK_ID",
  "status": "completed",
  "outputs": ["https://api.hop-base.com/..."],
  "usage": { "bucket": "1080p_...", "billed_seconds": 10, "cost": ..., "cost_usd": 2.206, "currency": "CNY" }
}

outputs holds signed links on api.hop-base.com that are valid for 24 hours from completion. Polling again returns the same link without extending it, and an expired link returns 410, so copy the file to your own storage right away. usage.cost_usd is the amount deducted from your USD balance; cost is the same charge expressed in CNY.

A failed task still answers with HTTP 200, status: "failed" and a stable error.code:

{
  "id": "kt57xYOUR_TASK_ID",
  "status": "failed",
  "error": { "code": "input_sensitive", "message": "..." }
}

Complete Python example

This script submits a text-to-video task, polls it every 10 seconds and downloads the MP4:

import time
import requests

API = "https://api.hop-base.com/v1"
HEADERS = {"Authorization": "Bearer sk-YOUR_KEY"}

resp = requests.post(f"{API}/video/generate", headers=HEADERS, json={
    "model": "kling-v4",
    "prompt": "A paper boat drifts down a stream in a sunlit forest, birdsong and running water",
    "duration": 10,
    "resolution": "1080p",
    "aspect_ratio": "16:9",
})
resp.raise_for_status()
task_id = resp.json()["id"]
print("submitted", task_id)

while True:
    task = requests.get(f"{API}/video/tasks/{task_id}", headers=HEADERS).json()
    status = task["status"]
    if status == "completed":
        url = task["outputs"][0]
        with requests.get(url, stream=True) as r:
            r.raise_for_status()
            with open(f"{task_id}.mp4", "wb") as f:
                for chunk in r.iter_content(chunk_size=1 << 20):
                    f.write(chunk)
        print("saved", f"{task_id}.mp4", "charged $", task["usage"]["cost_usd"])
        break
    if status == "failed":
        err = task.get("error", {})
        raise RuntimeError(f'{err.get("code")}: {err.get("message")}')
    time.sleep(10)

There is no webhook field in the Kling request, so polling is how you track a task. A task still unfinished 2 hours after creation is marked failed with error.code timeout and is not billed. Tasks cannot be cancelled. If you run several video models, our guide to calling Seedance, Kling, Hailuo and Wan with one key has a polling loop that works across all of them.

Errors you are likely to hit

The request body is decoded strictly. Anything wrong at submission returns an error immediately, creates no task and costs nothing:

What you sent error.message
duration outside 3–30 model kling-v4 supports 3 to 30 seconds, got 40
An image with usage: "reference" model kling-v4 does not support reference-based generation
An image without usage images[0].usage is required for standard Kling video requests
resolution: "2k" or "4k" model "kling-v4" does not support billing bucket "..." for this request
A field from OpenAI's API, such as size request body does not match the JSON contract: json: unknown field "size"
No prompt and no image prompt and input media cannot both be empty

A 402 with code insufficient_balance means your balance, minus the estimated cost of tasks that are still running and of this one, cannot cover the request. The hold is released when each task ends.

Media is checked by Kling while the task runs, not at submission. An image that cannot be downloaded or does not meet Kling's format and size rules is accepted and then fails a few minutes later with reference_input_invalid; a prompt or image refused by moderation fails with input_sensitive. None of these failures is billed. The full error catalog is in the Kling video API docs.

FAQ

What is the model ID for Kling 4.0?

kling-v4. Run GET /v1/models with your key to confirm it is included in your key's groups before you send paid work.

How long can a Kling 4.0 video be?

From 3 to 30 seconds per task, in whole seconds. The default is 5 seconds if you leave out duration.

Does Kling 4.0 support 2K or 4K?

Not yet. kling-v4 supports 720p and 1080p. For 2K or 4K output, use kling-v3 or kling-v3-omni.

Can I turn off the audio?

No. The output always includes an audio track, even with audio: false, and the price is the same either way. If you need a silent file, strip the audio track after downloading.

Does Kling 4.0 accept reference images or a reference video?

No. It accepts a text prompt and, optionally, one first-frame image. For reference images, a reference video, custom subjects or multi-shot storyboards, use kling-v3-omni or kling-v3.

Why doesn't aspect_ratio work in image-to-video?

With a first frame, the output follows the aspect ratio of the input image and aspect_ratio is ignored. Crop the image to the shape you want before submitting.

How long does generation take?

Usually a few minutes. Poll every 5 to 10 seconds. A task that has not finished 2 hours after creation fails with timeout and is not charged.

How much does a 10-second 1080p Kling 4.0 video cost?

At the official list price, 10 × $0.2206 ≈ $2.21. The actual charge for each task is returned in usage.cost_usd and appears in your usage records.

How do I get access?

Create an API key in the HopBase console with a group that includes Kling, then check that kling-v4 appears in GET /v1/models. The same key can also run Kling motion control, Kling digital human and the other video families in the video overview, as long as its groups include them.

TutorialKling