# Kling 4.0

> Create videos with Kling 4.0 using image and video references. Combine a text prompt with reference images, videos, or elements to guide clips up to 30 seconds long in 720p or 1080p.

## Overview

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

## Pricing

Without input video: 720p $0.157/s, 1080p $0.235/s, charged on output duration. With input video: 720p $0.094/s, 1080p $0.141/s, charged on output duration + max(total input video duration, output duration). Input duration includes video elements and explicit videos after the 30-second trim.

## 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`, _required_):

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

- **`elements`** (`list<integer>`, _optional_):

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

- **`image_urls`** (`list<string>`, _optional_):

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

- **`video_urls`** (`list<string>`, _optional_):

- **`aspect_ratio`** (`string`, _optional_):
  - Default: `"adaptive"`
  - Options: `21:9`, `16:9`, `9:16`, `1:1`, `adaptive`

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

### Input JSON Schema

```json
{
  "if": {
    "required": [
      "image_url"
    ]
  },
  "else": {
    "if": {
      "required": [
        "image_urls"
      ],
      "properties": {
        "image_urls": {
          "minItems": 1
        }
      }
    },
    "else": {
      "if": {
        "required": [
          "end_image_url"
        ]
      },
      "else": {
        "if": {
          "required": [
            "video_urls"
          ],
          "properties": {
            "video_urls": {
              "minItems": 1
            }
          }
        },
        "else": {
          "required": [
            "elements"
          ],
          "properties": {
            "elements": {
              "minItems": 1
            }
          }
        }
      }
    }
  },
  "type": "object",
  "required": [
    "prompt"
  ],
  "properties": {
    "prompt": {
      "type": "string",
      "minLength": 1
    },
    "duration": {
      "type": "integer",
      "default": 10,
      "maximum": 30,
      "minimum": 3
    },
    "elements": {
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 1
      },
      "maxItems": 7
    },
    "image_url": {
      "type": "string",
      "format": "uri",
      "minLength": 1
    },
    "image_urls": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri",
        "minLength": 1
      },
      "maxItems": 10
    },
    "resolution": {
      "enum": [
        "720p",
        "1080p"
      ],
      "type": "string",
      "default": "1080p"
    },
    "video_urls": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uri",
        "minLength": 1
      },
      "maxItems": 5
    },
    "aspect_ratio": {
      "enum": [
        "21:9",
        "16:9",
        "9:16",
        "1:1",
        "adaptive"
      ],
      "type": "string",
      "default": "adaptive"
    },
    "end_image_url": {
      "type": "string",
      "format": "uri",
      "minLength": 1
    }
  },
  "additionalProperties": true
}
```

### Required Parameters Example

```json
{
  "prompt": "A cinematic scene at sunset",
  "duration": 10,
  "resolution": "1080p",
  "aspect_ratio": "adaptive"
}
```

### 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/reference-to-video",
  {
    input: {
      "prompt": "A cinematic scene at sunset",
      "duration": 10,
      "resolution": "1080p",
      "aspect_ratio": "adaptive"
    },
    withPolling: true,
  },
);

console.log(result);
```

### Python

```python
import higgsfield_client

result = higgsfield_client.subscribe(
    'kling-video/v4.0/reference-to-video',
    arguments={'prompt': 'A cinematic scene at sunset',
         'duration': 10,
         'resolution': '1080p',
         'aspect_ratio': 'adaptive'},
)

print(result)
```

### cURL

```bash
curl --request POST \
  --url 'https://api.higgsfield.ai/kling-video/v4.0/reference-to-video' \
  --header "Authorization: Key $HF_KEY" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "prompt": "A cinematic scene at sunset",
  "duration": 10,
  "resolution": "1080p",
  "aspect_ratio": "adaptive"
}
JSON
```

## Additional Documentation

# Kling 4.0 — Reference to Video

Generate a new video guided by reference images or reference videos. Use the prompt to describe the new scene and how each reference should influence it.

**Model ID:** `kling-video/v4.0/reference-to-video`

## 1. Calling the API

Send a JSON POST request to `https://api.higgsfield.ai/kling-video/v4.0/reference-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 |
| --- | --- | --- | --- | --- |
| `prompt` | `string` | Yes | — | A non-empty prompt describing the video and the role of each reference. |
| `image_urls` | `string[]` | Conditional | — | Reference image URLs, up to 10 images. These guide the generated content; they are not middle frames in this mode. |
| `video_urls` | `string[]` | Conditional | — | Reference video URLs, up to 5 videos. These are motion/content references, not the source video to edit. |
| `duration` | `integer` | No | 10 | Output duration in seconds. Integer from 3 to 30. |
| `resolution` | `string` | No | 1080p | Output resolution: `720p` or `1080p`. |
| `aspect_ratio` | `string` | No | adaptive | Output aspect ratio: `21:9`, `16:9`, `9:16`, `1:1`, or `adaptive`. |

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

### Required references

A prompt alone is insufficient. Supply at least one non-empty `image_urls` or `video_urls` list. Empty lists do not satisfy the reference requirement.

### Reference IDs in prompts

Images are addressed as `@image_1`, `@image_2`, and so on, and videos as `@video_1`, `@video_2`, and so on, following array order.

This mode creates a new video from references. To edit an existing source video, use `kling-video/v4.0/video-edit` and its required `video_url`.

### Input video processing

Each supplied video URL is subject to a 2 GiB download limit. Input videos longer than 30 seconds are trimmed to their first 30 seconds before generation. This does not change the requested output `duration`, which remains an integer from 3 to 30 seconds.

## 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/reference-to-video",
  {
    input: {
      "prompt": "Use the character from @image_1 in a new scene walking through a sunlit market. Follow the camera motion from @video_1.",
      "image_urls": [
        "https://example.com/character.jpg"
      ],
      "video_urls": [
        "https://example.com/camera-reference.mp4"
      ],
      "duration": 10,
      "resolution": "1080p",
      "aspect_ratio": "16:9"
    },
    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/reference-to-video',
    arguments={'prompt': 'Use the character from @image_1 in a new scene walking through a '
                   'sunlit market. Follow the camera motion from @video_1.',
         'image_urls': ['https://example.com/character.jpg'],
         'video_urls': ['https://example.com/camera-reference.mp4'],
         'duration': 10,
         'resolution': '1080p',
         'aspect_ratio': '16:9'},
)

print(result)
```

```bash control=language group=submit variant=curl label=cURL
curl --request POST \
  --url 'https://api.higgsfield.ai/kling-video/v4.0/reference-to-video' \
  --header "Authorization: Key $HF_KEY" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "prompt": "Use the character from @image_1 in a new scene walking through a sunlit market. Follow the camera motion from @video_1.",
  "image_urls": [
    "https://example.com/character.jpg"
  ],
  "video_urls": [
    "https://example.com/camera-reference.mp4"
  ],
  "duration": 10,
  "resolution": "1080p",
  "aspect_ratio": "16:9"
}
JSON
```

### Image references only

Use this JSON body with the same model endpoint:

```json
{
  "prompt": "Place the character from @image_1 in a snowy mountain scene with a slow camera orbit.",
  "image_urls": [
    "https://example.com/character.jpg"
  ],
  "duration": 10,
  "resolution": "1080p",
  "aspect_ratio": "16:9"
}
```

## 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.

A prompt with no usable reference is invalid. An empty reference array does not satisfy the source requirement.

## Additional Resources

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