Kling O3 — Image reference API - Higgsfield API Docs

← Kling O3 Endpoint: POST https://api.higgsfield.ai/kling-video/o3/image-reference Endpoint ID: kling-video/o3/image-reference ▶Open API PlaygroundKling O3 · Image reference↗

Usage notes

Supply image_urls for visual references. Reference images are optional in the schema.
For a single shot, set multi_shots to false and provide prompt. For multiple shots, set multi_shots to true and provide 1–6 multi_prompt objects, each containing prompt and a positive integer duration.
Always include a non-empty top-level prompt, including when using multi_prompt.
Each shot prompt is limited to 512 characters. Custom-shot durations are summed for generation and billing; the top-level duration does not override that sum.
Native audio uses sound: on or off and defaults to off.
A multi_prompt shot must last at least 1 second; zero-second shots are rejected even though the schema permits zero.
When multi_shots is true, multi_prompt is required even with shot_type set to intelligent.
Keep the top-level prompt within 2,500 characters; longer prompts are truncated.
elements contains Kling element IDs as decimal strings. Each ID must belong to the account making the request; arbitrary provider IDs are rejected.
The example.com media URLs are placeholders. Replace them with public HTTPS URLs to your own media before submitting.

Quick start

Replace the example media URLs with publicly accessible URLs for your own files before submitting.

curl --request POST \
  --url https://api.higgsfield.ai/kling-video/o3/image-reference \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: ${IDEMPOTENCY_KEY}" \
  --data '{
  "prompt": "A slow cinematic camera move around the subject in warm evening light.",
  "image_urls": [
    "https://example.com/reference-image.jpg"
  ],
  "multi_shots": false
}'

import higgsfield_client

arguments = (
    {'prompt': 'A slow cinematic camera move around the subject in warm evening '
               'light.',
     'image_urls': ['https://example.com/reference-image.jpg'],
     'multi_shots': False}
)
result = higgsfield_client.subscribe(
    "kling-video/o3/image-reference",
    arguments=arguments,
)
print(result["video"]["url"])

import { config, higgsfield } from "@higgsfield/client/v2";

config({ credentials: process.env.HF_CREDENTIALS });

const result = await higgsfield.subscribe("kling-video/o3/image-reference", {
  input:
    {
      "prompt": "A slow cinematic camera move around the subject in warm evening light.",
      "image_urls": [
        "https://example.com/reference-image.jpg"
      ],
      "multi_shots": false
    },
  withPolling: true,
});

if (result.status === "completed") {
  console.log(result.video?.url);
}

Input schema

string

default:"std"

Allowed values: "std", "pro", "4k".

string

default:"off"

Enable sound for the output video. Allowed values: "on", "off".

string

Write your prompt here

integer

default:"5"

Requested output duration in seconds. Minimum: 3. Maximum: 15.

array

Each item: string.

string

default:"customize"

Allowed values: "customize", "intelligent".

array

Ordered public image reference URLs. Each item: string. Format: uri.

boolean

default:"false"

See the complete JSON schema below.

string

Output width-to-height ratio. Allowed values: "16:9", "9:16", "1:1".

array

Minimum items: 1. Maximum items: 6.

Show Nested fields

string

Text instructions for the generation or edit. Maximum characters: 512.

integer

Requested output duration in seconds. Minimum: 0. Maximum: 15.

string

Format: uri.

string

Format: uri.

Complete JSON schema

{
  "if": {
    "properties": {
      "multi_shots": {
        "const": true
      }
    }
  },
  "else": {
    "required": [
      "prompt"
    ]
  },
  "then": {
    "required": [
      "multi_prompt"
    ]
  },
  "type": "object",
  "title": "Kling Omni Playground",
  "properties": {
    "mode": {
      "enum": [
        "std",
        "pro",
        "4k"
      ],
      "type": "string",
      "default": "std"
    },
    "sound": {
      "enum": [
        "on",
        "off"
      ],
      "type": "string",
      "default": "off"
    },
    "prompt": {
      "type": "string",
      "title": "Prompt",
      "description": "Write your prompt here"
    },
    "duration": {
      "type": "integer",
      "title": "Duration",
      "default": 5,
      "maximum": 15,
      "minimum": 3
    },
    "elements": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "shot_type": {
      "enum": [
        "customize",
        "intelligent"
      ],
      "type": "string",
      "default": "customize"
    },
    "image_urls": {
      "type": "array",
      "items": {
        "type": "string",
        "title": "Image URL",
        "format": "uri"
      }
    },
    "multi_shots": {
      "type": "boolean",
      "default": false
    },
    "aspect_ratio": {
      "enum": [
        "16:9",
        "9:16",
        "1:1"
      ],
      "type": "string"
    },
    "multi_prompt": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "prompt": {
            "type": "string",
            "maxLength": 512
          },
          "duration": {
            "type": "integer",
            "maximum": 15,
            "minimum": 0
          }
        }
      },
      "maxItems": 6,
      "minItems": 1
    },
    "last_frame_url": {
      "type": "string",
      "title": "Last frame URL",
      "format": "uri"
    },
    "first_frame_url": {
      "type": "string",
      "title": "First frame URL",
      "format": "uri"
    }
  }
}

Response

Submission returns a request handle. Poll status_url until status is completed, or use webhooks.

Accepted

{
  "status": "queued",
  "request_id": "REQUEST_ID",
  "status_url": "https://api.higgsfield.ai/requests/REQUEST_ID/status",
  "cancel_url": "https://api.higgsfield.ai/requests/REQUEST_ID/cancel"
}

A completed response includes the following output fields:

{
  "status": "completed",
  "request_id": "REQUEST_ID",
  "video": {
    "url": "https://example.com/output.mp4"
  }
}

See idempotent requests, polling, request errors and authentication for shared request handling.

Get started

Model API reference

Core concepts

SDKs

Organizations

API reference

Resources

Kling O3 — Image reference API

Usage notes

Quick start

Input schema

Response

​Usage notes

​Quick start

​Input schema

​Response

Usage notes

Quick start

Input schema

Response