Name: Kling Video 3.0 API: Text and Image to Video
Brand: magicapi
SKU: api-magicapi-cinematic-video-generation-kwaivgi-kling-v3-video
Availability: InStock
Author: API Market

Shashank Agarwal

# 🎬 Cinematic Video Generation API - Multi-Shot Control (Kling Video 3.0)

## Overview
This API runs Kling Video 3.0 from Kuaishou. It generates a video of 3 to 15 seconds from a text prompt, or animates a start frame image you provide, with optional native audio and multi-shot prompts.

You choose the output quality with `mode` (`standard` generates 720p, `pro` generates 1080p, `4k` generates 4K), the length with `duration`, and the framing with `aspect_ratio` (16:9, 9:16 or 1:1). You can also pin the last frame with `end_image`, describe what to avoid with `negative_prompt`, and split the clip into up to 6 shots with `multi_prompt`.

## Features
- **Text-to-video:** describe the scene in `prompt` (max 2500 characters).
- **Image-to-video:** pass `start_image` to use your image as the first frame. Add `end_image` (requires `start_image`) to set the last frame as well.
- **Multi-shot prompts:** `multi_prompt` takes a JSON array of shots, each with its own prompt and duration. Max 6 shots, at least 1 second per shot, and the shot durations must add up to `duration`.
- **Native audio:** set `generate_audio` to `true` to generate audio with the video (off by default).
- **Three quality modes:** `standard` (720p), `pro` (1080p, the default) and `4k`.
- **Duration from 3 to 15 seconds:** default 5 seconds.
- **Negative prompt:** list things you do not want to see (max 2500 characters).

## Use Cases
1. **Ads and product clips:** animate a product photo or key visual into a short clip with camera movement.
2. **Social media:** vertical 9:16 or square 1:1 clips from a single prompt.
3. **Storyboards and previs:** sketch a scene as several shots in one request with `multi_prompt`.
4. **Bringing stills to life:** use an illustration or photo as the first frame and describe the motion.

## Visual Examples
This is the request we ran through api.market (image-to-video with a start frame, all other settings at their defaults: `mode` pro, 5 seconds, no audio).

**Prompt:** "The camera slowly pushes in as she pulls down her hood and looks up at the glowing neon sign"

**Input image (`start_image`):**

![Start frame: a woman in a yellow raincoat on a rainy street under a pink neon api.market sign](https://blog.api.market/wp-content/uploads/2026/09/kling-v2-1-input-api-market.webp)

**Output:** [Watch the example video](https://blog.api.market/wp-content/uploads/2026/10/kling-v3-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) |
| pro | false | 1.3333 | $0.28 | 7 units ($1.47) |
| standard | true | 1.5 | $0.315 | 8 units ($1.68) |
| pro | true | 2 | $0.42 | 10 units ($2.10) |
| 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).
- Failed or cancelled predictions are not billed.
- GET requests to check prediction status (GET /api/v1/magicapi/cinematic-video-generation-kwaivgi-kling-v3-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/cinematic-video-generation-kwaivgi-kling-v3-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/cinematic-video-generation-kwaivgi-kling-v3-video/predictions
Create a new prediction.

```bash
curl -X POST "https://prod.api.market/api/v1/magicapi/cinematic-video-generation-kwaivgi-kling-v3-video/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "cadb27bd609b3432e7989ce823fb107570335cd165d83f3bddd26da045944ed3",
    "input": {
      "prompt": "The camera slowly pushes in as she pulls down her hood and looks up at the glowing neon sign",
      "start_image": "https://blog.api.market/wp-content/uploads/2026/09/kling-v2-1-input-api-market.webp"
    }
  }'
```

Response (201 Created):
```json
{
  "id": "ufawqhfynnddngldkgtslldrkq",
  "version": "cadb27bd609b3432e7989ce823fb107570335cd165d83f3bddd26da045944ed3",
  "status": "starting",
  "created_at": "2026-10-11T19:06:34.190Z"
}
```

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

```bash
curl -X GET "https://prod.api.market/api/v1/magicapi/cinematic-video-generation-kwaivgi-kling-v3-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-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.
- Validate inputs before sending: `duration` must be an integer from 3 to 15, `end_image` needs `start_image`, and `multi_prompt` shot durations must add up to `duration`.
- 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. |
| `negative_prompt` | string | `""` | Text, max 2500 characters | No | Things you do not want to see in the video. |
| `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. |
| `mode` | string | `pro` | `standard`, `pro`, `4k` | No | `standard` generates 720p, `pro` generates 1080p, `4k` generates 4K. Affects price. |
| `aspect_ratio` | string | `16:9` | `16:9`, `9:16`, `1:1` | No | Aspect ratio. Ignored when `start_image` is provided. |
| `duration` | integer | 5 | 3 to 15 | No | Video duration in seconds. |
| `generate_audio` | boolean | false | `true`, `false` | No | Generate native audio for the video. Affects price. |
| `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 1s per shot, total must equal `duration`. |

Example `multi_prompt` value for a 5 second video:
```json
"[{\"prompt\": \"A lighthouse on a cliff at dusk\", \"duration\": 3}, {\"prompt\": \"The lighthouse beam sweeps across the sea\", \"duration\": 2}]"
```

## Implementation Guide

#### JavaScript Example
```javascript
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/cinematic-video-generation-kwaivgi-kling-v3-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: "cadb27bd609b3432e7989ce823fb107570335cd165d83f3bddd26da045944ed3",
      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 camera slowly pushes in as she pulls down her hood and looks up at the glowing neon sign",
  start_image: "https://blog.api.market/wp-content/uploads/2026/09/kling-v2-1-input-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/cinematic-video-generation-kwaivgi-kling-v3-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": "cadb27bd609b3432e7989ce823fb107570335cd165d83f3bddd26da045944ed3",
            "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 camera slowly pushes in as she pulls down her hood and looks up at the glowing neon sign",
    "start_image": "https://blog.api.market/wp-content/uploads/2026/09/kling-v2-1-input-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.
- You only pay for the seconds you generate, so test prompts with a short `duration` first.
- `generate_audio: true` raises the price per second in `standard` and `pro` mode; leave it off if you add your own soundtrack.
- When you pass `start_image`, the output follows the image's framing and `aspect_ratio` is ignored.

## FAQ
**Q: Can I generate video without an input image?**
A: Yes. `prompt` is the only required field. Without `start_image`, the video is generated from the text and `aspect_ratio` sets the framing.

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

**Q: How long can a video be?**
A: 3 to 15 seconds, set with `duration`. With `multi_prompt`, the shot durations must add up to `duration`.

**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 API on api.market: 3 to 15 second videos from text or a start frame, multi-shot prompts, optional audio. Pay per second of video.