Name: Kling Video 3.0 Omni API: Multimodal Video Generation
Brand: magicapi
SKU: api-magicapi-multimodal-video-generation-api-kwaivgi-kling-v3-omni-video
Availability: InStock
Author: API Market

Shashank Agarwal

# 🎥 Unified Multimodal Video Generation API (Kling Video 3.0 Omni)

## Overview
This API runs Kling Video 3.0 Omni from Kuaishou: one model for text-to-video, start and end frame animation, reference-image generation, video reference and video editing, with optional native audio and multi-shot prompts.

You describe the video in `prompt` and can add reference images (for elements, scenes or styles), a start frame, an end frame, or a reference video. A reference video can be used as a style and camera reference (`video_reference_type: "feature"`) or as the base video to edit (`video_reference_type: "base"`). Output quality is set with `mode`: `standard` generates 720p, `pro` generates 1080p, `4k` generates 4K.

## Features
- **Text-to-video:** `prompt` is the only required field (max 2500 characters).
- **Reference images:** pass up to 7 images in `reference_images` (up to 4 when you also pass a reference video) for elements, scenes or styles. Refer to them in the prompt with template references such as `<<<image_1>>>`.
- **Start and end frames:** `start_image` sets the first frame; `end_image` (requires `start_image`) sets the last frame.
- **Reference video:** `reference_video` (.mp4/.mov, 3 to 10 seconds, 720 to 2160px per side, max 200MB). Refer to it in the prompt as `<<<video_1>>>`. `keep_original_sound` (default `true`) keeps the original sound from the reference video.
- **Video editing:** set `video_reference_type` to `base` to edit the reference video. `duration` is ignored in this case.
- **Native audio:** `generate_audio: true` generates audio with the video. It cannot be combined with a reference video.
- **Multi-shot prompts:** `multi_prompt` takes a JSON array of up to 6 shots, each at least 1 second, adding up to `duration`.
- **Quality modes:** `standard` (720p), `pro` (1080p, the default) and `4k`. 4K does not support `reference_video`.
- **Duration from 3 to 15 seconds:** default 5 seconds.

## Use Cases
1. **Reusing a character or product:** put a character or product photo in `reference_images` and place it in a new scene.
2. **Restyling and editing footage:** pass a clip as `reference_video` with `video_reference_type: "base"` and describe the change.
3. **Matching a look or camera move:** use a clip as a `feature` reference for style and camera motion.
4. **Short multi-shot sequences:** describe several shots in one request with `multi_prompt`.

## Visual Examples
This is the request we ran through api.market: one reference image, all other settings at their defaults (`mode` pro, 5 seconds, no audio).

**Prompt:** "The astronaut from the reference image walks across a red desert on Mars as dust swirls around the boots"

**Input image (`reference_images`):**

