Name: Kling v2.6 Motion Control API: Character Animation
Brand: magicapi
SKU: api-magicapi-character-action-control-ai-kwaivgi-kling-v2-6-motion-control
Availability: InStock
Author: API Market

Shashank Agarwal

# 🎭 Precise Character Action Control API (Kling v2.6)

## Overview
The Precise Character Action Control API (Kling v2.6) enables the precise control of character actions and expressions within a reference image by utilizing motion from a reference video. The API is built to transform an image into a motion-filled video that corresponds to the actions presented in the video input. Users can select between standard and professional video generation modes to achieve different levels of output quality.

## Features
- **Character Animation**: Animate characters from a reference image using motions from a reference video.
- **Video Generation Modes**: Offers both standard and professional modes for video generation, catering to different quality requirements.
- **Sound Options**: Allows users to choose whether to keep the original sound of the video.
- **Orientation Control**: Supports generating character orientation based either on the image or the video.
- **Custom Prompts**: Users can utilize text prompts to add elements and achieve specific motion effects.

## Use Cases
- **Entertainment Industry**: Automate the creation of animated video content from static character designs for films, games, and social media.
- **Advertising**: Generate personalized video advertisements by animating characters with target audience-specific actions.
- **Education**: Transform educational images and diagrams into animated videos to make learning more engaging and interactive.
- **Virtual Assistants**: Develop dynamic avatars for virtual assistants that mimic real-time actions and expressions.
- **Social Media Content Creation**: Create lively and engaging social media posts by animating static images with motion-based video content.

## Visual Examples

### Example Input

```json
{
  "input": {
    "image": "https://blog.api.market/wp-content/uploads/2026/09/kling-v2-6-motion-control-input-character-api-market.webp",
    "video": "https://blog.api.market/wp-content/uploads/2026/09/kling-v2-6-motion-control-input-motion-api-market.mp4",
    "mode": "pro",
    "character_orientation": "video",
    "keep_original_sound": false
  }
}
```

