Kling Omni-Video API

Quick Start

Authentication

Add Authorization header with Bearer token to all requests:

Authorization: Bearer YOUR_API_KEY

Available Models

For plain text- or image-to-video, Kling V3 (per second), Kling V2.6 (per clip) and Kling Motion Control are documented on the Kling Video API page.

Detailed Pricing (official Kling rates)

Kling Video O1

Kling V3 Omni

Endpoints

Request Parameters

Common Parameters

Advanced Parameters

Code Examples

curl -X POST https://api.apimodels.app/v1/video/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-video-o1",
    "prompt": "A girl dancing on the beach at sunset, cinematic lighting",
    "mode": "std",
    "duration": "5",
    "aspect_ratio": "16:9"
  }'

Response Format

Create Task Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "clxxx...",
    "state": "pending",
    "model": "kling-video/kling-video-o1"
  }
}

Success Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "clxxx...",
    "state": "completed",
    "model": "kling-video/kling-video-o1",
    "resultUrls": ["https://...video.mp4"],
    "createTime": 1705123450000,
    "completeTime": 1705123500000
  }
}

Failed Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "clxxx...",
    "state": "failed",
    "model": "kling-video/kling-video-o1",
    "failMsg": "Content policy violation"
  }
}

Webhook Callback (callback_url)

Pass callback_url in the create request. When the task reaches the completed or failed terminal state, our server sends a single HTTP POST to that URL with Content-Type: application/json (no signing header). Delivery is retried up to 3 times (exponential backoff 1s/2s/4s, 10s per attempt); if still unsuccessful, a background job keeps retrying for up to 30 minutes until your endpoint returns 2xx.

Payload Structure

POST {your callback_url}
Content-Type: application/json

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "clxxx...",
    "model": "kling-video/kling-video-o1",
    "state": "completed" | "failed",
    "param": "<JSON string>",            // request params, JSON.parse once
    "resultJson": "<JSON string> | null", // result object, JSON.parse once
    "failCode": null | "CONTENT_MODERATION | INVALID_INPUT | INSUFFICIENT_BALANCE | UPSTREAM_BUSY | UPSTREAM_FAILED | TIMEOUT | INTERNAL_ERROR | OTHER",
    "failMsg": null | "string",
    "retryable": true | false,           // present when state=failed: safe to retry/fallback
    "costTime": 12345,                    // duration in ms
    "completeTime": 1705123500000,        // ms epoch
    "createTime": 1705123450000           // ms epoch
  }
}

Note: data.param and data.resultJson are both JSON strings — call JSON.parse once on each.

Video task: shape after JSON.parse(data.resultJson)

{
  "resultUrls":    ["https://r2.apimodels.app/videos/xxx.mp4"],
  "videoDuration": 5                   // optional, seconds
}

resultUrls is always present (length 1 in success, [] on failure). Other fields are optional. When state=failed, resultJson is typically null or {"resultUrls":[]}.

Node.js receiver example

app.post('/webhook/kling-omni', express.json(), (req, res) => {
  const { taskId, state, resultJson, failMsg } = req.body.data
  if (state === 'completed') {
    const r = JSON.parse(resultJson)
    console.log('video ready', taskId, r.resultUrls[0], r.videoDuration)
  } else {
    console.warn('video failed', taskId, failMsg)
  }
  res.status(200).end()                 // must be 2xx, otherwise we retry
})

Notes

• -A task stops retrying only after a 2xx response — once delivered it is never pushed again.
• -Callbacks are not signed today. Embed a random token in your callback_url path and verify it on receipt.
• -Omni video jobs typically take 30s to several minutes — strongly prefer callback_url over polling.
• -Use a public HTTPS endpoint that responds within 10 seconds (per-attempt timeout).

Task States

Error Codes

Important Notes

• *Video files are stored for 30 days, download promptly
• *Omni-Video uses a single unified endpoint -- no need to choose between text-to-video and image-to-video
• *At least one of prompt, image_list, or video_list must be provided
• *Video face/character swap: the reference face must be passed as an image URL in image_list (alongside video_list) — an @mention in the prompt attaches no reference image
• *O1 supports 3-10s duration, V3 Omni supports 3-15s duration, both priced per second
• *Audio generation is available for both models (set sound: "on")
• *Use video_list with refer_type: "base" for video editing/re-creation
• *Poll every 5-10 seconds to check status