Skip to main content
通过 即刻API 统一网关调用可灵 v3 视频生成接口，支持文本生成视频、图生视频、显式首尾帧控制及有声视频生成，所有任务均为异步处理。
请传入公网可访问的图片 URL。不要直接传 base64 图片数据；本地图片请先使用上传图片接口获取 URL。

​
请求参数

​
model
string
required
视频生成模型名称，固定为 kling-v3。
​
prompt
string
required
视频提示词。建议描述主体、动作、场景、镜头语言和风格。
​
mode
string
default:"std"
生成模式。
  • std — 标准模式，720P
  • pro — 专业模式，1080P
​
duration
integer
default:"5"
视频时长，单位秒。可选值：3、4、5、6、7、8、9、10、11、12、13、14、15。
​
aspect_ratio
string
default:"16:9"
视频宽高比。常用值：16:9、9:16、1:1。
​
reference_images
string[]
普通参考图 URL 数组。
  • 此字段仅表示参考图语义
  • 不会将第二张参考图自动推断为尾帧
  • 首尾帧控制请使用 image_with_roles
​
image_with_roles
object[]
显式图片角色数组，用于首尾帧控制或混合输入。每个对象包含：
​
audio
boolean
default:"false"
是否生成有声视频。true 会生成有声视频，并按 Sound 价格计费。
​
metadata.negative_prompt
string
负面提示词，描述不希望出现的内容。
​
metadata.watermark
boolean
是否添加水印。

​
输入规则

输入形态行为
只有 reference_images普通参考图
只有 image_with_roles 且角色仅有 first_frame / last_frame首尾帧控制
两者混用，或 roles 中同时含 frame/reference 语义混合模式

​
请求示例

curl --request POST \
  --url https://geekapis.com/v1/videos/generations \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "kling-v3",
    "prompt": "一只金色的猫咪在阳光下的草地上奔跑，慢动作，电影质感",
    "mode": "std",
    "duration": 5,
    "aspect_ratio": "16:9"
  }'

​
返回示例

200
{
  "id": "video_01K8SGYNNNVBQTXNR4MM964S7K",
  "object": "generation.task",
  "model": "kling-v3",
  "status": "queued",
  "progress": 0,
  "created_at": 1768380224,
  "metadata": {}
}

​
响应字段

字段类型说明
idstring任务唯一标识符，用于查询任务状态
objectstring对象类型，固定为 generation.task
modelstring使用的模型名称
statusstring任务状态：queued / in_progress / completed / failed
progressinteger任务进度百分比（0–100）
created_atinteger任务创建时间戳（Unix 时间戳）

​
查询任务状态

提交后，使用以下接口轮询任务进度： 
GET https://geekapis.com/v1/videos/generations/{task_id}