Kling Gateway Overview

Gateway Base URL: https://maasunion.com Unified prefix: All endpoints are mounted under https://maasunion.com/kling/ Official reference: Kling Open Platform Documentation

Design Principles

The Kling channel uses native pass-through: the client JSON request body is forwarded as-is to the official Kling upstream, and the response JSON structure is identical to the official one. The gateway only handles authentication, channel routing, task ID mapping, and billing.

Gateway Base URL Structure

https://maasunion.com/kling/v1/{product_line}/{resource}/...

Authentication

Client (caller)

The client does not need to and should not pass the Kling upstream API Key.

Upstream (admin backend channel configuration)

The AccessKey|SecretKey format is no longer supported, and JWT is no longer auto-generated.

Channel Types and Path Mapping

Each API capability corresponds to an independent channel type. The gateway automatically matches the required channel type based on the request path and dispatches only to channels of the corresponding type.

Gateway Path ↔ Official Upstream Mapping

image2image compatibility note: /v1/images/image2image does not exist in the official Kling API. The gateway provides /kling/v1/standard/images/image2image as a compatibility alias: a single reference image goes to generations (request body with image field), and multiple reference images go to multi-image2image.

Common Conventions

Task ID Mapping

The gateway replaces the task ID returned by the upstream with a public ID; use the public ID when querying, and the gateway maps it back to the upstream ID automatically.

Sync vs Async

Recommended Polling Strategy

1. After creating a task, obtain the task_id (id for Turbo)
2. Poll with GET every 2–5 seconds until the status is succeed or failed
3. After success, get the result URL from data.task_result (v1) or data.outputs (Turbo)

Task Status Enumerations

Note: the success status for the new API is succeeded, and for the v1 API it is succeed.

Two API Format Differences Comparison

The generated result URL is valid for 30 days; please persist it in time.

Image Material Specifications

• Format: .jpg / .jpeg / .png
• v1 endpoints: file ≤ 10MB, width/height ≥ 300px, aspect ratio 1:2.5 ~ 2.5:1
• New API: file ≤ 50MB, width/height ≥ 300px, aspect ratio 1:2.5 ~ 2.5:1
• Supports URL or Base64 (without the data:image/xxx;base64, prefix; the gateway strips this prefix automatically)

Quick Start

1. Create a channel in the admin backend

Based on the API type you want to call, select the corresponding channel type, and fill in the Kling API Key and Base URL.

2. Bind models and groups

Configure the model names (e.g. kling-v2-6, kling-video-o1) in the channel, and bind them to user groups.

3. Create a task

curl --request POST \
  --url "https://maasunion.com/kling/v1/standard/videos/text2video" \
  --header "Authorization: Bearer {your_api_token}" \
  --header "Content-Type: application/json" \
  --data '{
    "model_name": "kling-v2-6",
    "prompt": "一只猫在草地上奔跑",
    "duration": "5",
    "aspect_ratio": "16:9"
  }'

4. Poll for the task result

curl --request GET \
  --url "https://maasunion.com/kling/v1/standard/videos/text2video/{task_id}" \
  --header "Authorization: Bearer {your_api_token}"

Billing

• The gateway bills based on the models and group multipliers bound to the channel
• The final_unit_deduction (credit consumption) returned by Kling is used as a settlement reference when the task completes
• Image and video APIs go through different billing paths (the gateway distinguishes MediaKind internally by request path)
• Different API types, models, and mode (std/pro/4k) are billed differently; refer to the official Kling pricing
• The model_name in the request must match the model configured in the channel, otherwise routing or billing anomalies may occur

Error Handling

HTTP Status Codes

Business Error Codes

When the response code != 0, it indicates a business failure; message / task_status_msg contains the specific reason. Common cases:

Admin Backend Configuration

Using Kling Omni Video as an example, the steps for other types are the same; only the channel type and model name differ.

1. Go to Channel Management → New Channel
2. For Channel type, select the corresponding type (e.g. Kling Omni Video)
3. For API Base URL, fill in the Kling API address:
   • Standard video (50): https://api.klingai.com
   • Other types (62–66): https://api-beijing.klingai.com
4. For Secret key, fill in the Kling API Key
5. For Models, fill in the model names supported by the channel, and bind them to user groups
6. After saving, ensure the models are visible to the caller in the tokens/groups

If you need to use multiple Kling capabilities at the same time, you must create channels of the corresponding types separately:

Kling Video (50)      → /kling/v1/standard/videos/*
Kling Turbo (62)      → /kling/v1/turbo/*
Kling Omni Video (63) → /kling/v1/omni/videos
Kling Image (64)      → /kling/v1/standard/images/*
Kling Omni Image (65) → /kling/v1/omni/images
Kling Extended (66)   → /kling/v1/extended/*

Related Documentation

Video models

• Standard Video (Text/Image to Video)
• Kling Turbo (3.0 Turbo New API)
• Omni Video
• Motion Control
• Digital Human
• Audio Generation
• Lip Sync (Two-Step)
• Image Recognition (Sync)

Image models

• Standard Image Generation/Editing
• Omni Image
• Virtual Try-On
• Multi-Image Subject Generation

Official resources

• Kling Open Platform
• Official API Documentation Overview