Kling-style asynchronous media API

Beginner: separate the site route from direct Kling

/kling/v1/* is a Kling-style compatibility route exposed by this site. It retains familiar action paths, while authentication, public task IDs, and retrieval responses are managed by the gateway; it is not an unconditional pass-through to api.klingai.com. Send the site's Authorization: Bearer $API_KEY here. A direct Kling integration signs a short-lived JWT from its Access Key and Secret Key according to the official documentation. Never interchange those credentials or base URLs.

The consumer product, Kling's official API, and the site's adapted capabilities are also different sets. Confirm the exact model and current availability in the model marketplace.

Minimal text-to-video request

Copycreate=$(curl -sS "$BASE_URL/kling/v1/videos/text2video" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_name":"kling-v3",
    "prompt":"A layered paper-cut rabbit crossing a misty forest, slow dolly in",
    "negative_prompt":"blur, flicker",
    "mode":"std",
    "duration":"5",
    "aspect_ratio":"16:9"
  }')

task_id=$(printf '%s' "$create" | jq -r '.id // .task_id')
test -n "$task_id" && test "$task_id" != "null"

Creation returns the public site id/task_id; Kling's upstream request_id and internal task ID may be retained separately. Store the site Request-ID, public task ID, action kind, model, creation time, and redacted parameters. HTTP 200 means submitted, not completed.

Image-to-video and action selection

Use POST /kling/v1/videos/image2video with image; an optional last frame is image_tail. A reference can be an HTTPS URL or another encoding supported by the selected model and channel. text2video, image2video, effects, lip-sync, and extend actions have different required fields. Changing only the URL while reusing one request body is unsafe.

Copycurl "$BASE_URL/kling/v1/videos/image2video" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model_name":"kling-v3","image":"https://assets.example.com/input.jpg","prompt":"The subject turns toward the camera","duration":"5"}'

Retrieval, terminal states, and output

Retrieve with the same action family used for creation:

Copycurl "$BASE_URL/kling/v1/videos/text2video/$task_id" \
  -H "Authorization: Bearer $API_KEY"

The canonical pattern is GET /kling/v1/videos/{kind}/{task_id}. The site returns a task envelope whose data.status can be SUBMITTED, QUEUED, IN_PROGRESS, SUCCESS, or FAILURE. Only the last two are terminal; after success, read result_url or the result payload. A direct Kling response can instead use lowercase submitted, processing, succeed, and failed. Do not share one parser between the direct and site contracts.

Poll with bounded exponential backoff, jitter, a total deadline, and cancellation. A wrong action kind, a task owned by another user, or a request_id substituted for task_id will make retrieval fail.

Media, safety, billing, and retry

Apply SSRF, redirect, content-type, and byte limits to input URLs, and estimate decoded size before accepting Base64. Face, lip-sync, voice, and virtual try-on actions require stricter consent, impersonation, and moderation controls. Cost can vary by model, mode, duration, resolution, audio, and action; reconcile the billing log instead of estimating by request count.

A creation timeout may already have produced a billed task. Check an application idempotency record for a public task_id before resubmitting. Do not retry validation or moderation failures, back off and reduce concurrency on 429, and retry transient 5xx failures only within a budget. Stream signed output URLs into controlled storage and record hashes, sizes, durations, access, and deletion time.

Expert: multi-capability rollout gates

The site also registers Kling image, audio, avatar, effects, lip-sync, extension, and multi-element actions. Contract-test each action as a tuple of path, request fields, model, billing dimensions, and terminal states. Rollout gates should cover explicit false/zero forwarding, task-ID mapping, query-path affinity, failure settlement/refund, output expiry, channel switching, and degradation. Monitor submit success, completion by kind, P95 latency, failure reasons, duplicate jobs, cost per second, and output-retention failures.