linkfox-echotik-get-video-download-url

EchoTik TikTok 视频下载

本技能将介绍如何将 TikTok 视频 URL 解析为直接下载和播放链接，帮助卖家保存网红或推广视频素材，以便离线分析或重复使用。

核心概念

此工具接收一个 TikTok 视频 URL，并将其解析为直接媒体地址：无水印下载 URL（首选，可获得干净素材）、带水印下载 URL、播放 URL，以及封面图片（静态和动态）。例如，卖家可以归档通过 EchoTik 商品视频工具找到的高表现推广视频，或重复使用创作者的片段，而无需重新录制。

必需输入：必须提供 url。支持以下两种 URL 格式：

• 短链接：https://vt.tiktok.com/xxxxxx
• 完整链接：https://www.tiktok.com/@user/video/1234567890

下载 URL 的条件：并非所有视频都会返回可下载地址。仅当源视频允许下载时，才会返回 noWatermarkDownloadUrl 和 downloadUrl；对于某些受地区、隐私或可用性限制的视频，这两个字段都不会返回，只会返回 playUrl 和封面图片。提供下载链接前，务必先检查字段是否存在；如果缺少下载字段，则使用 playUrl 播放视频。

URL 有效期：返回的下载和播放地址可能会随时间失效。解析后请尽快使用；如果链接失效，请重新解析。

参数指南

参数	类型	必填	描述	默认值
url	string	是	TikTok 视频 URL（短链接 vt.tiktok.com/xxx 或完整链接 tiktok.com/@user/video/xxx）。最大长度为 1000	-

调用方式

• API 端点：POST /echotik/getVideoDownloadUrl（完整参数/响应/错误码见 references/api.md）
• Python 脚本：python scripts/echotik_get_video_download_url.py '<JSON 参数>' [--inline]
• 成本约束：本工具会消耗算力；同一会话同一参数组合默认只调用一次，脚本带 24h 本地缓存。失败/空结果不得自动换关键词、翻页或改邮编连续试探；需要继续检索时先向用户说明会产生额外消耗。

输出策略（脚本默认行为）：

• 始终将完整响应写入 <cwd>/linkfox/<YYYY-MM-DD>/<session>/data/linkfox-echotik-get-video-download-url-<timestamp>.json（<cwd> 为脚本执行时的工作目录，在 Claude Code 里即当前项目目录；<session> 取自环境变量 SESSION_ID，按用户任务自动聚合；禁止写入 /tmp，当前目录不可写则报错）
• 响应体 ≤ 8 KB：落盘后将完整 JSON 打印到 stdout
• 响应体 > 8 KB：落盘后，stdout 只输出摘要（顶层字段、常见计数如 total/costToken、最大列表字段的长度 + 前 3 条样本）
• 添加 --inline 可强制将完整内容打印到 stdout（同样会落盘）

读取数据的建议：先查看摘要，判断是否足够；需要具体字段时，优先使用 jq或ConvertFrom-Json 从保存的 json 文件中按需提取，避免将整份 JSON 纳入上下文。

解决认证和算力问题

发生以下异常情况时，采用 references/onboarding.md 引导解决问题：

异常情况

• 未配置 API Key：环境变量未配置 LINKFOX_AGENT_API_KEY，也未配置 LINKFOXAGENT_API_KEY。
• 响应 401 或 402 状态码
• 响应提示算力或余额不足：消息含"算力余额不足/计费不足/余额不足/quota exceeded/insufficient balance/套餐到期/需充值/请充值"，或类似含义的内容。

使用示例

1. 解析 TikTok 视频完整链接

{
  "url": "https://www.tiktok.com/@user/video/1234567890"
}

2. 解析 TikTok 短链接

{
  "url": "https://vt.tiktok.com/Z123abc/"
}

展示规则

1. 优先展示无水印链接：存在 noWatermarkDownloadUrl 时，将其作为主要下载选项展示，因为卖家通常需要干净素材
2. 提供带水印版本：存在 downloadUrl（带水印）时也一并列出，以便用户需要原始品牌标识时使用
3. 处理缺失的下载 URL：若 noWatermarkDownloadUrl 和 downloadUrl 均不存在（某些视频中很常见），不要编造下载链接；应告知用户视频没有直接下载地址，并提供 playUrl 用于播放或预览
4. 提供播放和封面：提及用于快速预览的 playUrl，以及用于缩略图的 coverUrl / dynamicCoverUrl
5. 有效期提示：提醒用户解析得到的 URL 可能会失效，应尽快下载
6. 仅展示数据：清晰展示解析得到的地址，不要对视频的使用方式提供主观建议
7. 错误处理：解析失败时，根据 errcode/errmsg 说明原因——400 表示缺少或无效的 url，10000 表示该链接不是有效/可访问的 TikTok 视频；建议检查 URL 格式

用户表达与场景快速参考

适用场景

用户表达	场景
“下载这个 TikTok 视频” / “保存这个 TikTok 视频片段”	将视频 URL 解析为下载链接
“获取这个 TikTok 视频的无水印版本”	优先使用 noWatermarkDownloadUrl
“我想保存这位网红的推广视频”	解析并存档创作者的视频
“给我这个 TikTok 视频的可播放链接”	返回 playUrl
“获取这个 TikTok 视频的封面/缩略图”	返回 coverUrl / dynamicCoverUrl

不适用场景

• 列出与 TikTok 商品相关的推广视频（改用 linkfox-echotik-product-video — 它需要 productId，而不是视频 URL）
• 搜索 TikTok 商品（改用 linkfox-echotik-product-search）
• TikTok 新品排行榜（改用 linkfox-echotik-new-product-rank）
• TikTok 直播数据
• 视频编辑或内容创作建议
• 下载非 TikTok 平台的视频

边界判断

当用户提到“TikTok 视频”时，判断他们是否已有想要下载的特定视频 URL（此技能），还是想要发现与商品关联的视频（商品视频技能）。如果用户提供 tiktok.com 或 vt.tiktok.com 链接，并要求保存/下载/提取，则适用此技能。如果用户提到商品 ID，并询问“哪些视频推广了这个商品”，则改用 linkfox-echotik-product-video。

算力消耗规则

消耗 5 算力。

用户会因算力消耗而支付费用。请充分评估：当需要高频调用本技能，或用户对算力消耗量预期不足时，务必提醒用户，由用户决定是否继续。

反馈：

在以下任一情况出现时，通过 Feedback API 自动检测并报告反馈：

1. 此技能描述的功能或用途与实际行为不符
2. 技能结果与用户意图不符
3. 用户表达对本技能的不满或赞赏
4. 你认为有任何可改进之处

按照 references/api.md 中的说明调用反馈 API。不要打断用户的流程。

---

如需了解更多高品质、专业的跨境电商技能，请访问 LinkFox Skills。