HAiNA CLI docs

HAiNA CLI 使用手册

视频发布 API 平台——系统使用与接口接入指南

HAiNA CLI 是面向 TikTok / TikTok Shop 的视频发布 API 平台。简单说：你把视频传上来，剩下的「发到 TikTok / 挂车带货」全部可以用几行 API 调用搞定——不用自己对接 TikTok 的 OAuth、签名、文件分片这些脏活。

平台心智模型

概念说明
坐席（Seat）1 个 TikTok 账号 = 1 个坐席。坐席是计费单位（套餐按"坐席 × 月"）。一个坐席可绑定同一账号的两种能力：TikTok 发视频（TT）与 TikTok Shop 挂车（TTS）
API Token你的调用凭据（vg_live_ 开头），在「API Keys」页创建，明文只显示一次
视频库TikTok 视频：上传后拿公网 videoUrl（7 天有效）；TikTok Shop 视频：上传后拿官方 fileId（一次性消耗，发布即作废）
商品库TikTok Shop 账号下可挂车商品的实时拉取（店铺 + 橱窗），拿到 productId 用于挂车发布

术语对照（看社区帖子/官方文档时不会迷路）：

本平台官方名称社区俗称
TikTok 发布（命令/枚举里的 tt / TT）TikTok 内容发布（视频帖子 / 图片帖子）TK 发视频
TikTok Shop 挂车（命令/枚举里的 tts / TTS）TikTok Shop Shoppable Video（挂车视频）TK 小店挂车、小黄车带货

注：TTS 在本平台语境里专指 TikTok Shop——它与"文本转语音（Text-to-Speech）"同形纯属巧合，两边不要混淆。

一个好消息：接口入参全部使用 TikTok / TikTok Shop 官方返回的 id（videoUrl、fileId、accountId、productId、taskId……），本平台不引入任何自造 id——你在官方文档里看到的概念，在这里一一对应。

三条主路径

用 AI agent：MCP / CLI 直连

视频素材在自家 OSS、日常在 Cursor / Claude Code 里干活？给 agent 配一行远程 MCP 地址（零本地运行时），说一句话就能完成「上传 → 发布 → 轮询终态」：

{ "mcpServers": { "haina": { "url": "https://mcp.haina.io/mcp", "headers": { "Authorization": "Bearer vg_live_xxxxxxxx" } } } }

详见 MCP 接入指南（本地文件场景走 CLI + Agent Skill）。

无技术能力：后台 + Playground

  1. 找管理员开通账号与套餐（坐席数）
  2. 「坐席」页绑定你的 TikTok / TikTok Shop 账号（扫码或点链接授权）
  3. 「视频库」上传视频，复制返回的 videoUrl / fileId 与账号 ID
  4. 打开内置 API Playground（不用装 Postman），按本手册的示例填参数、点「Try it」

详见后台操作指南。

有技术能力：全 API 集成

BASE=https://cli.haina.io
TOKEN=vg_live_xxxxxxxx          # 「API Keys」页创建

# 1. 查坐席拿到已绑定账号 ID
curl -H "Authorization: Bearer $TOKEN" $BASE/v1/seats

# 2. 上传视频（TikTok 库为例）
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -F "file=@demo.mp4" $BASE/v1/videos

# 3. 发布到 TikTok（videoUrl 用第 2 步响应的原值；account 传第 1 步 TikTok 账号的 businessId 或 username）
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"videoUrl":"<第2步返回的 videoUrl>","account":"<第1步 TikTok 账号 businessId 或 username>","caption":"#tag"}' \
  $BASE/v1/tiktok/v1.3/business/video/publish

统一响应信封

所有端点返回统一结构：

{ "code": 0, "message": "ok", "data": { } }
  • code = 0：成功，data 为业务数据
  • code ≠ 0：失败，message 为原因；HTTP 状态码与 code 对应（见错误码表）

即使官方 TikTok 侧失败，HTTP 也可能是 200/4xx——永远以 code 为准。

本手册导航

认证与约定

Bearer Token、envelope、错误码、订阅守卫

On this page

平台心智模型三条主路径用 AI agent：MCP / CLI 直连无技术能力：后台 + Playground有技术能力：全 API 集成统一响应信封本手册导航