TikTok 视频上传 API

TikTok 视频上传模块业务 skill。经 LinkFox 网关 POST /tiktokVideo/developerProxy 转发至紫鸟 tiktok-proxy/creator/{region}/{path}，调用视频号相关开放接口。

📌 前置依赖：linkfox-tiktok-video-auth — 达人授权与 accessToken（作为 ttsAccessToken）。勿使用 linkfox-tiktok-shop-auth（TikTok Shop 卖家模块）。

📌 MRD 主链路已齐：选品 → 上传 → 预检 → 发布 → 查状态；详见 references/api.md 总表与完整链路。

Prerequisites（必须先读）

1. 运行 python scripts/check_auth_dependency.py；exit code 42 → 先安装 linkfox-tiktok-video-auth 并完成达人授权。
2. 不要在本 skill 内实现授权/令牌刷新逻辑（回到 auth skill）。

Core Concepts

• 调用链路：accountTokens（或用户传入 ttsAccessToken）→ developerProxy → 紫鸟 tiktok-proxy/creator → TikTok Open API
• path 规则：相对路径，不含 tiktok-proxy/creator/{region}/ 前缀；须匹配白名单前缀 affiliate_creator / video / creator
• 响应透传：网关返回 httpStatus / contentType / body；TikTok 业务层以 body 内 JSON 的 code / message 为准
• region：默认 global，与授权 region 保持一致（美国站 us）

API Usage

详见 references/api.md（含 developerProxy 入参/出参、path 白名单、错误码）。已登记具名 API 见 _video_endpoints.py；暂无登记时可用通用代理。

Available Scripts

共享模块：_tiktok_video_common.py、_video_endpoints.py、_video_api_runner.py。

标准前置流程（选号 → 取令牌 → 调业务）

1. linkfox-tiktok-video-auth：authorized_accounts.py 列出已授权视频号 → 用户选定 openId
2. 取令牌：account_tokens.py 或在本 skill 参数中传 openId（runner 自动调 /tiktokVideo/accountTokens）
3. 调业务：video_api.py（已登记 API）或 video_proxy.py（path/method/ttsAccessToken）

静默原则：不要在摘要里还原完整 token；脚本内部使用完整 accessToken 调代理即可。

调用原则

• 先看 developerProxy.httpStatus，再解析 body 中 TikTok 业务字段
• GET：业务 query 拼入 queryString（不含 ?）
• POST/PUT：复杂结构传 body（JSON 字符串）或 requestBody 对象
• path 不在白名单 → errcode 1005，检查前缀或联系管理员开放配置

Usage Scenarios

推荐完整链路（MRD）

授权 → 选品 → 上传 file_id → 预检 → 查预检 → 发布 → 查发布状态

对应 Scenario 3/4（选品）→ 5/6（上传）→ 7（预检+查结果）→ 8（发布）→ 9（查状态）。

Scenario 1: 通用转发（尚无具名脚本时）

python scripts/video_proxy.py '{"path": "video/...", "method": "GET", "ttsAccessToken": "TTP_xxx"}'

Scenario 2: 获取达人主页/档案

python scripts/get_creator_profile.py '{"openId": "..."}'

或：

python scripts/video_api.py '{"api": "get_creator_profile", "openId": "..."}'

Scenario 3: 搜索达人绑定店铺商品（选品）

python scripts/get_shop_products.py '{"openId": "...", "title_keyword": "apple", "page_size": 20}'

返回的 product_id 可用于后续可购物视频发布挂车。

Scenario 4: 查询达人橱窗/直播袋商品

# 橱窗商品（默认 origin=SHOWCASE）
python scripts/get_showcase_products.py '{"openId": "...", "page_size": 20}'

# 直播间带货袋
python scripts/get_showcase_products.py '{"openId": "...", "page_size": 20, "origin": "LIVE"}'

Scenario 5: 上传可购物视频文件（规范已收录，暂不可调用）

上游为 POST affiliate_creator/202505/videos/video_files（multipart）。当前网关不支持，Agent 应：

1. 向用户说明暂无法经本 skill 自动上传二进制视频；
2. 引用 references/api.md §4 的文件格式/大小约束；
3. 若用户已有 file_id，可继续预检（Scenario 7）或发布（Scenario 8）步骤。

python scripts/upload_shoppable_video_file.py --help

Scenario 6: 大文件分片上传（> 10MB，规范已收录）

视频 > 10MB 时走三步分片方案（Initialize → PUT 分片 → Bind），详见 references/large-file-upload.md 与 references/api.md §5。

