Kling 4.0 — API reference

Animate a required first frame, optionally guiding the sequence with middle frames and an end frame. Generate a 3–30 second video in 720p or 1080p.

Model ID: kling-video/v4.0/image-to-video

1. Calling the API

Send a JSON POST request to https://api.higgsfield.ai/kling-video/v4.0/image-to-video. Authenticate with Authorization: Key KEY_ID:KEY_SECRET.

SDK setup

Install an official server-side SDK. cURL needs no package.

npm install @higgsfield/client

Keep credentials in server-side environment variables. The SDKs accept the same KEY_ID:KEY_SECRET value under their documented variable names.

export HF_CREDENTIALS="YOUR_KEY_ID:YOUR_KEY_SECRET" # TypeScript
export HF_KEY="YOUR_KEY_ID:YOUR_KEY_SECRET"         # Python and cURL

Keep API credentials on your server and out of browser code and source control.

2. Request parameters

Parameter	Type	Required	Default	Description
`image_url`	`string`	Yes	—	First frame. A non-empty image URL is always required.
`prompt`	`string`	No	—	Describe the desired action, transitions, and camera movement. May be omitted.
`image_urls`	`string[]`	No	—	Middle frames, in sequence order. Maximum 8 images, even when the end frame is omitted. These are intermediate keyframes, not general reference images.
`end_image_url`	`string`	No	—	Optional end frame. Does not replace the required first frame.
`duration`	`integer`	No	10	Output duration in seconds. Integer from 3 to 30.
`resolution`	`string`	No	1080p	Output resolution: `720p` or `1080p`.

Defaults apply when a field is omitted. Send media as non-empty URLs accessible to the service, not local file paths. Replace the example.com URLs in the examples with your own reachable media URLs.

3. Using this model

Frame order

Frames are sent in this order: image_url → each entry in image_urls → end_image_url, if supplied. Put middle frames in the order you want them used. The schema allows at most 8 middle frames, leaving room for one first frame and one end frame: up to 10 images in total.

Only image_url is required. An end frame or middle frames alone cannot start a valid request. Omit unused optional frame fields rather than sending empty URL strings.

Output framing

This endpoint does not expose an aspect_ratio parameter. Prepare your input frames with the desired composition; use resolution to select 720p or 1080p output.

4. Request examples

Submit and wait

import { config, higgsfield } from "@higgsfield/client/v2";

config({
  credentials: process.env.HF_CREDENTIALS,
});

const result = await higgsfield.subscribe(
  "kling-video/v4.0/image-to-video",
  {
    input: {
      "image_url": "https://example.com/first-frame.jpg",
      "prompt": "The camera slowly moves forward as the subject turns toward the sunlight.",
      "duration": 10,
      "resolution": "1080p"
    },
    withPolling: true,
  },
);

console.log(result);

First, middle, and end frames

Use this JSON body with the same model endpoint:

{
  "image_url": "https://example.com/first-frame.jpg",
  "image_urls": [
    "https://example.com/middle-frame-1.jpg",
    "https://example.com/middle-frame-2.jpg"
  ],
  "end_image_url": "https://example.com/end-frame.jpg",
  "prompt": "Move smoothly through the supplied frames while keeping the subject consistent.",
  "duration": 15,
  "resolution": "1080p"
}

5. Results and polling

Generation is asynchronous. A direct HTTP submission returns request_id, status, status_url, and cancel_url. Submission is not the finished video.

The SDK examples above use automatic polling. For direct HTTP integration, send authenticated GET requests to the returned status_url. Continue while status is queued or in_progress; stop on completed, failed, nsfw, or canceled. A completed video result exposes the generated URL as video.url. If generation fails, inspect the returned error before retrying.

curl --request GET \
  --url "$STATUS_URL" \
  --header "Authorization: Key $HF_KEY"

Set STATUS_URL to the URL returned by submission. Keep the same API credentials for subsequent requests.

6. Validation notes

Use the exact field names and values listed above. duration must be an integer from 3 to 30, and resolution must be 720p or 1080p. Omit unused media fields instead of sending empty strings or nulls.

The schema permits additional properties, but undocumented keys do not create new model controls. Use only the parameters documented for this endpoint.

The first frame is required even when middle or end frames are supplied. Nine or more middle frames are rejected. aspect_ratio is not a documented control for this mode.