--- title: Kling Text-to-Video url: https://runapi.ai/zh-CN/docs/api/kling/text-to-video.md canonical: https://runapi.ai/zh-CN/docs/api/kling/text-to-video locale: zh-CN --- # Kling Text-to-Video ## 概览 使用支持的模型创建异步文生视频任务。使用返回的任务 ID 查询状态，或提供 callback_url 接收终态投递。 ### 快速开始 1. 创建 API Key，并将其设置为 RUNAPI_API_KEY。 2. 选择一个支持的模型，并发送与该模型 Schema 匹配的 POST 请求。 3. 保存返回的任务 ID，随后轮询到终态，或处理终态回调。 ## 端点 POST /api/v1/kling/text_to_video 基础 URL: https://runapi.ai API 版本: v1 身份验证: Authorization: Bearer YOUR_API_TOKEN ## 支持的模型 打开模型页可查看当前价格、限流和商业使用详情。 - [kling-3.0](/models/kling/3.0) - [kling-o1](/models/kling/o1) - [kling-v2.1-master-text-to-video](/models/kling/v2.1-master-text-to-video) - [kling-v2.5-turbo-text-to-video-pro](/models/kling/v2.5-turbo-text-to-video-pro) - [kling-v2.6](/models/kling/v2.6) - [kling-v3-omni](/models/kling/v3-omni) - [kling-v3-turbo-text-to-video](/models/kling/v3-turbo-text-to-video) ## 请求 Schema 字段和允许的取值取决于所选模型。提供 callback_url 后，它会收到任务终态投递。 ### kling-3.0 ```json { "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "16:9", "9:16", "1:1" ], "type": "string" }, "callback_url": { "description": "Webhook URL for async notifications.", "type": "string" }, "cfg_scale": { "description": "Guidance scale (0-1).", "type": "number" }, "duration_seconds": { "description": "Duration in seconds.", "enum": [ 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 ], "type": "integer" }, "enable_sound": { "description": "Enable sound generation.", "type": "boolean" }, "first_frame_image_url": { "description": "First frame image URL.", "type": "string" }, "kling_elements": { "description": "Element references with image, video, or audio materials.", "type": "array" }, "last_frame_image_url": { "description": "Last frame image URL for single-shot mode.", "type": "string" }, "model": { "description": "Model slug.", "required": true, "type": "string" }, "multi_prompt": { "description": "Prompt segments for multi-shot mode.", "type": "array" }, "multi_shots": { "description": "Enable multi-shot generation.", "type": "boolean" }, "negative_prompt": { "description": "Negative prompt.", "type": "string" }, "output_resolution": { "description": "Output resolution.", "enum": [ "720p", "1080p", "4k" ], "type": "string" }, "prompt": { "description": "Video description. Required unless multi_shots is enabled.", "type": "string" } } ``` ### kling-o1 ```json { "aspect_ratio": { "default": "16:9", "description": "Output aspect ratio.", "enum": [ "16:9", "9:16", "1:1" ], "type": "string" }, "callback_url": { "description": "Webhook URL for async notifications.", "type": "string" }, "duration_seconds": { "default": 5, "description": "Duration in seconds.", "enum": [ 5 ], "type": "integer" }, "enable_sound": { "default": false, "description": "Sound generation must remain disabled.", "type": "boolean" }, "mode": { "default": "std", "description": "Generation mode.", "enum": [ "std", "pro" ], "type": "string" }, "model": { "description": "Model slug.", "required": true, "type": "string" }, "preserve_reference_video_audio": { "default": false, "description": "Preserve the reference video's original audio.", "type": "boolean" }, "prompt": { "description": "Video description; reference media with matching numbered markers.", "length": true, "max": 2500, "min": 1, "required": true, "type": "string" }, "reference_image_urls": { "description": "Ordered public HTTP(S) JPG, JPEG, or PNG reference image URLs.", "items": { "type": "string" }, "max_items": 7, "min_items": 1, "type": "array" }, "reference_video_type": { "default": "base", "description": "Use the video as a base edit or feature reference.", "enum": [ "base", "feature" ], "type": "string" }, "reference_video_url": { "description": "Public HTTP(S) MP4 or MOV reference video URL.", "type": "string" } } ``` ### kling-v2.1-master-text-to-video ```json { "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "16:9", "9:16", "1:1" ], "type": "string" }, "callback_url": { "description": "Webhook URL for async notifications.", "type": "string" }, "cfg_scale": { "description": "Guidance scale (0-1).", "type": "number" }, "duration_seconds": { "description": "Duration in seconds.", "enum": [ 5, 10 ], "type": "integer" }, "enable_sound": { "description": "Enable sound generation.", "type": "boolean" }, "model": { "description": "Model slug.", "required": true, "type": "string" }, "negative_prompt": { "description": "Negative prompt.", "type": "string" }, "prompt": { "description": "Video description.", "type": "string" } } ``` ### kling-v2.5-turbo-text-to-video-pro ```json { "aspect_ratio": { "description": "Output aspect ratio.", "enum": [ "16:9", "9:16", "1:1" ], "type": "string" }, "callback_url": { "description": "Webhook URL for async notifications.", "type": "string" }, "cfg_scale": { "description": "Guidance scale (0-1).", "type": "number" }, "duration_seconds": { "description": "Duration in seconds.", "enum": [ 5, 10 ], "type": "integer" }, "enable_sound": { "description": "Enable sound generation.", "type": "boolean" }, "model": { "description": "Model slug.", "required": true, "type": "string" }, "negative_prompt": { "description": "Negative prompt.", "type": "string" }, "prompt": { "description": "Video description.", "type": "string" } } ``` ### kling-v2.6 ```json { "aspect_ratio": { "default": "16:9", "description": "Output aspect ratio.", "enum": [ "16:9", "9:16", "1:1" ], "type": "string" }, "callback_url": { "description": "Webhook URL for async notifications.", "type": "string" }, "duration_seconds": { "default": 5, "description": "Duration in seconds.", "enum": [ 5, 10 ], "type": "integer" }, "enable_sound": { "default": false, "description": "Enable sound generation; requires pro mode.", "type": "boolean" }, "mode": { "default": "std", "description": "Generation mode.", "enum": [ "std", "pro" ], "type": "string" }, "model": { "description": "Model slug.", "required": true, "type": "string" }, "prompt": { "description": "Video description.", "length": true, "max": 2500, "min": 1, "required": true, "type": "string" } } ``` ### kling-v3-omni ```json { "aspect_ratio": { "default": "16:9", "description": "Output aspect ratio.", "enum": [ "16:9", "9:16", "1:1" ], "type": "string" }, "callback_url": { "description": "Webhook URL for async notifications.", "type": "string" }, "duration_seconds": { "default": 5, "description": "Duration in seconds.", "enum": [ 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 ], "type": "integer" }, "enable_sound": { "default": false, "description": "Enable synchronized sound generation.", "type": "boolean" }, "model": { "description": "Model slug.", "required": true, "type": "string" }, "output_resolution": { "default": "720p", "description": "Output resolution.", "enum": [ "720p", "1080p", "4k" ], "type": "string" }, "prompt": { "description": "Video description.", "length": true, "max": 2500, "min": 1, "required": true, "type": "string" } } ``` ### kling-v3-turbo-text-to-video ```json { "aspect_ratio": { "default": "16:9", "description": "Output aspect ratio.", "enum": [ "16:9", "9:16", "1:1" ], "type": "string" }, "callback_url": { "description": "Webhook URL for async notifications.", "type": "string" }, "duration_seconds": { "default": 5, "description": "Duration in seconds.", "enum": [ 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15 ], "type": "integer" }, "model": { "description": "Model slug.", "required": true, "type": "string" }, "output_resolution": { "default": "720p", "description": "Output resolution.", "enum": [ "720p", "1080p" ], "type": "string" }, "prompt": { "description": "Video description.", "length": true, "max": 2500, "min": 1, "required": true, "type": "string" } } ``` ## 创建已接受 HTTP 202 - POST /api/v1/kling/text_to_video ```json { "billing": { "refund": null, "reservation": null, "settlement": null }, "id": "tsk_reference_demo", "status": "processing" } ``` ## 轮询处理中 HTTP 200 - GET /api/v1/kling/text_to_video/:id ```json { "billing": { "refund": null, "reservation": null, "settlement": null }, "id": "tsk_reference_demo", "status": "processing" } ``` ## 轮询已完成 HTTP 200 - GET /api/v1/kling/text_to_video/:id ```json { "billing": { "refund": null, "reservation": null, "settlement": null }, "id": "tsk_reference_demo", "status": "completed", "videos": [ { "url": "https://file.runapi.ai/reference-video.mp4" } ] } ``` ## 轮询失败 HTTP 200 - GET /api/v1/kling/text_to_video/:id ```json { "billing": { "refund": null, "reservation": null, "settlement": null }, "error": "Task processing failed.", "id": "tsk_reference_demo", "status": "failed" } ``` ## 客户回调：已完成 HTTP 200 - POST callback_url ```json { "billing": { "refund": null, "reservation": null, "settlement": null }, "id": "tsk_reference_demo", "status": "completed", "videos": [ { "url": "https://file.runapi.ai/reference-video.mp4" } ] } ``` ## 客户回调：失败 HTTP 200 - POST callback_url ```json { "billing": { "refund": null, "reservation": null, "settlement": null }, "error": { "code": "generation_failed", "message": "Task processing failed." }, "id": "tsk_reference_demo", "status": "failed" } ``` ## 错误 HTTP 400 ```json { "error": { "code": "invalid_request", "message": "A required request field is missing." } } ``` ## 生成的代码示例 直接使用 cURL，或安装所用语言的 SDK。每个示例都会提交本参考中经过验证的请求。 ### curl ```curl curl -X POST https://runapi.ai/api/v1/kling/text_to_video \ -H 'Authorization: Bearer YOUR_API_TOKEN' \ -H 'Content-Type: application/json' \ -d '{"model":"kling-v3-turbo-text-to-video","prompt":"A paper kite flying above a quiet coastal town at sunrise","duration_seconds":5,"aspect_ratio":"16:9","output_resolution":"720p"}' ``` ### javascript #### 安装 ```bash npm install @runapi.ai/kling ``` ```javascript import { KlingClient } from "@runapi.ai/kling"; const client = new KlingClient({ apiKey: process.env.RUNAPI_API_KEY }); const task = await client.textToVideo.create({ "model": "kling-v3-turbo-text-to-video", "prompt": "A paper kite flying above a quiet coastal town at sunrise", "duration_seconds": 5, "aspect_ratio": "16:9", "output_resolution": "720p" }); ``` ### python #### 安装 ```bash pip install runapi-kling ``` ```python import os from runapi.kling import KlingClient client = KlingClient(api_key=os.environ["RUNAPI_API_KEY"]) task = client.text_to_video.create( model="kling-v3-turbo-text-to-video", prompt="A paper kite flying above a quiet coastal town at sunrise", duration_seconds=5, aspect_ratio="16:9", output_resolution="720p" ) ``` ### go #### 安装 ```bash go get github.com/runapi-ai/kling-sdk/go@latest ``` ```go package main import ( "context" "log" "os" "github.com/runapi-ai/core-sdk/go/option" kling "github.com/runapi-ai/kling-sdk/go/kling" ) func main() { client, err := kling.NewClient(option.WithAPIKey(os.Getenv("RUNAPI_API_KEY"))) if err != nil { log.Fatal(err) } _, err = client.TextToVideo.Create(context.Background(), kling.TextToVideoParams{ Model: "kling-v3-turbo-text-to-video", Prompt: "A paper kite flying above a quiet coastal town at sunrise", DurationSeconds: 5, AspectRatio: "16:9", OutputResolution: "720p", }) if err != nil { log.Fatal(err) } } ``` ### ruby #### 安装 ```bash gem install runapi-kling ``` ```ruby client = RunApi::Kling::Client.new(api_key: ENV.fetch("RUNAPI_API_KEY")) task = client.text_to_video.create( model: "kling-v3-turbo-text-to-video", prompt: "A paper kite flying above a quiet coastal town at sunrise", duration_seconds: 5, aspect_ratio: "16:9", output_resolution: "720p" ) ``` ### java #### 安装 ```kotlin implementation("ai.runapi:runapi-kling") ``` ```java import ai.runapi.core.polling.TaskCreateResponse; import ai.runapi.kling.KlingClient; import ai.runapi.kling.types.TextToVideoParams; KlingClient client = KlingClient.builder() .apiKey(System.getenv("RUNAPI_API_KEY")) .build(); TaskCreateResponse task = client.textToVideo().create( TextToVideoParams.builder() .model("kling-v3-turbo-text-to-video") .prompt("A paper kite flying above a quiet coastal town at sunrise") .durationSeconds(5) .aspectRatio("16:9") .outputResolution("720p") .build() ); ``` ### php #### 安装 ```bash composer require runapi-ai/kling ``` ```php textToVideo->create([ "model" => "kling-v3-turbo-text-to-video", "prompt" => "A paper kite flying above a quiet coastal town at sunrise", "duration_seconds" => 5, "aspect_ratio" => "16:9", "output_resolution" => "720p" ]); ``` ## 相关指南 - [API 身份验证](/docs/guides/authentication) - [Task API 快速开始](/docs/guides/task-api/quickstart)