tella-cli

何时使用此技能

在需要执行以下操作时使用 tella-cli 技能：

• 列出、获取、更新或删除 Tella 工作区中的视频
• 拉取剪辑的字幕（完整或剪切版），包含逐词时间戳
• 在自定义尺寸和时间点生成视频或剪辑缩略图（支持 jpg/png/webp/gif/mp4 格式）
• 触发 1080p 或 4k 分辨率、30/60fps 的视频导出，可选内嵌字幕
• 复制视频或剪辑，可选择性裁剪
• 编辑剪辑：裁剪时间段、重新排序、移除填充词、查找静音段落
• 添加或更新视觉编辑：模糊、高亮、布局、缩放（手动或追踪模式）
• 管理播放列表并添加或移除视频
• 为视频添加工作区协作者（编辑者或查看者）
• 创建 webhook 端点，获取签名密钥，并检查最近的交付记录

功能能力

• 读取工作区中所有视频和播放列表，包括元数据、观看次数和分享链接
• 无需打开 Tella 编辑器即可推送细粒度剪辑修改（如裁剪、重排、模糊、高亮、布局、缩放）
• 拉取字幕用于下游搜索、摘要生成或无障碍处理流程
• 启动导出任务并轮询/列出 webhook 交付状态，以确认文件是否就绪
• 管理分享设置：linkScope、密码、允许嵌入的域名、搜索引擎索引
• 订阅事件（如 video.created、export.ready、transcript.ready 等），并恢复已丢失的消息

常见使用场景

• “列出我最近的 20 个 Tella 视频，并以 JSON 格式输出用于内容审计”
• “获取剪辑 X 的未剪切字幕，以便生成章节时间戳”
• “将视频 Y 导出为 4k 60fps 并内嵌字幕”
• “在该剪辑中从 4.2 秒到 7.8 秒的位置添加模糊遮盖”
• “创建名为 ‘教程’ 的播放列表，并添加这 5 个视频”
• “配置 webhook，以便在导出完成时收到通知”
• “从该剪辑中移除填充词，然后获取清理后的字幕”

安装与设置

如果未找到 tella-cli，请先安装并构建：

bun --version || curl -fsSL https://bun.sh/install | bash
npx api2cli bundle tella
npx api2cli link tella

api2cli link 会自动将 ~/.local/bin 添加到 PATH。CLI 工具将在下一条命令中可用。

程序化调用时，请始终使用 --json 参数。

使用规则

• 对于由代理驱动的调用，请始终使用 --json，以便下游步骤能够解析结果
• 当不确定参数时，运行 <resource> --help 或 <resource> <action> --help，不要猜测
• 执行破坏性操作（如 delete、remove-*）前，先通过 get/list 确认目标对象
• 大多数剪辑修改操作需要同时提供 <videoId> 和 <clipId> 作为位置参数（顺序为先 videoId 后 clipId）
• 遮罩（模糊、高亮）和缩放焦点坐标均归一化为画布的 0-1 范围
• 时间单位默认为毫秒（*-ms 标志），除非文档另有说明

认证方式

tella-cli auth set "tella_pk_xxx..."   # 从 https://www.tella.tv/settings/api-keys 获取的 API 密钥
tella-cli auth test                     # 验证密钥是否有效
tella-cli auth show                     # 显示掩码后的令牌
tella-cli auth remove                   # 删除存储的令牌

令牌存储路径为 ~/.config/tokens/tella-cli.txt（权限设为 600）。

可用资源

videos

clips

大多数剪辑相关命令需以 <videoId> <clipId> 作为位置参数。

Skill: tella-cli

Version: 0.1.0

Chunk: 2/2

命令列表

遮罩坐标（--point-*, --dim-*, --focus-*）为归一化值，范围是 0-1 的画布比例。

播放列表

Webhooks

可用事件类型包括：video.created, video.viewed, view.milestone, transcript.ready, export.ready, playlist.created, playlist.video_added。

输出格式

使用 --json 参数返回标准化的封装结构：

{ "ok": true, "data": { ... }, "meta": { "total": 42 } }

发生错误时返回：

{ "ok": false, "error": { "message": "...", "status": 401 } }

快速参考

tella-cli --help                       # 列出所有资源和全局参数
tella-cli videos --help                # 列出视频相关操作
tella-cli videos list --help           # 显示视频列表的参数
tella-cli clips add-zoom --help        # 显示 add-zoom 命令的参数

全局参数

所有命令支持以下参数：--json, --format <text|json|csv|yaml>, --verbose, --no-color, --no-header

退出码说明：

0 = 成功

1 = API 错误

2 = 使用错误