Kling Text-to-Video
以异步 Task 提交Text to Video请求。
01
概览
使用支持的模型提交Text to Video请求。使用返回的 Task ID 查询状态，或提供 callback_url 接收下方列出的投递。
快速开始
- 创建 API Key，并将其设置为 RUNAPI_API_KEY。
- 选择一个支持的模型，并发送与该模型 Schema 匹配的 POST 请求。
- 保存返回的任务 ID，随后轮询到终态，或处理下方列出的回调。
端点
- 基础 URL
https://runapi.ai- API 版本
v1- 身份验证
Authorization: Bearer YOUR_API_TOKEN
02
支持的模型
打开模型页可查看当前价格、限流和商业使用详情。
03
JSON 请求体请求 Schema
字段和允许的取值取决于所选模型。提供 callback_url 后，它会收到下方列出的 Task 投递。
kling-3.014 个字段
aspect_ratiostring
可选
Output aspect ratio.
可选值:16:9, 9:16, 1:1
callback_urlstring
可选
Webhook URL for async notifications.
cfg_scalenumber
可选
Guidance scale (0-1).
duration_secondsinteger
可选
Duration in seconds.
可选值:3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15
enable_soundboolean
可选
Enable sound generation.
first_frame_image_urlstring
可选
First frame image URL.
kling_elementsarray
可选
Element references with image, video, or audio materials.
last_frame_image_urlstring
可选
Last frame image URL for single-shot mode.
modelstring
必填
Model slug.
multi_promptarray
可选
Prompt segments for multi-shot mode.
multi_shotsboolean
可选
Enable multi-shot generation.
negative_promptstring
可选
Negative prompt.
output_resolutionstring
可选
Output resolution.
可选值:720p, 1080p, 4k
promptstring
可选
Video description. Required unless multi_shots is enabled.
kling-o111 个字段
aspect_ratiostring
可选
Output aspect ratio.
可选值:16:9, 9:16, 1:1
默认值: 16:9
callback_urlstring
可选
Webhook URL for async notifications.
duration_secondsinteger
可选
Duration in seconds.
可选值:5
默认值: 5
enable_soundboolean
可选
Sound generation must remain disabled.
默认值:false
modestring
可选
Generation mode.
可选值:std, pro
默认值: std
modelstring
必填
Model slug.
preserve_reference_video_audioboolean
可选
Preserve the reference video's original audio.
默认值:false
promptstring
必填
Video description; reference media with matching numbered markers.
范围:1 - 2500
reference_image_urlsarray
可选
Ordered public HTTP(S) JPG, JPEG, or PNG reference image URLs.
项数范围:1 - 7
reference_video_typestring
可选
Use the video as a base edit or feature reference.
可选值:base, feature
默认值: base
reference_video_urlstring
可选
Public HTTP(S) MP4 or MOV reference video URL.
kling-v2.1-master-text-to-video8 个字段
aspect_ratiostring
可选
Output aspect ratio.
可选值:16:9, 9:16, 1:1
callback_urlstring
可选
Webhook URL for async notifications.
cfg_scalenumber
可选
Guidance scale (0-1).
duration_secondsinteger
可选
Duration in seconds.
可选值:5, 10
enable_soundboolean
可选
Enable sound generation.
modelstring
必填
Model slug.
negative_promptstring
可选
Negative prompt.
promptstring
可选
Video description.
kling-v2.5-turbo-text-to-video-pro8 个字段
aspect_ratiostring
可选
Output aspect ratio.
可选值:16:9, 9:16, 1:1
callback_urlstring
可选
Webhook URL for async notifications.
cfg_scalenumber
可选
Guidance scale (0-1).
duration_secondsinteger
可选
Duration in seconds.
可选值:5, 10
enable_soundboolean
可选
Enable sound generation.
modelstring
必填
Model slug.
negative_promptstring
可选
Negative prompt.
promptstring
可选
Video description.
kling-v2.67 个字段
aspect_ratiostring
可选
Output aspect ratio.
可选值:16:9, 9:16, 1:1
默认值: 16:9
callback_urlstring
可选
Webhook URL for async notifications.
duration_secondsinteger
可选
Duration in seconds.
可选值:5, 10
默认值: 5
enable_soundboolean
可选
Enable sound generation; requires pro mode.
默认值:false
modestring
可选
Generation mode.
可选值:std, pro
默认值: std
modelstring
必填
Model slug.
promptstring
必填
Video description.
范围:1 - 2500
kling-v3-omni7 个字段
aspect_ratiostring
可选
Output aspect ratio.
可选值:16:9, 9:16, 1:1
默认值: 16:9
callback_urlstring
可选
Webhook URL for async notifications.
duration_secondsinteger
可选
Duration in seconds.
可选值:3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15
默认值: 5
enable_soundboolean
可选
Enable synchronized sound generation.
默认值:false
modelstring
必填
Model slug.
output_resolutionstring
可选
Output resolution.
可选值:720p, 1080p, 4k
默认值: 720p
promptstring
必填
Video description.
范围:1 - 2500
kling-v3-omni-reference8 个字段
aspect_ratiostring
必填
Output aspect ratio.
可选值:16:9, 9:16, 1:1
callback_urlstring
可选
Webhook URL for async notifications.
duration_secondsinteger
可选
Output duration in seconds.
可选值:3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15
默认值: 5
enable_soundboolean
可选
Enable synchronized sound generation.
默认值:false
modelstring
必填
Model slug.
output_resolutionstring
可选
Output resolution.
可选值:720p, 1080p, 4k
默认值: 720p
promptstring
必填
Video description.
范围:1 - 2500
reference_image_urlsarray
必填
Ordered reference image URLs.
项数范围:1 - 7
kling-v3-turbo-text-to-video6 个字段
aspect_ratiostring
可选
Output aspect ratio.
可选值:16:9, 9:16, 1:1
默认值: 16:9
callback_urlstring
可选
Webhook URL for async notifications.
duration_secondsinteger
可选
Duration in seconds.
可选值:3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15
默认值: 5
modelstring
必填
Model slug.
output_resolutionstring
可选
Output resolution.
可选值:720p, 1080p
默认值: 720p
promptstring
必填
Video description.
范围:1 - 2500
条件规则
当列出的全部条件同时匹配时，应用这些要求。
-
当
model = kling-3.0- 必填
- 不可提供
reference_image_urls,reference_video_url,reference_video_type,preserve_reference_video_audio
-
当
model = kling-o1- 必填
- 不可提供
output_resolution,negative_prompt,cfg_scale,multi_shots,multi_prompt,first_frame_image_url,last_frame_image_url,kling_elements
-
当
model = kling-v2.1-master-text-to-video- 必填
- 不可提供
mode,reference_image_urls,reference_video_url,reference_video_type,preserve_reference_video_audio
-
当
model = kling-v2.5-turbo-text-to-video-pro- 必填
- 不可提供
mode,reference_image_urls,reference_video_url,reference_video_type,preserve_reference_video_audio
-
当
model = kling-v2.6- 必填
- 不可提供
output_resolution,negative_prompt,cfg_scale,multi_shots,multi_prompt,first_frame_image_url,last_frame_image_url,kling_elements,reference_image_urls,reference_video_url,reference_video_type,preserve_reference_video_audio
-
当
model = kling-v3-omni- 必填
- 不可提供
negative_prompt,cfg_scale,multi_shots,multi_prompt,first_frame_image_url,last_frame_image_url,kling_elements,reference_image_urls,reference_video_url,reference_video_type,preserve_reference_video_audio
-
当
model = kling-v3-turbo-text-to-video- 必填
- 不可提供
enable_sound,negative_prompt,cfg_scale,multi_shots,multi_prompt,first_frame_image_url,last_frame_image_url,kling_elements,reference_image_urls,reference_video_url,reference_video_type,preserve_reference_video_audio
04
HTTP 202创建已接受
POST /api/v1/kling/text_to_video
响应 Schema
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"status": {
"enum": [
"processing"
],
"type": "string"
},
"task_replayed": {
"type": "boolean"
}
},
"required": [
"id",
"status",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}响应示例
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "processing"
}05
HTTP 200轮询处理中
GET /api/v1/kling/text_to_video/:id
响应 Schema
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"status": {
"enum": [
"processing"
],
"type": "string"
}
},
"required": [
"id",
"status",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}响应示例
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "processing"
}06
HTTP 200轮询已完成
GET /api/v1/kling/text_to_video/:id
响应 Schema
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"id": {
"type": "string"
},
"status": {
"enum": [
"completed"
],
"type": "string"
},
"videos": {
"items": {
"properties": {
"url": {
"type": "string",
"x-runapi-generated-media": true
}
},
"required": [
"url"
],
"type": "object",
"unevaluatedProperties": false
},
"type": "array"
}
},
"required": [
"id",
"status",
"videos",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}响应示例
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"id": "tsk_reference_demo",
"status": "completed",
"videos": [
{
"url": "https://file.runapi.ai/reference-video.mp4"
}
]
}07
HTTP 200轮询失败
GET /api/v1/kling/text_to_video/:id
响应 Schema
JSON
{
"properties": {
"billing": {
"properties": {
"refund": {
"oneOf": [
{
"properties": {
"refunded_at": {
"type": "string"
}
},
"required": [
"refunded_at"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"reservation": {
"oneOf": [
{
"properties": {
"amount_cents": {
"type": "integer"
}
},
"required": [
"amount_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
},
"settlement": {
"oneOf": [
{
"properties": {
"amount_micro_cents": {
"type": "integer"
},
"charged_amount_cents": {
"type": "integer"
}
},
"required": [
"charged_amount_cents",
"amount_micro_cents"
],
"type": "object",
"unevaluatedProperties": false
},
{
"enum": [
null
]
}
]
}
},
"required": [
"reservation",
"settlement",
"refund"
],
"type": "object",
"unevaluatedProperties": false
},
"error": {
"type": "string"
},
"id": {
"type": "string"
},
"status": {
"enum": [
"failed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"error",
"billing"
],
"type": "object",
"unevaluatedProperties": false
}响应示例
JSON
{
"billing": {
"refund": null,
"reservation": null,
"settlement": null
},
"error": "Task processing failed.",
"id": "tsk_reference_demo",
"status": "failed"
}08
HTTP 200客户回调：已完成
POST callback_url
响应 Schema
JSON
{
"properties": {
"id": {
"type": "string"
},
"status": {
"enum": [
"completed"
],
"type": "string"
},
"videos": {
"items": {
"properties": {
"url": {
"type": "string",
"x-runapi-generated-media": true
}
},
"required": [
"url"
],
"type": "object",
"unevaluatedProperties": false
},
"type": "array"
}
},
"required": [
"id",
"status",
"videos"
],
"type": "object",
"unevaluatedProperties": false
}响应示例
JSON
{
"id": "tsk_reference_demo",
"status": "completed",
"videos": [
{
"url": "https://file.runapi.ai/reference-video.mp4"
}
]
}09
HTTP 200客户回调：失败
POST callback_url
响应 Schema
JSON
{
"properties": {
"error": {
"oneOf": [
{
"type": "string"
},
{
"properties": {
"code": {
"type": "string"
},
"limit_cents": {
"type": "integer"
},
"message": {
"type": "string"
},
"reset_at": {
"format": "date-time",
"type": [
"string",
"null"
]
},
"used_cents": {
"type": "integer"
},
"window": {
"enum": [
"1h",
"1d",
"7d",
"daily",
"weekly",
"monthly",
"lifetime"
],
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object",
"unevaluatedProperties": false
}
]
},
"id": {
"type": "string"
},
"status": {
"enum": [
"failed"
],
"type": "string"
}
},
"required": [
"id",
"status",
"error"
],
"type": "object",
"unevaluatedProperties": false
}响应示例
JSON
{
"error": {
"code": "generation_failed",
"message": "Task processing failed."
},
"id": "tsk_reference_demo",
"status": "failed"
}10
HTTP 401错误
POST /api/v1/kling/text_to_video
响应 Schema
JSON
{
"properties": {
"error": {
"description": "Human-readable error message.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}响应示例
JSON
{
"error": "Authentication required"
}11
HTTP 401错误
GET /api/v1/kling/text_to_video/:id
响应 Schema
JSON
{
"properties": {
"error": {
"description": "Human-readable error message.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}响应示例
JSON
{
"error": "Authentication required"
}12
HTTP 400错误
POST /api/v1/kling/text_to_video
响应 Schema
JSON
{
"oneOf": [
{
"properties": {
"error": {
"description": "Human-readable error message.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
},
{
"properties": {
"error": {
"description": "Human-readable validation summary.",
"type": "string"
},
"errors": {
"additionalProperties": {
"items": {
"type": "string"
},
"type": "array"
},
"description": "Validation messages keyed by public request field, with an array of human-readable strings for each field.",
"type": "object"
}
},
"required": [
"error",
"errors"
],
"type": "object",
"unevaluatedProperties": false
}
]
}响应示例
JSON
{
"error": "model must be one of: kling-3.0, kling-o1, kling-v2.1-master-text-to-video, kling-v2.5-turbo-text-to-video-pro, kling-v2.6, kling-v3-omni, kling-v3-omni-reference, kling-v3-turbo-text-to-video"
}13
HTTP 402错误
POST /api/v1/kling/text_to_video
响应 Schema
JSON
{
"properties": {
"error": {
"description": "Human-readable error message.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}响应示例
JSON
{
"error": "Insufficient balance"
}14
HTTP 429错误
POST /api/v1/kling/text_to_video
响应 Schema
JSON
{
"properties": {
"error": {
"description": "Human-readable error message.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}响应示例
JSON
{
"error": "API key credit limit exceeded"
}15
HTTP 409错误
POST /api/v1/kling/text_to_video
响应 Schema
JSON
{
"properties": {
"error": {
"description": "Human-readable error message.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}响应示例
JSON
{
"error": "The request uses features that are not supported for the selected model"
}16
HTTP 429错误
POST /api/v1/kling/text_to_video
响应 Schema
JSON
{
"properties": {
"error": {
"description": "Human-readable error message.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}响应示例
JSON
{
"error": "Rate limit reached. Please retry later."
}17
HTTP 503错误
POST /api/v1/kling/text_to_video
响应 Schema
JSON
{
"properties": {
"error": {
"description": "Human-readable error message.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}响应示例
JSON
{
"error": "Service under maintenance, please try again later"
}18
HTTP 504错误
POST /api/v1/kling/text_to_video
响应 Schema
JSON
{
"properties": {
"error": {
"description": "Human-readable error message.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}响应示例
JSON
{
"error": "The request timed out"
}19
HTTP 404错误
GET /api/v1/kling/text_to_video/:id
响应 Schema
JSON
{
"properties": {
"error": {
"description": "Human-readable error message.",
"type": "string"
}
},
"required": [
"error"
],
"type": "object",
"unevaluatedProperties": false
}响应示例
JSON
{
"error": "Task with id 'tsk_reference_demo' not found"
}20
生成的代码示例
直接使用 cURL，或安装所用语言的 SDK。每个示例都会提交本参考中经过验证的请求。
安装
Shell
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"
)