API 参考
Kling Image-to-Video
以异步 Task 提交Image to Video请求。
01
概览
使用支持的模型提交Image 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-o113 个字段
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
first_frame_image_urlstring
必填
Public HTTP(S) JPG, JPEG, or PNG first-frame image URL.
last_frame_image_urlstring
可选
Public HTTP(S) JPG, JPEG, or PNG final-frame image URL; cannot be combined with reference_image_urls or reference_video_url.
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; cannot be combined with last_frame_image_url.
项数范围: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; cannot be combined with last_frame_image_url.
kling-v2.1-master-image-to-video9 个字段
aspect_ratiostring
可选
Output aspect ratio.
callback_urlstring
可选
Webhook URL for async notifications.
cfg_scalenumber
可选
Guidance scale (0-1).
duration_secondsinteger
可选
Duration in seconds.
可选值:5, 10
first_frame_image_urlstring
必填
First frame image URL.
last_frame_image_urlstring
可选
Final frame image URL for supported image-to-video models.
modelstring
必填
Model slug.
negative_promptstring
可选
Negative prompt.
promptstring
必填
Video description.
kling-v2.1-pro9 个字段
aspect_ratiostring
可选
Output aspect ratio.
callback_urlstring
可选
Webhook URL for async notifications.
cfg_scalenumber
可选
Guidance scale (0-1).
duration_secondsinteger
可选
Duration in seconds.
可选值:5, 10
first_frame_image_urlstring
必填
First frame image URL.
last_frame_image_urlstring
可选
Final frame image URL for supported image-to-video models.
modelstring
必填
Model slug.
negative_promptstring
可选
Negative prompt.
promptstring
必填
Video description.
kling-v2.1-standard9 个字段
aspect_ratiostring
可选
Output aspect ratio.
callback_urlstring
可选
Webhook URL for async notifications.
cfg_scalenumber
可选
Guidance scale (0-1).
duration_secondsinteger
可选
Duration in seconds.
可选值:5, 10
first_frame_image_urlstring
必填
First frame image URL.
last_frame_image_urlstring
可选
Final frame image URL for supported image-to-video models.
modelstring
必填
Model slug.
negative_promptstring
可选
Negative prompt.
promptstring
必填
Video description.
kling-v2.5-turbo-image-to-video-pro9 个字段
aspect_ratiostring
可选
Output aspect ratio.
callback_urlstring
可选
Webhook URL for async notifications.
cfg_scalenumber
可选
Guidance scale (0-1).
duration_secondsinteger
可选
Duration in seconds.
可选值:5, 10
first_frame_image_urlstring
必填
First frame image URL.
last_frame_image_urlstring
可选
Final frame image URL for supported image-to-video models.
modelstring
必填
Model slug.
negative_promptstring
可选
Negative prompt.
promptstring
必填
Video description.
kling-v2.69 个字段
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
first_frame_image_urlstring
必填
First frame image URL.
last_frame_image_urlstring
可选
Final frame image URL; requires pro mode and 5 seconds.
modestring
可选
Generation mode.
可选值:std, pro
默认值: std
modelstring
必填
Model slug.
promptstring
必填
Video description.
范围:1 - 2500
kling-v3-omni9 个字段
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
first_frame_image_urlstring
必填
First frame image URL.
last_frame_image_urlstring
可选
Final frame image URL; requires a 5-second duration.
modelstring
必填
Model slug.
output_resolutionstring
可选
Output resolution.
可选值:720p, 1080p, 4k
默认值: 720p
promptstring
必填
Video description.
范围:1 - 2500
kling-v3-turbo-image-to-video6 个字段
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
first_frame_image_urlstring
必填
First frame image URL.
modelstring
必填
Model slug.
output_resolutionstring
可选
Output resolution.
可选值:720p, 1080p
默认值: 720p
promptstring
必填
Video description.
范围:1 - 2500
条件规则
当列出的全部条件同时匹配时，应用这些要求。
-
当
model = kling-o1- 必填
- 不可提供
output_resolution,negative_prompt,cfg_scale
-
当
model = kling-v2.1-master-image-to-video- 必填
- 不可提供
output_resolution,enable_sound,reference_image_urls,reference_video_url,reference_video_type,preserve_reference_video_audio
-
当
model = kling-v2.1-pro- 必填
- 不可提供
output_resolution,enable_sound,reference_image_urls,reference_video_url,reference_video_type,preserve_reference_video_audio
-
当
model = kling-v2.1-standard- 必填
- 不可提供
output_resolution,enable_sound,reference_image_urls,reference_video_url,reference_video_type,preserve_reference_video_audio
-
当
model = kling-v2.5-turbo-image-to-video-pro- 必填
- 不可提供
output_resolution,enable_sound,reference_image_urls,reference_video_url,reference_video_type,preserve_reference_video_audio
-
当
model = kling-v2.6- 必填
- 不可提供
output_resolution,negative_prompt,cfg_scale,reference_image_urls,reference_video_url,reference_video_type,preserve_reference_video_audio
-
当
model = kling-v3-omni- 必填
- 不可提供
negative_prompt,cfg_scale,reference_image_urls,reference_video_url,reference_video_type,preserve_reference_video_audio
-
当
model = kling-v3-turbo-image-to-video- 必填
- 不可提供
enable_sound,aspect_ratio,negative_prompt,cfg_scale,last_frame_image_url,reference_image_urls,reference_video_url,reference_video_type,preserve_reference_video_audio
04
HTTP 202创建已接受
POST /api/v1/kling/image_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/image_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/image_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/image_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/image_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/image_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/image_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-o1, kling-v2.1-master-image-to-video, kling-v2.1-pro, kling-v2.1-standard, kling-v2.5-turbo-image-to-video-pro, kling-v2.6, kling-v3-omni, kling-v3-turbo-image-to-video"
}13
HTTP 402错误
POST /api/v1/kling/image_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/image_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/image_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/image_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/image_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/image_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/image_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.image_to_video.create(
model="kling-o1",
prompt="A gentle camera pan across the scene.",
first_frame_image_url="https://file.runapi.ai/first-frame.png"
)