Kling documents a direct API for video generation. That differs from using a Kling model through a third-party provider, which has its own credentials, endpoints, request format, job handling, and billing. This guide covers Kling’s direct Kling 3.0 text-to-video API. The authentication documentation specifies a Singapore API hostname for servers outside China; it does not detail every account-eligibility condition. (kling.ai)
Choose the API provider before you integrate
For direct access, use Kling’s developer platform and its model-specific API documentation. If you choose an intermediary instead, follow that provider’s instructions: its routes, request format, job lifecycle, and charges are not automatically interchangeable with Kling’s direct API.
This guide uses Kling’s documented Kling 3.0 text-to-video endpoint. Confirm that this model and endpoint meet your needs before integrating; other Kling models may have different routes and supported settings. (kling.ai)
Set up access and authentication
Create an API key in the Kling developer console and store it securely. Kling’s authentication guide says to send the key in the Authorization header as a Bearer token and recommends storing it in an environment variable. It identifies https://api-singapore.klingai.com for servers outside China. (kling.ai)
For a U.S.-hosted service, that documented outside-China hostname provides a route to use. The documentation reviewed here does not detail every account-eligibility requirement, so confirm that your account has API access before building a production integration around it.
Submit a Kling 3.0 text-to-video request
The documented route is POST /text-to-video/kling-3.0. The request requires a prompt; output options go inside the optional settings object. Kling documents the callback URL inside options.callback_url. The example requests a five-second, silent, 720p, 16:9 video and sends completion notifications to your HTTPS callback endpoint. (kling.ai)
export KLING_API_KEY="your_api_key"
curl --location 'https://api-singapore.klingai.com/text-to-video/kling-3.0' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer ${KLING_API_KEY}" \
--data '{
"prompt": "A red kite gliding over a quiet coastal path at sunrise, smooth tracking shot.",
"settings": {
"duration": 5,
"resolution": "720p",
"aspect_ratio": "16:9",
"audio": "off"
},
"options": {
"callback_url": "https://your-domain.example/kling-callback"
}
}'
Replace the sample callback URL with an HTTPS endpoint in your service that can receive Kling’s notifications. Keep the API key server-side; do not expose it in browser code or a public mobile app.
Kling documents prompt lengths up to 3,072 characters and recommends 2,500 or fewer. For this endpoint, the documented settings include durations of 3–15 seconds, resolutions 720p, 1080p, or 4k, aspect ratios 16:9, 9:16, or 1:1, and audio set to native or off. These limits are specific to this model and endpoint. (kling.ai)
Recognize an accepted task and receive the finished video
Submitting a generation is not the same as receiving a finished video. Kling’s callback protocol says to set callback_url when creating the task; the server then sends notifications when the task status changes. The callback’s id is the task ID, so save the task ID returned at creation and match it against the callback’s id. The documented callback statuses are submitted, processing, succeeded, and failed. (kling.ai)
Kling’s documented create-task response example for a Kling 3.0 video endpoint shows a successful response with code: 0 and a data object containing the generated task id and its status. Use the task ID to associate later notifications with the accepted job; submitted or processing means the task is not finished. The text-to-video page identifies the create route and callback configuration, but the response example retrieved here is from a related Kling 3.0 video endpoint, so confirm the exact response for your route in its current reference. (kling.ai)
If the create request returns an HTTP or API error instead of a successful task response, handle the returned error rather than waiting for a completion callback. The callback documentation says message carries task status information and can include the failure reason. A simplified example of the documented callback fields is:
{
"id": "task-id",
"status": "succeeded",
"message": "",
"outputs": [
{
"type": "video",
"id": "video-id",
"url": "result-url",
"duration": "5"
}
]
}
When status is succeeded, find the video entry in outputs and use its url to retrieve the result. If status is failed, inspect message rather than treating the task as successful. Kling’s callback documentation says generated results are cleared after 30 days, so save or download the output promptly. Follow Kling’s separate webhook-signature instructions to validate callback requests before relying on callbacks in production. (kling.ai)
This guide describes the documented callback route rather than a polling fallback. If you need polling, consult the current task-query documentation for the endpoint you use; do not assume a task-query route or response format from another provider or model.
Production checklist
- Confirm the provider and region: Kling documents the Singapore hostname for servers outside China. Verify API access for your account before launch. (
kling.ai) - Keep credentials private: store the API key server-side. Kling says a newly created key is displayed only once. (
kling.ai) - Handle callbacks as asynchronous events: distinguish
succeededfromfailed, inspect failure messages, and make your handler safe to receive repeated notifications. Follow Kling’s callback-signature instructions to validate requests. (kling.ai) - Save completed media promptly: the callback documentation says generated results are cleared after 30 days. (
kling.ai) - Check model-specific settings: do not reuse Kling 3.0 fields or limits for another model without checking that model’s endpoint reference. (
kling.ai)
Bottom line: Kling documents a direct Kling 3.0 text-to-video API, including a request schema and a callback-based way to receive results. For a U.S.-hosted service, its authentication guide names the Singapore hostname for servers outside China. Confirm account access and the exact create-response schema for your route, and configure callback validation before production use. (kling.ai)