Integrating Kling Video Generation Through a Gateway: My 2026 Implementation Notes

I’d start a Kling integration with the job lifecycle: submit a request, persist the task ID, query its status, and copy the finished asset into application storage. The generation call is the easy part. Handling an ambiguous submission or a worker restart takes more care.

A unified multi-model API such as CometAPI provides access to supported Kling models using its own account and API key, without a separate direct Kling developer onboarding step for that route. That is useful when a team already manages other models through the same gateway.

Account and region eligibility still apply. Model availability, parameters, pricing, and limits can change, so I’d check the live catalog and text-to-video reference before committing to an implementation.

Establish the endpoint contract first

The video workflow uses Kling-specific routes and request fields. A shared credential does not make it an OpenAI-compatible video API or make different providers accept identical payloads.

I’d keep the product-facing contract small: prompt, workflow, model, options, and job status. A provider adapter can translate those inputs while preserving differences in accepted media, generation behavior, latency, pricing, safety policies, and result metadata.

Choose the workflow from the available input:

Workflow	Creation endpoint	Input requirement
Text to video	POST /kling/v1/videos/text2video	A written scene or motion concept, with no source image to preserve.
Image to video	POST /kling/v1/videos/image2video	A source image that guides motion and visual identity.

The image-to-video endpoint accepts a public image URL or a base64 image string and also returns an asynchronous task. Adding an image field to the text-to-video payload does not select that workflow. Specialized workflows have their own constraints and deserve separate adapters.

For an initial test, I’d use text-to-video, one verified model, a short duration, and a fixed set of representative prompts. That keeps access and orchestration problems distinguishable from output-quality questions.

Before submitting anything:

1. Confirm that the required model is available to your account and region.
2. Check current prices, rate limits, and endpoint parameters.
3. Create a key in the console and store it server-side as COMETAPI_KEY.
4. Decide where to persist application jobs, provider task IDs, and completed videos.

Keep the credential out of browser and mobile client code.

Submit a small job

The documented text-to-video example uses kling-v3. Confirm that ID against the live enum and your account access; a cached example is insufficient evidence of availability.

This request uses Bearer authentication and a JSON body:

curl https://api.cometapi.com/kling/v1/videos/text2video \
  -H "Authorization: Bearer $COMETAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A small ceramic cup on a wooden table, steam rising in soft morning light",
    "model_name": "kling-v3",
    "mode": "std",
    "duration": "5",
    "sound": "off"
  }'

A successful submission includes data.task_id and a task status. Save the task ID immediately and finish the application’s submission request; rendering continues asynchronously.

These are the parameters I’d keep explicit in configuration:

Parameter	Documented values	Decision
model_name	kling-v3 and earlier tracks in the current enum	Verify both the live enum and account access.
duration	5 or 10	Start with 5 seconds.
aspect_ratio	16:9, 9:16, 1:1	Omit only when the documented default suits the product.
mode	std, pro	Validate the pipeline with std; the reference describes pro as higher quality and higher cost.
sound	on, off	Applies only to model tracks supporting generated audio.

Once submission, polling, and retrieval work, I’d compare std and pro using the same prompts. Evaluate output quality alongside generation time and actual cost.

Poll until the task reaches a terminal state

For text-to-video, query GET /kling/v1/videos/text2video/{task_id}. The task reference allows the task object either directly in the response or inside data.

The Python example below handles both shapes, waits through nonterminal states, and checks that a successful task actually contains a video URL:

import os
import time
import requests

API_KEY = os.environ["COMETAPI_KEY"]
BASE_URL = "https://api.cometapi.com/kling/v1/videos/text2video"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

def submit_video(prompt: str) -> str:
    response = requests.post(
        BASE_URL,
        headers=HEADERS,
        json={
            "prompt": prompt,
            "model_name": "kling-v3",
            "mode": "std",
            "duration": "5",
            "sound": "off",
        },
        timeout=30,
    )
    response.raise_for_status()
    payload = response.json()
    return payload["data"]["task_id"]

def wait_for_video(task_id: str, timeout_seconds: int = 600) -> str:
    deadline = time.monotonic() + timeout_seconds
    poll_url = f"{BASE_URL}/{task_id}"

    while time.monotonic() < deadline:
        response = requests.get(poll_url, headers=HEADERS, timeout=30)
        response.raise_for_status()
        payload = response.json()
        task = payload.get("data") or payload
        status = task.get("task_status")

        if status == "succeed":
            videos = task.get("task_result", {}).get("videos", [])
            if not videos or not videos[0].get("url"):
                raise RuntimeError("Task succeeded without a video URL")
            return videos[0]["url"]

        if status == "failed":
            detail = task.get("task_status_msg") or task.get("task_result")
            raise RuntimeError(f"Kling task failed: {detail}")

        time.sleep(10)

    raise TimeoutError(f"Kling task {task_id} exceeded {timeout_seconds}s")

