# Kling 4.0

> Create videos with Kling 4.0 from text, images, and video references. Generate up to 30-second clips in 1080p, guide keyframes, and edit existing videos.

## Overview

- **Endpoint**: `https://api.higgsfield.ai/kling-video/v4.0/text-to-video`
- **Model ID**: `kling-video/v4.0/text-to-video`
- **Category**: image2video
- **Kind**: inference
- **Tags**: banner, featured, trending

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

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

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

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

### Input JSON Schema

```json
{
  "type": "object",
  "required": [
    "prompt"
  ],
  "properties": {
    "prompt": {
      "type": "string",
      "minLength": 1
    },
    "duration": {
      "type": "integer",
      "default": 10,
      "maximum": 30,
      "minimum": 3
    },
    "resolution": {
      "enum": [
        "720p",
        "1080p"
      ],
      "type": "string",
      "default": "1080p"
    },
    "aspect_ratio": {
      "enum": [
        "21:9",
        "16:9",
        "9:16",
        "1:1"
      ],
      "type": "string",
      "default": "16:9"
    }
  },
  "additionalProperties": true
}
```

### Required Parameters Example

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

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

console.log(result);
```

### Python

```python
import higgsfield_client

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

print(result)
```

### cURL

```bash
curl --request POST \
  --url 'https://api.higgsfield.ai/kling-video/v4.0/text-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": "16:9"
}
JSON
```

## Additional Documentation

# Kling 4.0 — Text to Video

Generate a video from a text prompt. Describe the subject, action, scene, lighting, and camera movement. This endpoint uses text input and does not expose image or video reference parameters.

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

## 1. Calling the API

Send a JSON POST request to `https://api.higgsfield.ai/kling-video/v4.0/text-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 description of the video to generate. |
| `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 | 16:9 | Output aspect ratio: `21:9`, `16:9`, `9:16`, or `1:1`. `adaptive` is not supported by this endpoint. |

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

Supply a non-empty `prompt`. Use concrete motion and camera instructions, for example a tracking shot, a slow pan, or a stationary camera. Select the output framing with `aspect_ratio`.

To animate existing images, use `kling-video/v4.0/image-to-video`. To guide a new video with image or video references, use `kling-video/v4.0/reference-to-video`.

## 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/text-to-video",
  {
    input: {
      "prompt": "A red tram travels along a rain-soaked street at dusk. Warm windows reflect in the pavement as the camera tracks alongside it.",
      "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/text-to-video',
    arguments={'prompt': 'A red tram travels along a rain-soaked street at dusk. Warm '
                   'windows reflect in the pavement as the camera tracks alongside '
                   'it.',
         '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/text-to-video' \
  --header "Authorization: Key $HF_KEY" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "prompt": "A red tram travels along a rain-soaked street at dusk. Warm windows reflect in the pavement as the camera tracks alongside it.",
  "duration": 10,
  "resolution": "1080p",
  "aspect_ratio": "16:9"
}
JSON
```

## 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 non-empty prompt is required. Use one of the four listed aspect ratios; `adaptive` is not allowed for Text to Video.

## Additional Resources

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