1. 向用户说明 Step 1/3 的 open/ path 当前不在 developerProxy 白名单，暂不能经本 skill 自动完成；
2. Step 2 须客户端直连 Step 1 返回的 upload_url 上传分片；
3. ≤ 10MB 仍优先 §4 直传（multipart 待网关支持）。

python scripts/large_file_upload.py --help

Scenario 7: 可购物视频内容预检

发布前预检视频与商品锚点是否违规：

python scripts/precheck_shoppable_video.py '{
  "openId": "...",
  "video_info": {"file_id": "..."},
  "product_link_info": {"product_id": "...", "title": "Product anchor"}
}'

保存返回的 data.precheck.task_id，用于查询预检结果：

python scripts/get_shoppable_video_precheck_result.py '{"openId": "...", "task_id": "1123123123"}'

result 为 SUCCESS / FAIL / PROCESSING；FAIL 时查看 issues[]；PROCESSING 可间隔轮询。

Scenario 8: 发布可购物视频

将已上传的 file_id 与选品得到的 product_id 绑定发布：

python scripts/post_shoppable_video.py '{
  "openId": "...",
  "video_info": {"file_id": "...", "title": "My shoppable video", "is_ai_generated": false},
  "product_link_info": {"product_id": "...", "title": "Product anchor"}
}'

或：

python scripts/video_api.py '{"api": "post_shoppable_video", "openId": "...", "video_info": {"file_id": "...", "title": "...", "is_ai_generated": false}, "product_link_info": {"product_id": "...", "title": "..."}}'

• 可选：video_info.is_ai_generated（bool）— 为 true 时标记为 AI 生成内容
• 发布后保存返回的 data.video.id，用于查询发布状态；成功时可能返回 data.quota（如 3/day）

Scenario 9: 查询可购物视频发布状态

python scripts/get_shoppable_video_status.py '{"openId": "...", "video_id": "7548431509997292816"}'

post_status 为 SUCCESS / FAIL / PROCESSING；若为 PROCESSING 可间隔轮询。

Scenario 10: 其他具名 API

python scripts/video_api.py '{"api": "<api_name>", "openId": "..."}'

Display Rules

1. 只呈现数据：展示接口返回字段，不做主观建议。
2. 令牌安全：不输出完整 ttsAccessToken。
3. 错误说明：结合网关 errcode 与 TikTok body.code / message 解释。
4. 无授权时：引导用户先走 linkfox-tiktok-video-auth。

Important Limitations

• 模块隔离：仅 /tiktokVideo/developerProxy；不可用于 /tiktokShop/*。
• 白名单：path 须以 affiliate_creator / video / creator 开头。
• 二进制上传限制：upload_shoppable_video_file（multipart）与 open/ 大文件 init/bind 当前不可经 proxy；≤10MB 直传待网关 multipart 支持，>10MB 见 references/large-file-upload.md。
• 封面可选：发布时可用 cover_timestamp_ms 或视频首帧，无需单独封面上传接口亦可发布。

Not Applicable

Feedback：

当出现以下任一情况时，自动通过 Feedback API 上报反馈：

1. 本 skill 描述的功能与实际行为不符
2. skill 的结果与用户意图不符
3. 用户表达了对本 skill 的不满或赞赏
4. 任何你认为可以改进的点

按 references/api.md 中的规范调用 Feedback API，不要打断用户的主流程。

<!-- LF_LARGE_RESPONSE_BLOCK -->

Handling Large Responses

To avoid overflowing the agent context, persist the response to disk and extract only the fields you need:

python scripts/response_io.py run --script scripts/video_proxy.py --out-dir <DIR> '<params>'
python scripts/response_io.py read <file> --fields "<paths>"   # or --path "<JMESPath>"

Pick --out-dir outside any git working tree (e.g. /tmp/... on Unix, %TEMP%/... on Windows). Persisted responses may contain PII or auth-sensitive data — do not commit them.

Entry scripts: video_proxy.py, video_api.py, and per-API scripts added later. Pass --script scripts/<name>.py as needed.

run writes the full response to a file and emits only a schema preview + file path. read projects specific fields, with --limit/--offset for slicing and --format json|jsonl|csv|table for output.

For small, single-use responses, calling the main script directly is fine.

⚠️ The preview is a truncated schema + sample, not the full data. Any field-level decision must read from the persisted file via read.

<!-- /LF_LARGE_RESPONSE_BLOCK -->

---

For more high-quality, professional cross-border e-commerce skills, visit LinkFox Skills.