Kling 风格异步媒体 API

小白：区分本站入口与 Kling 直连

/kling/v1/* 是本站提供的 Kling 风格兼容入口。它保留熟悉的动作路径，但鉴权、公开任务 ID 和查询响应由本站网关管理，不是对 api.klingai.com 的无条件透传。通过本站时发送本站 Authorization: Bearer $API_KEY；直连 Kling 则按官方文档用 Access Key 和 Secret Key 签发短期 JWT。两套 Base URL 和凭据不能混用。

网页产品、Kling 官方 API 与本站适配能力也不是同一个集合。调用前在令牌管理创建本站 API Key，并在模型广场确认当前 Key 分组可见 kling_video，且模型详情列出当前动作端点：

Copyexport BASE_URL="https://api.tu-zi.com"
export API_KEY="你的本站 API Key"
export KLING_MODEL_NAME="kling_video"

kling_video 是本站当前公开的代表性视频入口，网关当前默认把它映射为上游 kling-v1。下面的请求明确选择 std 和 5 秒，但没有选择 v3。模型广场中出现 v3、std、pro 和时长等计费/能力变体，不代表 model_name: kling_video 会自动调用 v3，也不能把 v3 自行拼成另一个本站模型 ID。只有模型广场或本站接口明确公开可路由的 v3 模型 ID 或版本字段后，才应按该契约选择 v3。

文生视频最小请求

Copycreate=$(curl -sS "$BASE_URL/kling/v1/videos/text2video" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<JSON
  {
    "model_name":"$KLING_MODEL_NAME",
    "prompt":"纸雕白兔穿过晨雾森林，镜头缓慢前移",
    "negative_prompt":"模糊，闪烁",
    "mode":"std",
    "duration":"5",
    "aspect_ratio":"16:9"
  }
JSON
)

task_id=$(printf '%s' "$create" | jq -r '.id // .task_id')
test -n "$task_id" && test "$task_id" != "null"

创建成功会返回本站公开 id/task_id；Kling 上游的 request_id 和内部任务 ID 可能被单独保存。业务系统应同时保存本站 Request-ID、公开任务 ID、动作 kind、模型、创建时间和脱敏参数。HTTP 200 只表示任务已提交。

图生视频与动作选择

图生视频使用 POST /kling/v1/videos/image2video，在请求中提供 image；可选尾帧为 image_tail。参考图既可能是 HTTPS URL，也可能是受支持的编码值，具体范围以当前模型与渠道为准。text2video、image2video、effects、lip-sync、extend 等动作有不同必填字段，不能只替换 URL 而复用同一请求体。

Copycurl "$BASE_URL/kling/v1/videos/image2video" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<JSON
{"model_name":"$KLING_MODEL_NAME","image":"https://assets.example.com/input.jpg","prompt":"主体转身看向镜头","duration":"5"}
JSON

查询、终态与结果

查询 kind 要与创建动作族匹配：

Copywhile :; do
  task=$(curl -sS "$BASE_URL/kling/v1/videos/text2video/$task_id" \
    -H "Authorization: Bearer $API_KEY")
  status=$(printf '%s' "$task" | jq -r '.data.status // .status // empty')
  case "$status" in
    SUCCESS) printf '%s\n' "$task"; break ;;
    FAILURE) printf '%s\n' "$task" >&2; exit 1 ;;
    SUBMITTED|QUEUED|IN_PROGRESS) sleep 5 ;;
    *) printf '未知任务状态：%s\n' "$status" >&2; exit 1 ;;
  esac
done

规范模式写作 GET /kling/v1/videos/{kind}/{task_id}。本站查询响应使用任务信封，data.status 可能为 SUBMITTED、QUEUED、IN_PROGRESS、SUCCESS 或 FAILURE；只有后两者是终态，成功后从 result_url 或结果数据读取媒体。Kling 直连响应的状态名可能是小写 submitted、processing、succeed、failed，不要把直连解析器和本站解析器混用。

轮询应指数退避并加入抖动，保存总超时和取消状态。动作 kind 错误、任务不属于当前用户或使用 request_id 代替 task_id 都会导致查询失败。

媒体、安全、计费与重试

对输入 URL 实施 SSRF、防重定向绕过、内容类型和字节上限；对 Base64 先估算解码大小。人脸、对口型、声音和虚拟试穿等动作需要更严格的授权、活体/冒用风险和内容审核。任务成本可能随模型、模式、时长、分辨率、音频和动作变化，必须用账单日志核对，不能只按请求次数估算。

创建超时可能已经产生任务和费用。用业务幂等记录先查已有公开 task_id；参数或审核错误不重试，429 退避降并发，临时 5xx 才有限重试。签名结果 URL 应在成功后流式复制到受控存储，并记录哈希、大小、时长、权限与删除时间。

专家：多能力接入与上线门禁

本站还注册了 Kling 图像、音频、头像、特效、对口型、延长和多元素动作；每个动作都应按“路径 + 请求字段 + 模型 + 计费维度 + 终态”单独做契约测试。上线门禁至少覆盖显式 false/0 值透传、任务 ID 映射、查询路径亲和、失败退款/结算、结果过期、渠道切换和降级。监控提交成功率、各 kind 完成率、P95 时延、失败原因、重复任务、单位秒成本与结果保存失败。