ikc-video-sdk

IKC 视频引擎（ikc-video-service）的独立客户端 SDK 分发（导入包 ikc_video_sdk）。

• 与 ikc-video 服务端 wheel 中的 ikc_video_sdk 同源（force-include 自 ../src/ikc_video_sdk），版本号保持一致；
• 供下游（pipeline / ikc-open-platform 等）以正常依赖模式引用，无需安装服务端重型依赖（celery/redis/fastapi/pyuploadx 等）；
• 能力面：typed 视频资源方法（V-01 异步切片、V-02 同步处理）+ 系统路由（/、/health、/ready、/api/catalog、/api/error-codes）+ 泛化 client.request； 统一响应壳解包与类型化异常；身份信任头 / Bearer / 23 位 traceId / 幂等重试装配。

用法与资源清单见 docs/客户端SDK设计与使用.md。

跨层能力来自 ikc-sdk-lib（不自定义）

视频域 260xxx 与下游 509xxx 码字面量由本 SDK 的 ikc_video_sdk.codes 发布， 与服务端 registry（/api/error-codes）的一致性由 tests/test_sdk_contract.py 守护。

安装

pip install /home/sharkyai/ikc-video-service/sdk/dist/ikc_video_sdk-0.1.0-py3-none-any.whl

快速开始

from ikc_video_sdk import IkCVideoClient

with IkCVideoClient("http://127.0.0.1:19200", token="dev-token") as client:
    print(client.system.health())                      # {"status": "ok", ...}

    # V-01 异步切片：请求体嵌套 media（与 V-02 的扁平形状不同，由 SliceRequest 固化）
    accepted = client.video.slice(
        media={"source_format": "mp4", "object_key": "mm/video/a.mp4"}, mode="scene"
    )
    print(accepted.taskId)                             # 结果由上游按 taskId 获取

    # V-02 同步处理：扁平请求体，阻塞至 mm-schema 清单产出
    result = client.video.process(object_key="mm/video/a.mp4", klgId="klg_1")
    print(result.manifest_key, len(result.segments))

入参三选一：请求模型（SliceRequest / VideoProcessRequest，SDK 侧即校验）、 线缆 dict（原样透传，服务端校验）、关键字字段（按模型校验后只发显式传入的字段）。 V-01 的媒体来源在 media 下（media.object_key / media.input_url 二选一）， V-02 则在顶层，传错形状会得到 100001。

异步版方法同名（AsyncIkCVideoClient），生产（IKC_VIDEO_AUTH_MODE=gateway_header） 传 identity=CallerIdentity(user_id=..., tenant_id=...) 以透传信任头。

版本与兼容性

升级 ikc-sdk-lib pin 属兼容性变更，须与服务端 pyproject.toml 同步； 所有涉及 Celery 的依赖组另受 /home/sharkyai/依赖版本强制契约.md 约束（SDK 不引入 celery）。

分发形态：本包只发布 wheel（sdk/dist/ikc_video_sdk-<version>-py3-none-any.whl）。 sdist 在「由 sdist 重建 wheel」时会因 force-include 的相对路径（../src/ikc_video_sdk）失效而失败，故不上传 sdist。