![Reference image: a white astronaut figure standing on a plain grey background](https://blog.api.market/wp-content/uploads/2026/09/kling-v2-6-motion-control-input-character-api-market.webp)

**Output:** [Watch the example video](https://blog.api.market/wp-content/uploads/2026/10/kling-v3-omni-video-output-api-market.mp4)

The linked file is a smaller re-encoded copy for this page, so its resolution is not the resolution the API returns.

## Pricing
- **Pay As You Go (PAYG) pricing:** you only pay for what you use.
- **Price:** $0.21 per API unit.
- **API unit:** billing is per second of output video, rounded up to whole seconds. The number of units per second depends on `mode` and `generate_audio`, and the total for a request is rounded up to whole units.

| `mode` | `generate_audio` | Units per second | Price per second | 5 second clip |
|--------|------------------|------------------|------------------|---------------|
| standard | false | 1 | $0.21 | 5 units ($1.05) |
| standard | true | 1.3333 | $0.28 | 7 units ($1.47) |
| pro | false | 1.3333 | $0.28 | 7 units ($1.47) |
| pro | true | 1.6667 | $0.35 | 9 units ($1.89) |
| 4k | false | 2.5 | $0.525 | 13 units ($2.73) |
| 4k | true | 2.5 | $0.525 | 13 units ($2.73) |

- A request that leaves `mode` and `generate_audio` unset uses the defaults (`pro`, no audio): $0.28 per second, so a 5 second clip bills 7 units ($1.47).
- For video editing (`video_reference_type: "base"`), `duration` is ignored and you are billed for the length of the output video.
- Failed or cancelled predictions are not billed.
- GET requests to check prediction status (GET /api/v1/magicapi/multimodal-video-generation-api-kwaivgi-kling-v3-omni-video/predictions/{id}) are free and don't count toward API unit usage.
- No monthly subscription fee.

## API Documentation
### Base URL
All API requests should be made to: `https://prod.api.market/api/v1/magicapi/multimodal-video-generation-api-kwaivgi-kling-v3-omni-video`

### Authentication
Include your api.market API key in the request header:
```
x-api-market-key: YOUR_API_MARKET_KEY
```

### Asynchronous Processing
**IMPORTANT:** This API is asynchronous.

1. Send a POST request to `/predictions`. A successful request returns **201 Created** with a prediction `id` and a `status` of `starting` or `processing`.
2. Poll GET `/predictions/{id}` with that ID.
3. Stop when `status` is `succeeded` (the video URL is in `output`), `failed` (see `error`) or `canceled`.

### Endpoints

#### POST /api/v1/magicapi/multimodal-video-generation-api-kwaivgi-kling-v3-omni-video/predictions
Create a new prediction.

```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/multimodal-video-generation-api-kwaivgi-kling-v3-omni-video/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "460d4f46adf3c29abbcd8f42cf5434570da6b50a39ec4593f2006486b1dd3fba",
    "input": {
      "prompt": "The astronaut from the reference image walks across a red desert on Mars as dust swirls around the boots",
      "reference_images": [
        "https://blog.api.market/wp-content/uploads/2026/09/kling-v2-6-motion-control-input-character-api-market.webp"
      ]
    }
  }'
```

Response (201 Created):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "460d4f46adf3c29abbcd8f42cf5434570da6b50a39ec4593f2006486b1dd3fba",
  "status": "starting",
  "created_at": "2026-10-11T19:05:14.633Z"
}
```

#### GET /api/v1/magicapi/multimodal-video-generation-api-kwaivgi-kling-v3-omni-video/predictions/{id}
Check the status of a prediction and get the result.

```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/multimodal-video-generation-api-kwaivgi-kling-v3-omni-video/predictions/ufawqhfynnddngldkgtslldrkq" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

Response when finished (200 OK):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "status": "succeeded",
  "output": "https://blog.api.market/wp-content/uploads/2026/10/kling-v3-omni-video-output-api-market.mp4",
  "error": null
}
```

`output` is a single URL to the generated video.

### Status Codes
- **200 OK:** status check succeeded.
- **201 Created:** prediction created. This is the normal response to a POST, not an error.
- **400 Bad Request:** invalid input (for example a missing `prompt` or a value outside the allowed range).
- **401 Unauthorized:** missing or invalid API key.
- **404 Not Found:** unknown prediction ID.
- **429 Too Many Requests:** rate limit exceeded. Wait and retry with backoff.
- **500 Internal Server Error:** server-side error. Retry later.

### Error Handling
- A prediction can be created (201) and still fail later. When polling, check `status`: if it is `failed`, the `error` field explains why. Failed predictions are not billed.
- Check combinations before sending: `end_image` needs `start_image`, `generate_audio` cannot be used with `reference_video`, `4k` does not support `reference_video`, and `reference_images` allows at most 7 images (4 with a reference video).
- Retry 429 and 5xx responses with exponential backoff.

## Rate Limits

All plans allow 10 requests per second. Requests above that return `429 Too Many Requests`; back off before retrying and honour any `Retry-After` header. Polling a prediction with GET is free but still counts toward the per-second limit, so poll every 1 to 5 seconds rather than in a tight loop.

## Input Parameters

| Parameter | Type | Default | Allowed Values | Required | Description |
|-----------|------|---------|----------------|----------|-------------|
| `prompt` | string | none | Text, max 2500 characters | Yes | Text prompt for video generation. Supports `<<<image_1>>>`, `<<<video_1>>>` template references. |
| `start_image` | string (URI) | null | Image URL | No | First frame image. Supports .jpg/.jpeg/.png, max 10MB, min 300px, aspect ratio 1:2.5 to 2.5:1. |
| `end_image` | string (URI) | null | Image URL | No | Last frame image. Requires `start_image`. Supports .jpg/.jpeg/.png, max 10MB, min 300px. |
| `reference_images` | array of strings (URI) | null | Image URLs | No | Reference images for elements, scenes, or styles. Supports .jpg/.jpeg/.png. Max 7 without video, 4 with video. |
| `reference_video` | string (URI) | null | Video URL | No | Reference video (.mp4/.mov). Duration 3-10s, resolution 720-2160px per side, max 200MB. |
| `video_reference_type` | string | `feature` | `feature`, `base` | No | How to use the reference video: `feature` for style/camera reference, `base` for video editing. |
| `keep_original_sound` | boolean | true | `true`, `false` | No | Keep original sound from the reference video. |
| `generate_audio` | boolean | false | `true`, `false` | No | Generate native audio. Mutually exclusive with reference video. Affects price. |
| `mode` | string | `pro` | `standard`, `pro`, `4k` | No | `standard` generates 720p, `pro` generates 1080p, `4k` generates 4K. 4K does not support `reference_video`. Affects price. |
| `aspect_ratio` | string | `16:9` | `16:9`, `9:16`, `1:1` | No | Aspect ratio. Required when not using a start frame or video editing. |
| `duration` | integer | 5 | 3 to 15 | No | Video duration in seconds. Ignored for video editing (`base`). |
| `multi_prompt` | string | null | JSON array as a string | No | Shot definitions for multi-shot mode. Each shot: `{"prompt": "...", "duration": N}`. Max 6 shots, min duration 1s per shot, total must equal `duration`. |

Example `multi_prompt` value for a 5 second video:
```json
"[{\"prompt\": \"A cat jumps\", \"duration\": 3}, {\"prompt\": \"It lands\", \"duration\": 2}]"
```

## Implementation Guide

#### JavaScript Example
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/multimodal-video-generation-api-kwaivgi-kling-v3-omni-video";

async function createAndWaitForPrediction(inputData) {
  const response = await fetch(`${baseUrl}/predictions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-market-key": apiKey
    },
    body: JSON.stringify({
      version: "460d4f46adf3c29abbcd8f42cf5434570da6b50a39ec4593f2006486b1dd3fba",
      input: inputData
    })
  });

  // 201 Created is the normal success response
  if (!response.ok) {
    throw new Error(`API error: ${response.status} ${await response.text()}`);
  }

  const prediction = await response.json();
  return await pollForResults(prediction.id);
}

