可灵

调用快手可灵(Kling)视频模型,支持文生视频、图生视频(含尾帧)。可用统一格式提交,也可沿用可灵官方请求体。

项 值
提交 POST /v1/video/generations(或 POST /v1/videos)
查询 GET /v1/video/generations/{task_id}(或 GET /v1/videos/{task_id})
可灵官方格式 POST /kling/v1/videos/text2video、POST /kling/v1/videos/image2video,见 可灵官方格式
鉴权 Authorization: Bearer YOUR_API_KEY
Content-Type application/json

异步流程、轮询与计费见 概述与通用流程。

支持的模型

可用模型以 模型列表 返回为准(或控制台模型价格页)。

文生视频

BASH
curl https://www.nextai-code.com/v1/video/generations \
  -H "Authorization: Bearer $NEXTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL",
    "prompt": "宇航员在月球表面缓缓站起,地球在身后升起",
    "size": "1280x720",
    "duration": 5,
    "mode": "std",
    "metadata": { "negative_prompt": "模糊, 低画质" }
  }'

提交响应:

JSON
{
  "id": "866000000000000000",
  "task_id": "866000000000000000",
  "object": "video",
  "model": "YOUR_MODEL",
  "status": "",
  "progress": 0,
  "created_at": 1734567890
}

任务 ID 按 概述 · 读取任务 ID 的方法读取(先 id 后 task_id)。提交响应里的 status 为空字符串,以查询结果为准。

图生视频

BASH
curl https://www.nextai-code.com/v1/video/generations \
  -H "Authorization: Bearer $NEXTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL",
    "prompt": "人物抬头看向镜头",
    "image": "https://example.com/first-frame.jpg",
    "metadata": { "image_tail": "https://example.com/last-frame.jpg" }
  }'
  • 首帧用 image 传(URL 或 Base64)。可灵只读 image,不读 images,传 images 会按文生视频处理。
  • 尾帧放在 metadata.image_tail,需同时传 image。

查询

BASH
curl https://www.nextai-code.com/v1/video/generations/866000000000000000 \
  -H "Authorization: Bearer $NEXTAI_API_KEY"
  • data.status 为 SUCCESS 时,成片地址在 data.fail_reason(可灵 CDN 直链,直接 GET 下载,不要附带 API Key)。响应结构见 概述 · 查询响应。
  • 用 GET /v1/videos/{task_id} 查询则返回 OpenAI Video 对象,成片地址在 meta_data.url,时长在 seconds。

可灵状态与平台状态对应:

可灵 task_status 平台 status
submitted SUBMITTED
processing IN_PROGRESS
succeed SUCCESS
failed FAILURE

特有参数

统一字段在可灵的含义

参数 说明
model 可灵模型名。不传时使用平台默认的可灵模型,建议显式传入
size 换算为宽高比:1280x720 / 1920x1080 → 16:9;720x1280 / 1080x1920 → 9:16;其它值或不传 → 1:1。需要其它比例请用 metadata.aspect_ratio
duration 时长(秒),默认 5,可选值以可灵文档为准
mode std(默认)或 pro

metadata 字段

metadata 中的同名字段会覆盖上面的值。字段含义以可灵官方文档为准:

字段 类型 说明
image_tail string 尾帧图
negative_prompt string 反向提示词
aspect_ratio string 宽高比,如 16:9,优先于 size
cfg_scale number 提示词相关性,默认 0.5
mode string 同 mode
duration string 时长,必须是字符串,如 "10"
model_name string 覆盖模型名
image string 首帧图
static_mask string 静态笔刷
dynamic_masks array 动态笔刷:[{ "mask": "...", "trajectories": [{ "x": 0, "y": 0 }] }]
camera_control object 运镜:{ "type": "...", "config": { "horizontal", "vertical", "pan", "tilt", "roll", "zoom" } }
callback_url string 可灵回调地址
external_task_id string 自定义任务 ID

上表以外的字段不会生效。字段类型必须与上表一致,否则提交失败(例如 duration 传数字返回 500 build_request_failed)。

可灵官方格式

已按可灵官方请求体接入的,把地址换成平台、路径加 /kling 前缀即可:

BASH
curl https://www.nextai-code.com/kling/v1/videos/image2video \
  -H "Authorization: Bearer $NEXTAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "YOUR_MODEL",
    "prompt": "人物抬头看向镜头",
    "image": "https://example.com/first-frame.jpg",
    "mode": "pro",
    "duration": "5",
    "aspect_ratio": "16:9",
    "negative_prompt": "模糊"
  }'

查询:

BASH
curl https://www.nextai-code.com/kling/v1/videos/image2video/866000000000000000 \
  -H "Authorization: Bearer $NEXTAI_API_KEY"

与可灵官方的差异:

  • 鉴权用平台 API Key,不需要可灵的 AccessKey / SecretKey。
  • 模型名取 model_name,没有则取 model;prompt 必填。
  • 其余字段与类型同上面的 metadata 字段表(如 duration 用字符串)。
  • 请求体有非空 image 时按图生视频处理,否则按文生视频,与调用 text2video 还是 image2video 路径无关。
  • 提交响应是上文的统一提交响应,不是可灵官方的 {code, data: {task_id}};查询响应是 统一格式,不是可灵官方结构。

限制

HTTP code 说明
400 task_failed 可灵拒绝提交,message 为可灵的错误信息
500 build_request_failed metadata 字段类型不对,请求无法构造

其它错误见 概述 · 错误。

相关文档