Skip to main content

Blog

Kling 4 API Quickstart: Make and Retrieve Your First Video

Editorial illustration of a blue bottle and camera-path guides for a Kling 4 API tutorial

Quick answer: To make a video with Kling 4.0 on PiAPI, POST a text_to_video task with model: "kling", input.version: "4.0", a prompt, an explicit duration, and config.service_mode: "public". Poll the returned task ID until completion, then read data.output.video. The request and playable result below were run on PiAPI, not assembled from a stock clip.

What this quickstart tests

This article tests one Kling 4.0 standard text-to-video task: 720p, three seconds, 16:9, no image input. The prompt asks for a slow camera orbit around a cobalt-blue bottle. The output kept the bottle recognizable and moved the framing subtly; it is not a test of image-to-video, keyframes, Omni references, or Flash availability. For version differences, read the Kling 4 overview and the current API reference.

1. Keep your API key on the server

Store your PiAPI key in PIAPI_API_KEY in your server environment. Do not embed it in a public webpage or client-side app. The example uses curl and jq.

2. Create the video task

The request below is the one used for the video on this page. mode: "std" selects the 720p tier for Kling 4.0. The three-second duration is explicit because Kling 4 requires it. service_mode: "public" is required for Kling 4 requests.

curl -X POST 'https://api.piapi.ai/api/v1/task' \
  -H "X-API-Key: $PIAPI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "kling",
    "task_type": "text_to_video",
    "input": {
      "version": "4.0",
      "mode": "std",
      "duration": 3,
      "aspect_ratio": "16:9",
      "prompt": "A single cobalt-blue glass bottle stands on a pale stone table in warm morning light. The camera makes a slow, smooth orbit from left to right. Stable bottle shape and label-free surface, soft shadows, no people, no text, no logos."
    },
    "config": { "service_mode": "public" }
  }'

A successful create response contains data.task_id. It means the request was accepted for processing; the video is not ready yet. Save the ID and poll it. Do not re-POST just because processing takes longer than expected: a second POST creates another task.

3. Watch the actual result

Actual PiAPI Kling 4.0 output from the request above · 3 seconds · standard 720p · 16:9. The blue bottle is stable; camera motion is subtle. The separate cover illustration is not this model output.

4. Poll the task and get the video URL

Set TASK_ID to data.task_id from the create response. The loop stops when the task is completed or failed and times out after about five minutes. On success, read data.output.video; on failure, inspect data.error. For a production app, use bounded retries with backoff or webhooks instead of making the browser wait on this shell loop.

TASK_ID='YOUR_TASK_ID' # data.task_id from the POST response
video_url=''
for attempt in {1..30}; do
  response=$(curl -fsS -H "X-API-Key: $PIAPI_API_KEY" \
    "https://api.piapi.ai/api/v1/task/$TASK_ID") || exit 1
  status=$(printf '%s' "$response" | jq -r '.data.status // empty')
  case "$status" in
    completed)
      video_url=$(printf '%s' "$response" | jq -r '.data.output.video // empty')
      test -n "$video_url" || { echo 'Completed without a video URL' >&2; exit 1; }
      printf 'Video: %s\n' "$video_url"
      break ;;
    failed|error)
      printf '%s' "$response" | jq '.data.error'
      exit 1 ;;
    pending|processing)
      if (( attempt < 30 )); then sleep 10; fi ;;
    *) echo "Unexpected task status: $status" >&2; exit 1 ;;
  esac
done
test -n "$video_url" || { echo 'Task did not complete within 5 minutes' >&2; exit 1; }

Duration and cost for this request

PiAPI's current Kling 4.0 standard 720p rate is $0.1667 per output second. A three-second output is about $0.50 (3 × $0.1667 = $0.5001), before any account-specific adjustments. Kling 4.0 supports 3–30 seconds; Kling 4.0 Flash has a separate 720p rate and 3–20-second range. Check the live model page before running a batch.

Common failures to handle

  • Use the task type for the input: text_to_video for a prompt, image_to_video for a start image, and video_generation for first/last frames or keyframes. Kling 4 Omni uses a separate omni_video_generation contract; do not mix its media fields into this request.
  • For Kling 4.0 and 4.0 Flash, include a prompt and integer duration. Do not send fields that their request contract does not accept, such as enable_audio or negative_prompt; the provider may reject them with 10003.
  • An HTTP 200 create response does not guarantee a completed video. Poll data.status; if it becomes failed, log the task ID and safe error details. If a model is temporarily unavailable, report that state instead of silently switching the user's selected model or repeating a billable create call.

Kling 4 API quickstart FAQ

Where is the generated video URL?

After the task reaches completed, read data.output.video from GET /api/v1/task/{task_id}. The POST response gives you a task ID, not the finished video.

Can I use Kling 4.0 Flash with the same request?

For text-to-video, use input.version: "4.0-flash" and mode: "std", with a 3–20-second duration. Flash is 720p only. Confirm current availability and pricing before switching a production job.

How do I start from an image?

Use task_type: "image_to_video" and a directly readable HTTPS input.image_url. Keep version, prompt, duration, and the required public service mode. The result shown here tests text-to-video only.

Build the next request

Compare the input contracts in the Kling Create Task documentation, explore the Kling 4 model page, or read the task polling and webhooks guide before automating a batch.