# Kling Omni

> Kling Omni Image Reference generates videos from images and text prompts, allowing customization of duration, aspect ratio, and elements. It supports modes for standard or professional output, making it suitable for creating dynamic video content from static images.

## Overview

- **Endpoint**: `https://api.higgsfield.ai/kling-video/omni/image-reference`
- **Model ID**: `kling-video/omni/image-reference`
- **Category**: image2video
- **Kind**: inference
- **Tags**: partners, commercial_use

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

- **`mode`** (`string`, _optional_):
  - Default: `"pro"`
  - Options: `std`, `pro`

- **`prompt`** (`string`, _required_):
  Write your prompt here

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

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

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

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

### Input JSON Schema

```json
{
  "type": "object",
  "title": "Kling Omni Playground",
  "required": [
    "prompt"
  ],
  "properties": {
    "mode": {
      "enum": [
        "std",
        "pro"
      ],
      "type": "string",
      "default": "pro"
    },
    "prompt": {
      "type": "string",
      "title": "Prompt",
      "description": "Write your prompt here"
    },
    "duration": {
      "type": "integer",
      "title": "Duration",
      "default": 5,
      "maximum": 10,
      "minimum": 3
    },
    "elements": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "image_urls": {
      "type": "array",
      "items": {
        "type": "string",
        "title": "Image URL",
        "format": "uri"
      }
    },
    "aspect_ratio": {
      "enum": [
        "16:9",
        "9:16",
        "1:1"
      ],
      "type": "string",
      "default": "16:9"
    }
  }
}
```

### Required Parameters Example

```json
{
  "mode": "pro",
  "prompt": "A cinematic scene at sunset",
  "duration": 5,
  "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/omni/image-reference",
  {
    input: {
      "mode": "pro",
      "prompt": "A cinematic scene at sunset",
      "duration": 5,
      "aspect_ratio": "16:9"
    },
    withPolling: true,
  },
);

console.log(result);
```

### Python

```python
import higgsfield_client

result = higgsfield_client.subscribe(
    'kling-video/omni/image-reference',
    arguments={'mode': 'pro',
         'prompt': 'A cinematic scene at sunset',
         'duration': 5,
         'aspect_ratio': '16:9'},
)

print(result)
```

### cURL

```bash
curl --request POST \
  --url 'https://api.higgsfield.ai/kling-video/omni/image-reference' \
  --header "Authorization: Key $HF_KEY" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "mode": "pro",
  "prompt": "A cinematic scene at sunset",
  "duration": 5,
  "aspect_ratio": "16:9"
}
JSON
```

## Additional Documentation

# About

**Kling Omni** uses the model ID `kling-video/omni/image-reference`. Kling Omni Image Reference generates videos from images and text prompts, allowing customization of duration, aspect ratio, and elements. It supports modes for standard or professional output, making it suitable for creating dynamic video content from static images.

## 1. Calling the API

Send requests to `https://api.higgsfield.ai/kling-video/omni/image-reference` with a JSON body matching the parameters below.

### Install

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

### Setup

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

### Request parameters

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `mode` | `string` | No | `"pro"` | Options: std, pro. |
| `prompt` | `string` | Yes | `—` | Prompt. |
| `duration` | `integer` | No | `5` | Duration. Minimum: 3. Maximum: 10. |
| `elements` | `array[string]` | No | `—` |  |
| `image_urls` | `array[string]` | No | `—` |  |
| `aspect_ratio` | `string` | No | `"16:9"` | Options: 16:9, 9:16, 1:1. |

## 2. Authentication

The official SDKs read credentials from the server environment and send the required `Authorization: Key KEY_ID:KEY_SECRET` header.

### API Key

Never expose the secret in browser-side code or commit it to source control. The TypeScript SDK is server-side only. For direct HTTP calls, use:

```http
Authorization: Key $HF_KEY
```

## 3. Queue

`subscribe` submits the asynchronous request and waits for a terminal result. The TypeScript SDK polls automatically when `withPolling: true`; the Python SDK's synchronous `subscribe` call also waits. A completed request returns the generated file in the `video` field.

### 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/omni/image-reference",
  {
    input: {
      "mode": "pro",
      "prompt": "A cinematic scene at sunset",
      "duration": 5,
      "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/omni/image-reference',
    arguments={'mode': 'pro',
         'prompt': 'A cinematic scene at sunset',
         'duration': 5,
         '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/omni/image-reference' \
  --header "Authorization: Key $HF_KEY" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "mode": "pro",
  "prompt": "A cinematic scene at sunset",
  "duration": 5,
  "aspect_ratio": "16:9"
}
JSON
```

### Explicit lifecycle control

Use the Python SDK when a worker needs explicit status, result, or cancellation control for an existing request. The TypeScript v2 client currently exposes automatic polling through `subscribe`.

```python
import higgsfield_client

request_id = "{request_id}"
status = higgsfield_client.status(request_id=request_id)
result = higgsfield_client.result(request_id=request_id)
higgsfield_client.cancel(request_id=request_id)
```

## Additional Resources

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