![Character image, generated with P-Image on api.market](https://blog.api.market/wp-content/uploads/2026/09/kling-v2-6-motion-control-input-character-api-market.webp)

![Motion reference video, generated with Kling 2.5 Turbo Pro on api.market](https://blog.api.market/wp-content/uploads/2026/09/kling-v2-6-motion-control-input-motion-api-market.mp4)

### Example Output

![Example output](https://blog.api.market/wp-content/uploads/2026/09/kling-v2-6-motion-control-output-api-market.mp4)

This exact request was run through api.market and billed 19 API units ($1.672).
## Pricing
- Pay As You Go (PAYG) pricing - you only pay for what you use
- Price: $0.088 per API unit.
- 1 API unit = 1 second of output video, rounded up to whole seconds.
- The base rate applies to requests with mode: "std".
- Requests with mode: "pro" count as 1.714 units per second, rounded up to whole units per request (a 5 second clip bills 9 units).
- A request that does not choose a variant is billed at the base rate.
- Failed or cancelled predictions are not billed
- GET requests to check prediction status (GET /api/v1/magicapi/character-action-control-ai-kwaivgi-kling-v2-6-motion-control/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/character-action-control-ai-kwaivgi-kling-v2-6-motion-control`

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

### Asynchronous Processing
**IMPORTANT**: This API uses asynchronous processing for predictions. The typical flow is:
1. Submit a prediction request to the POST endpoint
2. Receive a prediction ID in the response
3. Poll the GET endpoint with the prediction ID to check status
4. Continue polling until the prediction is complete

The processing time varies depending on the complexity of the request. Your code should implement:
- A polling interval of 1 second between status checks
- A maximum timeout of 600 seconds (10 minutes)
- Status checking logic that continues while status is "starting" or "processing"
- Result handling when status becomes "succeeded"
- Error handling when status becomes "failed" or "canceled", or timeout is reached

### Endpoints
#### Create a Prediction
```bash
# Example for creating a prediction
curl -X POST "https://prod.api.market/api/v1/magicapi/character-action-control-ai-kwaivgi-kling-v2-6-motion-control/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "cdfd1d85d50b9fb970f0e864e871129f7abcfbd5caa546eb533ab12d322b06ea",
    "input": {
      "image": "https://blog.api.market/wp-content/uploads/2026/09/kling-v2-6-motion-control-input-character-api-market.webp",
      "video": "https://blog.api.market/wp-content/uploads/2026/09/kling-v2-6-motion-control-input-motion-api-market.mp4",
      "mode": "pro",
      "character_orientation": "video",
      "keep_original_sound": false
    }
  }'
```

#### Check Prediction Status
```bash
# Example for checking prediction status
curl -X GET "https://prod.api.market/api/v1/magicapi/character-action-control-ai-kwaivgi-kling-v2-6-motion-control/predictions/{id}" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

## Input Parameters
| Parameter              | Type    | Required | Default | Allowed Values         | Description |
|------------------------|---------|----------|---------|------------------------|-------------|
| `mode`                 | string  | No       | `std`   | `std`, `pro`           | Video generation mode. 'std': Standard mode (cost-effective). 'pro': Professional mode (higher quality). |
| `image`                | string  | Yes      | N/A     | N/A                    | Reference image. Supports .jpg/.jpeg/.png, max 10MB, dimensions 340px-3850px, aspect ratio 1:2.5 to 2.5:1. |
| `video`                | string  | Yes      | N/A     | N/A                    | Reference video. Supports .mp4/.mov, max 100MB, 3-30 seconds duration depending on character_orientation. |
| `prompt`               | string  | No       | ""      | N/A                    | Text prompt for video generation. You can add elements to the screen and achieve motion effects through prompt words. |
| `keep_original_sound`  | boolean | No       | `true`  | true, false            | Whether to keep the original sound of the video. |
| `character_orientation`| string  | No       | `image` | `image`, `video`       | Generate the orientation of the characters in the video. 'image': same orientation as the person in the picture (max 10s video). 'video': consistent with the orientation of the characters in the video (max 30s video). |

### Implementation Guide
#### Example Code
```javascript
// JavaScript example with proper polling and timeout
const apiKey = "YOUR_API_MARKET_KEY";
const baseUrl = "https://prod.api.market/api/v1/magicapi/character-action-control-ai-kwaivgi-kling-v2-6-motion-control";

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

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

    const prediction = await response.json();
    const predictionId = prediction.id;

    // Step 2: Poll for results with timeout
    return await pollForResults(predictionId);
  } catch (error) {
    console.error("Error:", error);
    throw error;
  }
}

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

async function pollForResults(predictionId) {
  const MAX_TIMEOUT = 600000; // 600 seconds (10 minutes)
  const POLL_INTERVAL = 1000; // 1 second between checks

  const startTime = Date.now();

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

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

    const prediction = await response.json();

    // Check status and return if completed
    if (prediction.status === "succeeded") {
      return prediction.output;
    }

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

    // Wait before next poll
    await delay(POLL_INTERVAL);
  }

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

```python
# Python example with proper polling and timeout
import requests
import time

API_KEY = "YOUR_API_MARKET_KEY"
BASE_URL = "https://prod.api.market/api/v1/magicapi/character-action-control-ai-kwaivgi-kling-v2-6-motion-control"

def create_and_wait_for_prediction(input_data):
    # Step 1: Create the prediction
    headers = {
        "Content-Type": "application/json",
        "x-api-market-key": API_KEY
    }

    response = requests.post(
        f"{BASE_URL}/predictions",
        headers=headers,
        json={"version": "cdfd1d85d50b9fb970f0e864e871129f7abcfbd5caa546eb533ab12d322b06ea", "input": input_data}
    )

    if response.status_code not in (200, 201):
        raise Exception(f"API error: {response.status_code} {response.text}")

    prediction = response.json()
    prediction_id = prediction["id"]

    # Step 2: Poll for results with timeout
    return poll_for_results(prediction_id)

def poll_for_results(prediction_id):
    MAX_TIMEOUT = 600  # 600 seconds (10 minutes)
    POLL_INTERVAL = 1  # 1 second between checks

    headers = {"x-api-market-key": API_KEY}
    start_time = time.time()

    while time.time() - start_time < MAX_TIMEOUT:
        # Check prediction status
        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()

        # Check status and return if completed
        if prediction["status"] == "succeeded":
            return prediction["output"]

        # Handle failure
        if prediction["status"] in ("failed", "canceled"):
            error_msg = prediction.get("error") or "Unknown error"
            raise Exception(f"Prediction {prediction['status']}: {error_msg}")

        # Wait before next poll
        time.sleep(POLL_INTERVAL)

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

```bash
# cURL example (can be simpler, just show the basic commands)
# Step 1: Create a prediction
curl -X POST "https://prod.api.market/api/v1/magicapi/character-action-control-ai-kwaivgi-kling-v2-6-motion-control/predictions" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
    "version": "cdfd1d85d50b9fb970f0e864e871129f7abcfbd5caa546eb533ab12d322b06ea",
    "input": {
      "image": "https://blog.api.market/wp-content/uploads/2026/09/kling-v2-6-motion-control-input-character-api-market.webp",
      "video": "https://blog.api.market/wp-content/uploads/2026/09/kling-v2-6-motion-control-input-motion-api-market.mp4",
      "mode": "pro",
      "character_orientation": "video",
      "keep_original_sound": false
    }
  }'

# Response will contain a prediction ID like:
# {"id": "abcd1234", "status": "starting"}

# Step 2: Check prediction status (replace abcd1234 with the actual ID)
curl -X GET "https://prod.api.market/api/v1/magicapi/character-action-control-ai-kwaivgi-kling-v2-6-motion-control/predictions/abcd1234" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"

# Note: You need to repeatedly poll this endpoint manually until status is "succeeded"
```

## Status Codes
- **200 OK**: Request successful
  - Explanation: The request was processed successfully, and the results are returned.
- **201 Created**: Resource successfully created
  - Explanation: The request created a new resource successfully.
- **400 Bad Request**: Invalid input parameters or malformed request
  - Explanation: The request has invalid input or syntax error.
- **401 Unauthorized**: Missing or invalid API key
  - Explanation: Authentication failed due to missing or invalid API key.
- **403 Forbidden**: Valid API key but insufficient permissions
  - Explanation: Access to the resource is forbidden with the provided API key.
- **404 Not Found**: Resource not found
  - Explanation: Specified resource does not exist.
- **429 Too Many Requests**: Rate limit exceeded
  - Explanation: The user has exceeded the allowed number of requests.
- **500 Internal Server Error**: Server-side error
  - Explanation: An error occurred on the server while processing the request.
- **503 Service Unavailable**: Service temporarily unavailable
  - Explanation: The service is temporarily unavailable. Try again later.

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

## Error Handling
### Common Error Responses
```json
{
  "error": {
    "code": "invalid_parameter",
    "message": "The parameter 'image' is required",
    "status": 400
  }
}
```
### Error Handling Best Practices
- **Interpret Error Responses**: Understand the error codes and messages returned by the API to identify the issue.
- **Resolve Common Errors**: Address errors such as invalid parameters, missing authentication, and rate limits.
- **Retry Strategies**: Implement retries for transient errors with exponential backoff.

## FAQ
**How long can the output video be?**
It follows the reference video. With `character_orientation: "image"` the character keeps the pose direction of your picture and the video can be up to 10 seconds; with `"video"` it follows the orientation in the reference video and can be up to 30 seconds. The reference video itself must be 3 to 30 seconds long.

**What do `std` and `pro` cost?**
`std` bills 1 API unit ($0.088) per second of output video. `pro` bills 1.714 units per second, rounded up per request, so a 5 second clip costs 9 units ($0.792).

**What image and video files are accepted?**
The image must be .jpg, .jpeg or .png, at most 10 MB, 340 to 3850 px on each side, with an aspect ratio between 1:2.5 and 2.5:1. The video must be .mp4 or .mov and at most 100 MB.

**Can I keep the audio of the reference video?**
Yes. `keep_original_sound` is `true` by default; set it to `false` for a silent result.

**Am I charged for failed requests?**
No. Failed or cancelled predictions are not billed, and status checks are free.

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

Transfer the motion from a reference video onto the character in a reference image with Kling v2.6 Motion Control. Pay per second of output video.