function delay(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

async function pollForResults(predictionId) {
  const MAX_TIMEOUT = 600000; // 10 minutes
  const POLL_INTERVAL = 2000; // 2 seconds between checks
  const startTime = Date.now();

  while (Date.now() - startTime < MAX_TIMEOUT) {
    const response = await fetch(`${baseUrl}/predictions/${predictionId}`, {
      headers: { "x-api-market-key": apiKey }
    });

    if (!response.ok) {
      throw new Error(`API error: ${response.status} ${await response.text()}`);
    }

    const prediction = await response.json();

    if (prediction.status === "succeeded") {
      return prediction.output;
    }

    if (prediction.status === "failed" || prediction.status === "canceled") {
      throw new Error(`Prediction ${prediction.status}: ${prediction.error || "Unknown error"}`);
    }

    await delay(POLL_INTERVAL);
  }

  throw new Error("Prediction timed out after 10 minutes");
}

createAndWaitForPrediction({
  prompt: "The astronaut from the reference image walks across a red desert on Mars as dust swirls around the boots",
  reference_images: [
    "https://blog.api.market/wp-content/uploads/2026/09/kling-v2-6-motion-control-input-character-api-market.webp"
  ]
}).then(videoUrl => console.log("Video:", videoUrl));
```

#### Python Example
```python
import requests
import time

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/multimodal-video-generation-api-kwaivgi-kling-v3-omni-video"

def create_and_wait_for_prediction(input_data):
    headers = {
        "Content-Type": "application/json",
        "x-api-market-key": API_KEY,
    }
    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={
            "version": "460d4f46adf3c29abbcd8f42cf5434570da6b50a39ec4593f2006486b1dd3fba",
            "input": input_data,
        },
    )

    # 201 Created is the normal success response
    if response.status_code not in (200, 201):
        raise Exception(f"API error: {response.status_code} {response.text}")

    return poll_for_results(response.json()["id"])

def poll_for_results(prediction_id):
    MAX_TIMEOUT = 600  # 10 minutes
    POLL_INTERVAL = 2  # seconds between checks
    headers = {"x-api-market-key": API_KEY}
    start_time = time.time()

    while time.time() - start_time < MAX_TIMEOUT:
        response = requests.get(f"{BASE_URL}/predictions/{prediction_id}", headers=headers)
        if response.status_code != 200:
            raise Exception(f"API error: {response.status_code} {response.text}")

        prediction = response.json()
        if prediction["status"] == "succeeded":
            return prediction["output"]
        if prediction["status"] in ("failed", "canceled"):
            raise Exception(f"Prediction {prediction['status']}: {prediction.get('error') or 'Unknown error'}")

        time.sleep(POLL_INTERVAL)

    raise Exception("Prediction timed out after 10 minutes")

video_url = create_and_wait_for_prediction({
    "prompt": "The astronaut from the reference image walks across a red desert on Mars as dust swirls around the boots",
    "reference_images": [
        "https://blog.api.market/wp-content/uploads/2026/09/kling-v2-6-motion-control-input-character-api-market.webp"
    ],
})
print("Video:", video_url)
```

## Tips
- Use `mode: "standard"` for drafts and switch to `pro` or `4k` for final renders. Higher modes cost more per second.
- Test prompts with a short `duration` first; you pay per second of output.
- Point the prompt at your inputs with template references (`<<<image_1>>>` for a reference image, `<<<video_1>>>` for the reference video) so the model knows which input you mean.
- When editing a video (`base`), `duration` is ignored.

## FAQ
**Q: Do I need an input image?**
A: No. `prompt` is the only required field. Images and a reference video are optional.

**Q: Can I add audio when I use a reference video?**
A: Not with `generate_audio`; it is mutually exclusive with a reference video. Use `keep_original_sound` to keep the reference video's own sound.

**Q: What does the API return?**
A: When the prediction succeeds, `output` is a URL to the generated video file.

**Q: What happens if my prediction fails?**
A: Failed or cancelled predictions are not billed. Check the `error` field, fix the input and retry.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Kling Video 3.0 Omni API on api.market: video from text, reference images or a reference video, video editing, multi-shot prompts. Pay per second.

Kling Video 3.0 Omni API: Multimodal Video Generation

🎥 Unified Multimodal Video Generation API (Kling Video 3.0 Omni)

PAYG

MagicAPI

Generate and edit 3 to 15 second videos from text, reference images, start and end frames or a reference video, with optional native audio and multi-shot prompts.