# Kling 4.0

## Overview

- **Endpoint**: `https://api.higgsfield.ai/kling-video/v4.0/video-edit`
- **Model ID**: `kling-video/v4.0/video-edit`
- **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_):

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

- **`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
{
  "type": "object",
  "required": [
    "prompt",
    "video_url"
  ],
  "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
    },
    "video_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,
  "video_url": "https://example.com/input.mp4",
  "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/video-edit",
  {
    input: {
      "prompt": "A cinematic scene at sunset",
      "duration": 10,
      "video_url": "https://example.com/input.mp4",
      "resolution": "1080p",
      "aspect_ratio": "adaptive"
    },
    withPolling: true,
  },
);

console.log(result);
```

### Python

```python
import higgsfield_client

result = higgsfield_client.subscribe(
    'kling-video/v4.0/video-edit',
    arguments={'prompt': 'A cinematic scene at sunset',
         'duration': 10,
         'video_url': 'https://example.com/input.mp4',
         'resolution': '1080p',
         'aspect_ratio': 'adaptive'},
)

print(result)
```

### cURL

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

## Additional Documentation

# Kling 4.0 — Video Edit

Edit an existing video using a text instruction. Supply the source video separately from optional image and video references that guide the edit.

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

## 1. Calling the API

Send a JSON POST request to `https://api.higgsfield.ai/kling-video/v4.0/video-edit`. 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 instruction describing the edit to the source video. |
| `video_url` | `string` | Yes | — | The single source video to edit. Displayed separately as Video to edit in Playground. |
| `image_urls` | `string[]` | No | — | Reference image URLs, up to 10 images. These guide the generated content; they are not middle frames in this mode. |
| `video_urls` | `string[]` | No | — | 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

### Source video versus references

`video_url` is the required source video to edit. `video_urls` contains optional reference videos; it does not replace the source. `image_urls` contains optional reference images. A source video plus a prompt is sufficient; references are not required.

In Playground, upload the source into **Video to edit**. Upload optional images and videos into the separate references block.

### Reference IDs in edit prompts

The source is `@video_1`. Reference videos from `video_urls` start at `@video_2`, in array order. Reference images start at `@image_1`, in array order.

`duration` controls the requested output duration; it is not automatically copied from the source video's length.

### 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/video-edit",
  {
    input: {
      "prompt": "Edit @video_1 to change the scene to golden-hour lighting while preserving the subject's movement.",
      "video_url": "https://example.com/source-video.mp4",
      "duration": 10,
      "resolution": "1080p",
      "aspect_ratio": "adaptive"
    },
    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/video-edit',
    arguments={'prompt': 'Edit @video_1 to change the scene to golden-hour lighting while '
                   "preserving the subject's movement.",
         'video_url': 'https://example.com/source-video.mp4',
         'duration': 10,
         'resolution': '1080p',
         'aspect_ratio': 'adaptive'},
)

print(result)
```

```bash control=language group=submit variant=curl label=cURL
curl --request POST \
  --url 'https://api.higgsfield.ai/kling-video/v4.0/video-edit' \
  --header "Authorization: Key $HF_KEY" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "prompt": "Edit @video_1 to change the scene to golden-hour lighting while preserving the subject's movement.",
  "video_url": "https://example.com/source-video.mp4",
  "duration": 10,
  "resolution": "1080p",
  "aspect_ratio": "adaptive"
}
JSON
```

### Edit with image and motion references

Use this JSON body with the same model endpoint:

```json
{
  "prompt": "Edit @video_1 using the visual style of @image_1 and the camera motion of @video_2.",
  "video_url": "https://example.com/source-video.mp4",
  "image_urls": [
    "https://example.com/style-reference.jpg"
  ],
  "video_urls": [
    "https://example.com/motion-reference.mp4"
  ],
  "duration": 10,
  "resolution": "1080p",
  "aspect_ratio": "adaptive"
}
```

## 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 reference video in `video_urls` does not satisfy the required `video_url`. Keep the source and reference roles separate.

## Additional Resources

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