/v1 端点地图与全局口径——字段级文档以 API Playground 为准（openapi 单源渲染）

API 参考

字段级文档都在 API Playground：全部端点的参数/响应/错误码逐字段说明由 openapi 单源渲染，可直接「Try it」调真接口（同源请求，免 CORS）。本页不再重复字段表，只承载 spec 装不下的内容：端点地图、全局口径、官方字段对照。

Playground 使用要点

端点按平台分 6 组（通用 / TikTok 视频发布 / TikTok Shop 挂车视频 / TikTok 评论与私信 / TikTok 数据洞察 / 事件推送），在 Playground 左侧边栏顶部的文档选择器里切换——与本页「端点地图」的分组一一对应
认证框里只粘裸 Token（vg_live_xxx，不要自己加 Bearer 前缀，否则会报 1001；详见认证与约定）
所有端点返回统一 envelope { code, message, data }，永远以 code 为准；错误码与限流语义见认证与约定
「写」操作（上传/发布/删除/重投）受订阅守卫约束：套餐过期返回 1003，只读接口不受影响

端点地图

通用

端点	读/写	说明
`GET /v1/seats`	读	坐席列表（含绑定；`capabilityAccountId`：TikTok 发布=businessId / TikTok Shop=creatorUserOpenId）
`POST /v1/videos`	写	上传视频（multipart 直传或 JSON `sourceUrl` 拉流）；TikTok 库返回 `videoUrl`（7 天有效），TikTok Shop 库返回 `fileId`（一次性消耗）
`GET /v1/videos`	读	游标分页；软删记录仍返回（`status=expired`），判断可用性看 status
`GET /v1/videos/{id}`	读	单条详情
`DELETE /v1/videos/{id}`	写	软删=立即失效（发布/预审拒绝 `2005`），记录保留审计留痕

TikTok 视频发布（按发布流程排序）

端点	读/写	说明
`GET /v1/tiktok/v1.3/business/hashtag/suggestion`	读	① 话题推荐（caption 写作辅助）
`GET /v1/tiktok/v1.3/business/publish/location`	读	① 地域标签搜索（图片帖挂地点用）
`POST /v1/tiktok/v1.3/business/video/publish`	写	② 视频发布；账号字段为 `account`（username 或 businessId）
`POST /v1/tiktok/v1.3/business/photo/publish`	写	② 图片帖发布：`photoUrls` 1-35 张 + `privacyLevel` 必填
`GET /v1/tiktok/v1.3/business/publish/status?publishId=`	读	③ 发布状态刷新（推荐入口）：命中发布记录即回写 + 归一化响应（只需 publishId，account 可省）；未命中时 account 必传、退化为纯官方直查
`GET /v1/publish/records`	读	发布记录分页（只读快照，不刷新状态）

TikTok Shop 挂车视频（按发布流程排序）

端点	读/写	说明
`POST /v1/products/query`	读	① 可挂车商品拉取（60s 短缓存，`fresh:true` 穿透）
`POST /v1/photos`	写	②（可选）上传封面图 → `photoUri`（≤10MB，9:16~16:9）
`POST /v1/music/search`	读	②（可选）电商授权音乐搜索（分页怪癖见 Playground 说明）
`POST /v1/publish/tts/precheck`	写	③（可选）预审提交（配额 50 次/天/账号）
`GET /v1/publish/tts/precheck/{taskId}`	读	③（可选）预审结果（violation 维度归一 passed/failed）
`POST /v1/publish/tts`	写	④ 挂车发布（`fileId`/`accountId`/`productId`/`title` 必填；无需预审凭证）
`GET /v1/publish/tts/status?videoId=`	读	⑤ 发布状态刷新（入参为官方 video_id，见下方口径坑）

评论与私信（TikTok，与官方接口路径一致）

端点	说明
`GET /v1/tiktok/v1.3/business/comment/list` · `…/comment/reply/list`	评论列表 / 回复列表
`POST …/comment/create` · `…/comment/reply/create`	发顶层评论 / 回复评论
`POST …/comment/like` · `…/comment/hide` · `…/comment/delete`	点赞/取消 · 隐藏/恢复 · 删除（仅限自评）
`GET …/message/conversation/list` · `…/message/content/list`	私信会话列表 / 会话消息（固定最近 20 条）
`POST …/message/send`	发私信（文本/图片/分享帖子/QA 卡片/Typing/已读，恰选其一）
`POST …/message/media/upload` · `POST …/message/media/download`	私信图片上传（mediaId 30 天有效）/ 媒体下载地址（24h 有效）
`GET …/message/capabilities/get`	会话能力自检（发图前查 IMAGE_SEND）
`POST …/message/auto_message/{get\|create\|update\|delete\|sort\|status/update}`	自动消息（欢迎语/常见问题/输入框提示）

数据洞察（TikTok，与官方接口路径一致）

端点	说明
`GET /v1/tiktok/v1.3/business/get?account=`	账号概览（给日期范围才回 metrics 日序列）
`GET /v1/tiktok/v1.3/business/video/list?account=`	视频列表+指标（`maxCount` ≤20；TikTok / TikTok Shop 视频通用——挂车视频也在账号列表里，按标题/时间定位）
`GET /v1/tiktok/v1.3/business/benchmark?account=&category=`	行业基准（官方 25 类目枚举）
`GET /v1/tiktok/v1.3/business/video/settings?account=`	发布隐私档位/最大时长（发布前自检）

事件推送

