Overview
Text-to-video and image-to-video generation with Kling. Recognized for smooth motion dynamics, scene consistency, and high visual fidelity.
Primary Endpoint
/api/v1/klingVideo/startGenerate videos using Kling Official API. **Modes:** - `text-to-video` – generate video from text prompt - `image-to-video` – generate video from an image (+ optional end frame in PRO) - `motion-control` – transfer motion from a video onto an image **Versions:** `2.6` (5s/10s) and `3.0` (standard/fast: 3s–15s) **Quality:** `std` (Standard), `pro` (Professional), or `4k` (Kling 3.0 Native 4K for text/image video). ### Request - Send a valid bearer token. The server evaluates the operation in the authenticated caller's access context. - Send an `application/json` body. Required fields: `mode`, `prompt`. - API-token callers may include `webhook_url` and `webhook_token` for best-effort terminal-state notifications; ordinary JWT/cookie calls ignore these fields. ### Behavior - This is an asynchronous operation: a successful submission creates a task and returns before processing finishes. - Persist the returned task identifier and use the corresponding detail or list operation to observe progress. - Treat the detail endpoint as the source of truth even when webhook delivery is enabled. ### Response - A `200` response confirms task acceptance; it does not by itself mean media generation has completed. - Retain the returned identifier and wait for a documented terminal status before using output URLs. - JSON object responses, including error responses, normally carry a top-level `trace_id` string for this request; include it when contacting support. It is not a task identifier. - Do not infer undocumented fields or statuses; clients should tolerate additional response properties. ### Errors - `400` — Bad Request - Invalid parameters. - `401` — Unauthorized - Invalid or missing JWT token. ### Related Operations - `GET /api/v1/klingVideo/allRecords` — Get all Kling video records. - `GET /api/v1/klingVideo/{_id}` — Get Kling video detail. - `PUT /api/v1/klingVideo/{_id}` — Update Kling video name. Authentication: set header Authorization: Bearer <token> (supports user JWT or sk_ API token).
Request Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | No | Name of the video generation task |
| mode | enum: text-to-video | image-to-video | motion-control | Yes | Generation mode: text-to-video, image-to-video, or motion-control |
| prompt | string | Yes | Text prompt describing the desired video |
| version | enum: 2.6 | 3.0 | No | Kling model version. 2.6 supports 5s/10s, 3.0 supports 5s/10s/15s; default: "2.6" |
| model_version | enum: standard | fast | No | Kling 3.0 model variant. fast requires version=3.0, supports text-to-video/image-to-video, supports 3–15s, and uses resolution instead of quality_mode=4k.; default: "standard" |
| resolution | enum: 720p | 1080p | No | Output resolution for model_version=fast; default: "720p" |
| quality_mode | enum: std | pro | 4k | No | Quality mode. 4K is only available for Kling 3.0 text-to-video and image-to-video; default: "std" |
| duration | enum: 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | No | Video duration in seconds. Kling 2.6 supports 5s/10s; Kling 3.0 supports 3–15s.; default: "5" |
| image_url | string | No | Input image URL (required for image-to-video and motion-control modes) |
| video_url | string | No | Input video URL (required for motion-control mode) |
| aspect_ratio | enum: 16:9 | 9:16 | 1:1 | No | Video aspect ratio (text-to-video mode only); default: "16:9" |
| sound | boolean | No | Enable audio generation. For v2.6 only available in PRO mode (STD does not support sound). v3.0 supports sound in STD/PRO. 4K is billed as a separate quality tier.; default: false |
| end_image_url | string | No | End frame image URL (image-to-video + PRO mode only). Cannot be used with sound in v2.6 |
| character_orientation | enum: video | image | No | Character orientation for motion-control mode. 'image' limits duration to 3-10s, 'video' allows 3-30s; default: "video" |
| negative_prompt | string | No | Negative prompt to avoid certain elements |
| seed | number | No | Random seed for reproducibility |
| minor_suspected_skip | boolean | No | Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block.; default: false |
| webhook_url | string | No | HTTPS URL to receive task.completed / task.failed notifications. Best-effort delivery, single attempt, no retries; clients should treat the detail API as the source of truth.; maxLength: 2048 |
| webhook_token | string | No | Optional plaintext token returned in the X-A2e-Webhook-Token header so receivers can verify the request originated from a2e.; maxLength: 256 |
Request schema and conditional rules
{
"allOf": [
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the video generation task",
"example": "My Kling Video"
},
"mode": {
"type": "string",
"enum": [
"text-to-video",
"image-to-video",
"motion-control"
],
"description": "Generation mode: text-to-video, image-to-video, or motion-control",
"example": "image-to-video"
},
"prompt": {
"type": "string",
"description": "Text prompt describing the desired video",
"example": "A beautiful sunset over the ocean"
},
"version": {
"type": "string",
"enum": [
"2.6",
"3.0"
],
"description": "Kling model version. 2.6 supports 5s/10s, 3.0 supports 5s/10s/15s",
"default": "2.6",
"example": "3.0"
},
"model_version": {
"type": "string",
"enum": [
"standard",
"fast"
],
"description": "Kling 3.0 model variant. fast requires version=3.0, supports text-to-video/image-to-video, supports 3–15s, and uses resolution instead of quality_mode=4k.",
"default": "standard",
"example": "fast"
},
"resolution": {
"type": "string",
"enum": [
"720p",
"1080p"
],
"description": "Output resolution for model_version=fast",
"default": "720p",
"example": "720p"
},
"quality_mode": {
"type": "string",
"enum": [
"std",
"pro",
"4k"
],
"description": "Quality mode. 4K is only available for Kling 3.0 text-to-video and image-to-video",
"default": "std",
"example": "std"
},
"duration": {
"type": "string",
"enum": [
"3",
"4",
"5",
"6",
"7",
"8",
"9",
"10",
"11",
"12",
"13",
"14",
"15"
],
"description": "Video duration in seconds. Kling 2.6 supports 5s/10s; Kling 3.0 supports 3–15s.",
"default": "5",
"example": "5"
},
"image_url": {
"type": "string",
"description": "Input image URL (required for image-to-video and motion-control modes)",
"example": "https://example.com/input.jpg"
},
"video_url": {
"type": "string",
"description": "Input video URL (required for motion-control mode)",
"example": "https://example.com/input.mp4"
},
"aspect_ratio": {
"type": "string",
"enum": [
"16:9",
"9:16",
"1:1"
],
"description": "Video aspect ratio (text-to-video mode only)",
"default": "16:9",
"example": "16:9"
},
"sound": {
"type": "boolean",
"description": "Enable audio generation. For v2.6 only available in PRO mode (STD does not support sound). v3.0 supports sound in STD/PRO. 4K is billed as a separate quality tier.",
"default": false,
"example": false
},
"end_image_url": {
"type": "string",
"description": "End frame image URL (image-to-video + PRO mode only). Cannot be used with sound in v2.6",
"example": "https://example.com/end_frame.jpg"
},
"character_orientation": {
"type": "string",
"enum": [
"video",
"image"
],
"description": "Character orientation for motion-control mode. 'image' limits duration to 3-10s, 'video' allows 3-30s",
"default": "video",
"example": "video"
},
"negative_prompt": {
"type": "string",
"description": "Negative prompt to avoid certain elements",
"example": "blurry, low quality"
},
"seed": {
"type": "number",
"description": "Random seed for reproducibility",
"example": 12345
},
"minor_suspected_skip": {
"type": "boolean",
"default": false,
"description": "Set to true when retrying after error code 1004 to confirm and bypass the suspected-minor soft block."
}
},
"required": [
"mode",
"prompt"
]
},
{
"$ref": "#/components/schemas/WebhookInput"
}
]
}Response Fields
- code: integer
- message: string
- data: object
- trace_id: string
- Trace ID of this HTTP request. Include it when contacting support about this request. It is generated per request and is not a task identifier; use the returned task `_id` to query results.
Request Example
curl -X POST "https://headswap.app/api/v1/klingVideo/start" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"mode": "image-to-video",
"prompt": "A beautiful sunset over the ocean"
}'Related Endpoints
/api/v1/klingVideo/{_id}Get Kling video detail
/api/v1/klingVideo/startStart Kling video generation
/api/v1/klingVideo/allRecordsGet all Kling video records
/api/v1/klingVideo/batchDetailBatch query task details
/api/v1/klingVideo/{_id}Update Kling video name
/api/v1/klingVideo/{_id}Delete Kling video
Responses
Video generation task started successfully. Each returned task exposes optional boolean hasRefundCoin (true: refund recorded; false: not refunded; omitted: unknown). A generation failure reason does not prove that a refund was recorded.
Bad Request - Invalid parameters
Unauthorized - Invalid or missing bearer token