可灵视频与生图 API

Essevin 通过腾讯云点播（VOD）AIGC 网关接入可灵。接口是异步的：先提交任务，再轮询 Essevin 任务 ID。请使用已配置可灵 VOD 账号的分组密钥，正式产生付费任务前先用 GET /v1/models 确认当前密钥实际返回的完整模型 ID。

接口

所有请求使用 Authorization: Bearer sk-你的密钥 和 Content-Type: application/json。请求体采用严格 JSON 契约：未知字段、第二个 JSON 值、顶层 image_url / video_url 和未经验证的嵌套字段会在调用腾讯前拒绝。

模型矩阵

可灵生图模型 ID 包括 kling-image-v3、kling-image-v3-omni、kling-image-o1、kling-image-v2-1、kling-image-v2-1-i2i、kling-image-v2-1-multi-ref 和 kling-image-expand。生图走图片接口，n 支持 1-9，按实际产出张数计费；可用画质档以当前密钥的模型目录为准。

请求契约

素材定位

每个 images[] 或 videos[] 项必须且只能提供以下一个字段：

{ "url": "https://cdn.example.com/file.png" }

或：

{ "file_id": "vod-file-id" }

url 必须是公网可访问的绝对 http:// 或 https:// 地址。空字符串、相对路径、file://、ftp:// 以及同时提供两个字段都会被拒绝。图片接口和人脸识别也遵循同一规则。

普通视频生成

普通视频使用 images[] 传首尾帧或参考图，使用 videos[] 传一个参考 / 编辑视频。不要在顶层使用 OpenAI 的 image_url 或 video_url 字段。

{
  "model": "kling-v3-omni",
  "prompt": "产品在干净的摄影棚桌面上缓慢旋转",
  "duration": 5,
  "resolution": "1080p",
  "audio": false,
  "images": [
    { "url": "https://cdn.example.com/first.png", "usage": "first_frame" },
    { "file_id": "vod-last-frame", "usage": "last_frame" },
    { "url": "https://cdn.example.com/reference-a.png", "usage": "reference" },
    { "file_id": "vod-reference-b", "usage": "reference" }
  ],
  "videos": [
    {
      "url": "https://cdn.example.com/character-motion.mp4",
      "reference_type": "feature",
      "keep_original_sound": false
    }
  ],
  "subjects": [
    { "id": "subject-92951593344", "name": "猫" },
    { "id": "subject-92951593345", "name": "狗" }
  ]
}

普通生成的 images[].usage 必填，可选 first_frame、last_frame、reference。首帧和尾帧各最多一张；指定尾帧必须同时提供首帧；参考图超过两张时不能再指定尾帧。videos[] 最多一项，且 reference_type 必填。feature 仅 kling-v3-omni 和 kling-o1 开放；base 仅已实测且有价的 kling-v1-6 开放，必须是唯一素材，不能和图片或主体混用。

腾讯还有两条数量耦合限制：有参考视频时，reference 图数 + 主体数最多 4；无参考视频时最多 7。没有提示词时必须至少有一个素材。省略 duration、resolution、audio 会统一归一化为 5 秒、720P、无声。

主体与分镜

subjects[] 使用腾讯固定主体 ID，每项必须有非空 id，name 可选。只有 kling-v3-turbo、kling-v3、kling-v3-omni 支持主体；提示词按腾讯主体语法引用，例如 <<<element_1>>>。

分镜仅 kling-v3 和 kling-v3-omni 支持：

{
  "model": "kling-v3-omni",
  "prompt": "",
  "duration": 5,
  "shots": {
    "mode": "customize",
    "segments": [
      { "index": 1, "prompt": "盒子打开", "duration": 2 },
      { "index": 2, "prompt": "产品出现", "duration": 3 }
    ]
  }
}

mode 可取 intelligence 或 customize。智能模式不能带 segments，自定义模式必须带分镜。自定义分镜从 1 开始连续编号，提示词不能为空且不超过 512 字，每段至少 1 秒，时长之和必须严格等于总时长。请使用结构化 shots，extra.multi_shot、extra.shot_type、extra.multi_prompt 会被拒绝。

动作控制

动作控制必须提供恰好一个视频和一张人物图，场景决定两者含义，因此图片不能带 usage，视频不能带 reference_type。videos[].keep_original_sound 是布尔值，网关会映射成腾讯 keep_original_sound 标记。目前唯一验证过的额外参数是 extra.character_orientation（image 或 video）。动作控制时长由输入视频决定，必须省略 duration，产物使用临时存储。

{
  "model": "kling-v3-motion-control",
  "prompt": "跟随舞者的动作",
  "resolution": "1080p",
  "images": [{ "file_id": "vod-person-image" }],
  "videos": [{ "url": "https://cdn.example.com/dance.mp4", "keep_original_sound": true }],
  "extra": { "character_orientation": "video" }
}

数字人与对口型

数字人（kling-avatar）需要 1-5 张人物图，不接受视频，并且必须在 extra.sound_file（HTTP(S) 音频地址）和 extra.audio_id 中二选一。时长由输入音频决定，省略 duration。

对口型（kling-lip-sync）不接受图片。先用一个或多个素材调用人脸识别：

curl https://api.essevin.com/v1/kling/faces \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{"videos":[{"file_id":"vod-source-video"}]}'

再提交返回的 session 和一个 face_choose 项：

{
  "model": "kling-lip-sync",
  "extra": {
    "session_id": "face-session-id",
    "face_choose": [
      { "face_id": "face-1", "sound_file": "https://cdn.example.com/voice.mp3" }
    ]
  }
}

face_choose 必须恰好一项，且包含非空 face_id 与 sound_file。输入音频 / 视频决定时长；对口型按秒计费并有 5 秒下限，4 秒成片按 5 秒收费。腾讯确认对应 SKU 前，voice_ids 和 extra.voice_list 均不可用。

提交与轮询

  -H "Authorization: Bearer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{"model":"kling-v3","prompt":"红球在白桌面上滚动","duration":5,"resolution":"720p"}'

202 响应会返回形如 kt57x<upstream-task-id> 的任务 ID。不要在查询时传计费标头：

  -H "Authorization: Bearer sk-你的密钥"

状态为 queued、processing、completed 或 failed。完成后的 outputs 是 Essevin 中继地址，插件不长期保存源文件；回源前会校验任务级 file token。只有内部钉选轮询观察到腾讯成功 FINISH、ErrCode=0、产物合法且有计费时长时才产生一次 Usage。FINISH 但 ErrCode 或 ErrCodeExt 非空属于失败，不计费。

计费单位与桶

模型目录中的 price.unit 明确单位：视频为 second，生图为 image，人脸识别为 call。视频基准价是腾讯人民币牌价除以站内固定汇率 6.8；Core 再单独乘分组倍率。

缺失或尚未确认的桶一律不可售，不会静默落到相邻价格。kling-v3-omni 4K 无声 feature 参考视频桶等待第二份腾讯确认后再开放；调用方指定音色同样暂不开放，请不要发送 voice_ids 或 extra.voice_list。