kling-video-motion-control-v2.6 API

## 参数详情 可选提示词最多2500字符；动作由参考视频提供，文字用于描述人物外观或场景。 请求体使用JSON；下面的点号表示嵌套字段，例如 `settings.resolution` 写在 `settings` 对象中。 | 字段 | 类型 | 必填 | 说明 | |---|---|---|---| | `model` | string | 是 | 目标视频型号；可选 kling-video-motion-control-v2.6 | | `prompt` | string | 否 | V3／Turbo文生视频时填写；使用contents的场景在type=prompt中填写text。 | | `contents` | array | 是 | 按素材类型传入text或url；动作控制同时提供image与video。 | | `contents[].type` | string | 是 | 按当前型号与场景选择；可选 prompt, image, video | | `contents[].text` | string | 否 | type=prompt时必填 | | `contents[].url` | string | 否 | 图／视频类型必填，公网HTTPS地址 | | `contents[].id` | string | 否 | voice及动作控制element的任务内唯一引用名 | | `settings` | object | 是 | 720p、1080p；人物朝向image时参考视频3～10秒，video时3～30秒；不支持主体引用。 | | `settings.resolution` | string | 否 | 输出清晰度；可选 720p, 1080p；默认 "720p" | | `settings.character_orientation` | string | 是 | 人物朝向；image最长10秒、video最长30秒；可选 image, video | | `settings.audio` | string | 否 | 原声或静音；可选 original, off；默认 "original" | | `options` | object | 否 | 可选水印和外部业务标识。 | | `options.external_task_id` | string | 否 | 业务标识；本站查询仍使用返回id | | `options.watermark_info` | object | 否 | 水印选项 | | `options.watermark_info.enabled` | boolean | 否 | 是否开启水印 | | `wait` | boolean | 否 | false：提交后立即返回任务ID；true：等待一段时间后返回当前任务状态。；默认 false | | `nonce` | string | 否 | 新生成更换nonce；异常恢复沿用原值 | | `idempotency_key` | string | 否 | 兼容字段，不作为当前视频去重依据 | ## 查询与响应 `GET /v1/videos/generations/{id}` 查询单个任务。`GET /v1/videos/generations?limit=20&offset=0` 查看任务列表，返回 `data`、`total`、`limit`、`offset`。 pending / submitted / processing 表示进行中；succeeded 表示生成成功；failed / timeout / canceled 表示任务已结束。 | 字段 | 类型 | 必填 | 说明 | |---|---|---|---| | `id` | string | 否 | 原样保存的查询任务ID | | `model` | string | 否 | 公开型号 | | `status` | string | 否 | 本站权威状态；可选 pending, submitted, processing, succeeded, failed, timeout, canceled, unknown | | `created_at` | integer | 否 | Unix秒 | | `error` | object | 否 | 成功通常null，失败可有code和message | | `error.code` | string | 否 | 错误码 | | `error.message` | string | 否 | 错误说明 | | `request_id` | string | 否 | 结果请求标识，不是任务ID | | `code` | integer | 否 | 模型结果业务码 | | `message` | string | 否 | 结果说明 | | `data` | array | 否 | 模型终态结果列表；需容忍兼容对象形状 | | `data[].id` | string | 否 | 任务标识 | | `data[].status` | string | 否 | 模型结果状态 | | `data[].message` | string | 否 | 任务说明 | | `data[].create_time` | integer | 否 | Unix毫秒 | | `data[].update_time` | integer | 否 | Unix毫秒 | | `data[].outputs` | array | 否 | 视频结果 | | `data[].outputs[].type` | string | 否 | video | | `data[].outputs[].id` | string | 否 | 输出标识，不是查询任务ID | | `data[].outputs[].url` | string | 否 | 临时视频URL，及时保存 | | `data[].outputs[].duration` | string | 否 | 输出秒数，可能带小数；兼容number | | `data[].usage` | object | 否 | 可选原生统计，缺失不等于0 | | `data[].usage.prompt_tokens` | integer | 否 | 原生输入Token；未提供时未知 | | `data[].usage.input_tokens` | integer | 否 | 可选原生输入别名，按实际字段保留 | | `data[].usage.completion_tokens` | integer | 否 | 原生输出Token；不跨口径补值 | | `data[].usage.output_tokens` | integer | 否 | 可选原生输出别名，按实际字段保留 | | `data[].usage.total_tokens` | integer | 否 | 原生总量，允许与官方计费总量不同，不再次收费 | | `tokenhub_usage` | object | 否 | 官方计费及对账口径；不叠加原生统计 | | `tokenhub_usage.total_tokens` | integer | 否 | 有效非负整数，包括明确0；实际费用采用的官方总量 | | `usage` | object | 否 | 兼容量，可能是官方量别名或原生统计，不能再次计费 | | `usage.prompt_tokens` | integer | 否 | 原生输入Token；未提供时未知 | | `usage.input_tokens` | integer | 否 | 可选原生输入别名，按实际字段保留 | | `usage.completion_tokens` | integer | 否 | 原生输出Token；不跨口径补值 | | `usage.output_tokens` | integer | 否 | 可选原生输出别名，按实际字段保留 | | `usage.total_tokens` | integer | 否 | 依字段来源判别，不能与tokenhub_usage重复累计 | 顶层 `usage.total_tokens` 表示该任务返回的总用量，可能包含参考视频输入；核对用量时不要只看输出时长。`tokenhub_usage`、`data`内部的原始用量及输入／输出细项仅在响应提供时出现；不同口径不相加，缺失不表示0。示例中的时间、标识、媒体和Token数字均为虚构数据。 ## 重试与新任务 请求结果不明确时，先查询原任务。需要标识一次提交时，可设置 `nonce` 或 `idempotency_key`；同一次提交重试沿用原值，新生成使用新值。保留返回的任务id与请求id，便于查询。 ## 常见错误 | HTTP状态 | 处理说明 | |---|---| | 400 | 参数、素材、计费模式或当前能力不支持 | | 401 | 令牌无效 | | 403 | 权限不足 | | 402 | 可用余额不足或预留失败 | | 404 | 查询任务不存在或无权访问 | | 409 | 原提交待确认，不换nonce | | 422 | 公共Schema或JSON校验失败 | | 429 | 请求受限，先核对原任务 | | 500 | 内部错误，受理状态须核对 | | 502 | 生成服务错误，受理状态须核对 | | 503 | 暂不可用，受理状态须核对 | 任务未结束时不支持取消。生成后使用返回的HTTPS地址获取视频。错误响应的通用结构见右侧400示例，具体字段以实际返回为准。 ## 参考素材要求 形象图：JPEG／PNG，最大50MB，宽高至少300px，画幅比1:2.5～2.5:1。动作视频：MP4／MOV，最大100MB，宽高340～3850px，至少3秒。人物朝向image时最长10秒，video时最长30秒。 不传duration或aspect_ratio；成片时长和画幅跟随有效动作及输入素材。人物比例尽量一致，动作视频优先使用清晰的单人连续动作。audio可用original保留原声或off静音，默认original。 ## 官方参考 [官方调用指南](https://www.tencentcloud.com/zh/document/product/1300/83714) · [国际版指南](https://intl.cloud.tencent.com/zh/document/product/1300/83714) · [官方价格说明](https://www.tencentcloud.com/zh/document/product/1300/78937)

curl --request POST \
  'https://api.router.ai/v1/videos/generations' \
  -H "Authorization: Bearer $OPENCROW_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary '{
  "model": "kling-video-motion-control-v2.6",
  "contents": [
    {
      "type": "image",
      "url": "https://media.example.com/character.png"
    },
    {
      "type": "video",
      "url": "https://media.example.com/motion.mp4"
    }
  ],
  "settings": {
    "character_orientation": "image",
    "resolution": "720p",
    "audio": "off"
  },
  "wait": false
}'