task_id = submit_video(
    "A small ceramic cup on a wooden table, steam rising in soft morning light"
)
video_url = wait_for_video(task_id)
print(video_url)

The exact success status is succeed. Using succeeded would miss the terminal state.

This example uses 30-second HTTP timeouts, a 10-second polling interval, and a default 600-second polling deadline. It raises on HTTP errors; a production worker needs a separate policy for retryable query failures. Individual request timeouts also mean the polling deadline is not a strict wall-clock execution cap.

For sustained workloads, run this lifecycle in a queue or worker. Keep long-running polling outside web request handlers.

Persist enough state to recover

I’d create the application job before calling the creation endpoint. Its record should include the application job ID, workflow, requested model, provider task ID, query URL, current status, submission timestamp, last poll time, and output location.

The dangerous case is a submission whose response never reaches your service. The provider may already have created the task. Repeating the POST can create duplicate work, so submission retries need a different policy from status-query retries.

The endpoint documents external_task_id for application tracking. Verify its current semantics before treating it as a deduplication guarantee.

Here is a compact status-refresh function for an existing job:

const TERMINAL = new Set(["succeed", "failed"]);

function normalizeKlingTask(payload) {
  const task = payload?.data ?? payload;
  if (!task?.task_id || !task?.task_status) {
    throw new Error("Kling response is missing task identity or status");
  }
  return task;
}

async function refreshVideoJob(job, apiKey) {
  const response = await fetch(job.queryUrl, {
    headers: { Authorization: `Bearer ${apiKey}` },
  });

  if (!response.ok) {
    throw new Error(`Task query failed with HTTP ${response.status}`);
  }

  const task = normalizeKlingTask(await response.json());
  const outputUrl = task.task_result?.videos?.[0]?.url ?? null;

  return {
    ...job,
    providerTaskId: task.task_id,
    providerStatus: task.task_status,
    terminal: TERMINAL.has(task.task_status),
    outputUrl,
    failureDetail: task.task_status_msg ?? null,
    checkedAt: new Date().toISOString(),
  };
}

The returned object preserves the raw provider status for debugging. The caller still needs to persist it and enforce an application timeout so stalled jobs cannot stay open indefinitely.

I’d avoid assigning product meanings to every intermediate status until the endpoint contract supports those meanings. Keep nonterminal tasks active and handle succeed and failed explicitly.

Add callbacks with a polling recovery path

Polling is a straightforward starting point because the task ID remains queryable. Where the selected endpoint supports callback_url, callbacks can reduce repeated status requests.

The polling and webhook guide notes that callback payloads can differ by provider. I’d make the receiver authenticate events, store the raw payload, and process updates idempotently by task ID.

Return a successful HTTP response quickly, deduplicate repeated deliveries, and retain polling to reconcile terminal state or recover missed callbacks. That lets callbacks become the primary notification path without making successful delivery the only way a job can finish.

Define completion beyond the provider status

A generated video URL is a delivery location. If the product promises durable access, copy the asset into storage you control and apply the application’s retention and deletion policy there.

I’d also keep output retrieval visible in monitoring. A task can reach succeed while the application still has work to do before the user can reliably access the result.

The operational checks I’d use before expanding traffic are:

• Model selection: validate availability and fail clearly when the requested model cannot be used. Avoid silent substitutions when output behavior matters.
• Polling bounds: use a timeout, a reasonable fixed interval or exponential backoff, and a maximum retry count. Review rate-limit and concurrency guidance before raising parallelism.
• Error classification: invalid parameters and authentication failures need correction. Retryable rate-limit and platform errors need backoff according to the retry guide.
• Credentials and inputs: avoid logging secrets, keep keys server-side, and confirm users have rights to submitted prompts, images, and other assets.
• Job metrics: track submission success, queue time, generation time, terminal failures, timeouts, output retrieval success, and cost by model and mode.
• Recovery: persist provider task identity immediately and keep creation retries separate from query retries.

My rollout would stay narrow until those measurements are useful: one workflow, one verified model, short jobs, and a fixed evaluation set. I’d add image-to-video or another model only after checking its endpoint contract and account eligibility, then compare its actual latency, cost, and output behavior against the product’s requirements.

---

Originally published at cometapi.com