端点	读/写	说明
`POST /v1/webhook-endpoints` · `GET /v1/webhook-endpoints` · `DELETE /v1/webhook-endpoints/{id}`	写/读/写	推送端点管理（secret 仅创建时返回一次）
`GET /v1/events`	读	事件流拉取（push 的对账兜底）
`GET /v1/events/stream`	长连	SSE 实时事件流（支持 Last-Event-ID 续传）；CLI 封装 `haina listen`
`POST /v1/events/{id}/redeliver`	写	事件重投（可 `endpointId` 定向）

废弃端点与迁移（1.6.x 移除，移除前功能不受影响；仍在用旧端点的集成请按下表迁移）

旧端点（将要废弃）	迁移到	说明
`POST /v1/publish/tiktok`	`POST /v1/tiktok/v1.3/business/video/publish`	账号字段 `accountId` → `account`（可传 username）；其余参数、返回、状态轮询同口径
`GET /v1/publish/tiktok/status?shareId=`	`GET /v1/tiktok/v1.3/business/publish/status?publishId=`	`publishId` 传旧 `shareId` 即可，命中发布记录时行为完全一致
`GET /v1/publish/stats?itemId=`	`GET /v1/tiktok/v1.3/business/video/list?videoIds=<postId>`	与官方路由一致，字段更多

TikTok 视频发布有两个端点：新版 POST /v1/tiktok/v1.3/business/video/publish（默认推荐，CLI 默认通道）与旧版 POST /v1/publish/tiktok（将要废弃——1.6.x 移除，移除前功能不受影响；CLI --via beervid 可选）。两版的参数、返回字段（publishId/shareId/status）完全同口径；状态轮询统一走新版路径 GET /v1/tiktok/v1.3/business/publish/status（命中发布记录即回写）。图片帖发布只有新版。

发布状态归一化（status ↔ 官方原值）

官方状态文案大小写混杂，平台统一收口为小写：

`status`	官方原值	含义
`submitted`	—	已提交，待官方处理
`publish_processing`	`PROCESSING_DOWNLOAD` / `PROCESSING` 等	TikTok 正在下载/处理视频
`publish_complete`	`PUBLISH_COMPLETE` / `PUBLISHED` / `SUCCESS`	发布成功（`postId` 可得，官方延迟约 3 分钟）
`publish_failed`	`FAILED` 等	发布失败，原因见 `beervid.reason` / `failReason`
`publish_draft_inbox`	`SEND_TO_USER_INBOX`	草稿入收件箱（仅 `--draft` 草稿发布）
`beervid_error`	—	平台到官方接口的调用失败（可重试）

轮询建议：每 5–10 秒一次、最多约 30 次，到达终态即停。

发布记录的 videoId vs shareId（最易踩的口径坑）

GET /v1/publish/records 返回里——

videoId = 平台视频库记录 ID（只用于 GET/DELETE /v1/videos/{id} 视频库管理）
shareId = 官方句柄：TikTok 发布记录是官方 share_id（查发布状态的入参），TikTok Shop 记录是官方 video_id（查挂车状态的入参）

勿拿 records 的 videoId 去查发布状态（必 1005）；查状态一律用发布响应里返回的 shareId（TT）/videoId（TTS）。

官方字段对照

如果你在读 TikTok 官方文档，本平台把官方的嵌套结构拍平了，一一对应如下。

TikTok 发布 ↔ 官方 Business API（v1.3 /business/video/publish/）

本平台字段	官方字段	备注
`videoUrl`	`video_url`	公网 URL，官方自行下载
`accountId` / `account`	`business_id`	坐席里 TikTok 绑定的账号（新版可用 username）
`caption`	`post_info.caption`	≤2200 字符（UTF-16），提及 ≤30 条
`isBrandOrganic`	`post_info.is_brand_organic`	品牌自然流量内容
`isBrandedContent`	`post_info.is_branded_content`	品牌内容（优先级更高）
`disableComment` / `disableDuet` / `disableStitch`	`post_info.disable_comment` / `disable_duet` / `disable_stitch`	互动开关
`thumbnailOffset`	`post_info.thumbnail_offset`	封面帧毫秒
响应 `shareId`	`data.share_id`	状态轮询句柄

TikTok Shop 挂车 ↔ 官方 Post Shoppable Video（v202607）

本平台字段	官方字段	来源
`fileId`	`video_info.file_id`	Upload Video File 返回
`title`	`video_info.title`	视频文案（官方必填）
`isAiGenerated`	`video_info.is_ai_generated`	AI 标识
`coverUri`	`video_info.cover_uri`	Upload Shoppable Photo File 返回
`coverTimestampMs`	`video_info.cover_timestamp_ms`	封面帧毫秒
`musicId`	`video_info.music_id`	Search Music 返回
`productId`	`product_link_info.product_id`	商品接口返回
`productTitle`	`product_link_info.title`	锚点文案（≤30 字符无标点 emoji）
`accountId`	官方走 access token 识别	本平台按坐席账号显式指定（creatorUserOpenId）

深入阅读

流程与示例：TikTok 发布全流程 · TikTok Shop 挂车全流程
互动与分析：TikTok 评论与私信 · TikTok 数据洞察 · 事件推送
官方硬约束速查：发布规则 · 评论规则 · 私信规则 · 数据洞察规则 · 事件推送规则

API 参考

API 参考

Playground 使用要点

端点地图

全局口径

TikTok 发布的两个版本

发布状态归一化（status ↔ 官方原值）

发布记录的 videoId vs shareId（最易踩的口径坑）

官方字段对照

深入阅读

On this page