# Kling 4.0

> Animate images with Kling 4.0. Guide the video with a starting image, reference images, or an ending frame, and generate clips up to 30 seconds long in 720p or 1080p.

## Overview

- **Endpoint**: `https://api.higgsfield.ai/kling-video/v4.0/image-to-video`
- **Model ID**: `kling-video/v4.0/image-to-video`
- **Category**: image2video
- **Kind**: inference

## Pricing

Public pricing information is not available for this model.

## Authentication

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

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

The official SDKs configure the authorization header. Keep credentials server-side; the TypeScript SDK blocks browser use.

## API Information

Use `subscribe` to submit the model request and wait for a terminal result. TypeScript performs automatic polling with `withPolling: true`; Python's synchronous `subscribe` call also waits.

### Input Parameters

- **`prompt`** (`string`, _optional_):

- **`duration`** (`integer`, _optional_):
  - Default: `10`

- **`image_url`** (`string`, _required_):

- **`image_urls`** (`list<string>`, _optional_):
  Intermediate frames between the first and end frames. Up to 8 images.

- **`resolution`** (`string`, _optional_):
  - Default: `"1080p"`
  - Options: `720p`, `1080p`

- **`end_image_url`** (`string`, _optional_):

### Input JSON Schema

```json
{
  "type": "object",
  "required": [
    "image_url"
  ],
  "properties": {
    "prompt": {
      "type": "string"
    },
    "duration": {
      "type": "integer",
      "default": 10,
      "maximum": 30,
      "minimum": 3
    },
    "image_url": {
      "type": "string",
      "format": "uri",
      "minLength": 1
    },
    "image_urls": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri",
        "minLength": 1
      },
      "title": "Middle frames",
      "maxItems": 8,
      "description": "Intermediate frames between the first and end frames. Up to 8 images."
    },
    "resolution": {
      "enum": [
        "720p",
        "1080p"
      ],
      "type": "string",
      "default": "1080p"
    },
    "end_image_url": {
      "type": "string",
      "format": "uri",
      "minLength": 1
    }
  },
  "additionalProperties": true
}
```

### Required Parameters Example

```json
{
  "duration": 10,
  "image_url": "https://example.com/input.jpg",
  "resolution": "1080p"
}
```

### Output Schema

The shared polling endpoint returns one of the following status shapes:

```json
{
  "title": "RequestStatus",
  "oneOf": [
    {
      "title": "PendingRequestStatus",
      "type": "object",
      "properties": {
        "request_id": {
          "type": "string",
          "format": "uuid"
        },
        "status_url": {
          "type": "string",
          "format": "uri"
        },
        "cancel_url": {
          "type": "string",
          "format": "uri"
        },
        "status": {
          "type": "string",
          "enum": [
            "queued",
            "in_progress",
            "nsfw",
            "canceled"
          ]
        }
      },
      "required": [
        "status",
        "request_id"
      ]
    },
    {
      "title": "FailedRequestStatus",
      "type": "object",
      "properties": {
        "request_id": {
          "type": "string",
          "format": "uuid"
        },
        "status_url": {
          "type": "string",
          "format": "uri"
        },
        "cancel_url": {
          "type": "string",
          "format": "uri"
        },
        "status": {
          "type": "string",
          "const": "failed"
        },
        "error": {
          "type": "string"
        }
      },
      "required": [
        "status",
        "request_id",
        "error"
      ]
    },
    {
      "title": "CompletedRequestStatus",
      "type": "object",
      "properties": {
        "request_id": {
          "type": "string",
          "format": "uuid"
        },
        "status_url": {
          "type": "string",
          "format": "uri"
        },
        "cancel_url": {
          "type": "string",
          "format": "uri"
        },
        "status": {
          "type": "string",
          "const": "completed"
        },
        "video": {
          "type": "object",
          "properties": {
            "url": {
              "type": "string",
              "format": "uri"
            }
          },
          "required": [
            "url"
          ]
        },
        "zip": {
          "type": "object",
          "properties": {
            "url": {
              "type": "string",
              "format": "uri"
            }
          },
          "required": [
            "url"
          ]
        },
        "mov": {
          "type": "object",
          "properties": {
            "url": {
              "type": "string",
              "format": "uri"
            }
          },
          "required": [
            "url"
          ]
        },
        "jsx": {
          "type": "object",
          "properties": {
            "url": {
              "type": "string",
              "format": "uri"
            }
          },
          "required": [
            "url"
          ]
        },
        "fbx": {
          "type": "object",
          "properties": {
            "url": {
              "type": "string",
              "format": "uri"
            }
          },
          "required": [
            "url"
          ]
        },
        "ply": {
          "type": "object",
          "properties": {
            "url": {
              "type": "string",
              "format": "uri"
            }
          },
          "required": [
            "url"
          ]
        }
      },
      "required": [
        "status",
        "request_id",
        "video"
      ]
    }
  ]
}
```

## SDK Installation

Install one of the official server-side SDKs:

```bash
npm install @higgsfield/client
# or
pip install higgsfield-client
```

## Usage Examples

### TypeScript

```typescript
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: {
      "duration": 10,
      "image_url": "https://example.com/input.jpg",
      "resolution": "1080p"
    },
    withPolling: true,
  },
);

console.log(result);
```

### Python

```python
import higgsfield_client

result = higgsfield_client.subscribe(
    'kling-video/v4.0/image-to-video',
    arguments={'duration': 10,
         'image_url': 'https://example.com/input.jpg',
         'resolution': '1080p'},
)

print(result)
```

### cURL

```bash
curl --request POST \
  --url 'https://api.higgsfield.ai/kling-video/v4.0/image-to-video' \
  --header "Authorization: Key $HF_KEY" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "duration": 10,
  "image_url": "https://example.com/input.jpg",
  "resolution": "1080p"
}
JSON
```

## Additional Documentation

# Kling 4.0 — Image to Video

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.

```bash control=package group=install-typescript variant=npm label=npm when=javascript
npm install @higgsfield/client
```

```bash control=package group=install-python variant=pip label=pip when=python
pip 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.

```bash
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

```ts control=language group=submit variant=javascript label=TypeScript
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);
```

```python control=language group=submit variant=python label=Python
import higgsfield_client

result = higgsfield_client.subscribe(
    'kling-video/v4.0/image-to-video',
    arguments={'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'},
)

print(result)
```

```bash control=language group=submit variant=curl label=cURL
curl --request POST \
  --url 'https://api.higgsfield.ai/kling-video/v4.0/image-to-video' \
  --header "Authorization: Key $HF_KEY" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "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"
}
JSON
```

### First, middle, and end frames

Use this JSON body with the same model endpoint:

```json
{
  "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.

```bash
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.

## Additional Resources

- [Model page](https://console.higgsfield.ai/models/kling-video/v4.0/image-to-video)
- [This LLM-readable document](https://dash.higgsfield.ai/models/kling-video/v4.0/image-to-video/llms.txt)