Tellers Skill
Tellers.ai is a video creation platform. The tellers CLI lets you upload media and generate AI-produced videos via a conversational agent.
Installation
1. Install the CLI
CODEBLOCK0
2. Get an API key
Go to app.tellers.ai → user menu (top right) → API keys → Create new.
Credits are required. New Google SSO users get free starter credits.
3. Configure
CODEBLOCK1
Add the export to your shell profile (~/.zshrc, ~/.bashrc) to persist it.
Workflow 1: Upload Media (non-blocking)
Always spawn an isolated subagent for uploads — they can take minutes and shouldn't block the main session.
CODEBLOCK2
OpenClaw pattern for uploads:
CODEBLOCK3
The subagent announces the result when done. Extract asset_ids from the output to use in generation.
Output (parsed from subagent result):
CODEBLOCK4
Upload options:
CODEBLOCK5
Workflow 2: Generate a Video (long-running)
Video generation runs the tellers AI agent and can take 5–20 minutes. Always run generation inside an isolated subagent — never block the main session.
CODEBLOCK6
Output (on completion):
CODEBLOCK7
Extract projects[0] as the project ID and chat_id to build the result URL.
OpenClaw pattern for generation:
Spawn an isolated subagent with the full blocking command. The subagent waits however long it takes and announces the result (preview link) when done. The main session stays free.
CODEBLOCK8
The tellers.json_result SSE event carries the final output. The --background --json-response flags extract and print it automatically.
Workflow 3: Combined Upload + Generate
Common pattern for "upload these videos and make an edit":
- 1. Spawn subagent for upload → wait for it to finish and return INLINECODE8
- Spawn a second subagent for generation with the asset context
Both steps use isolated subagents. Upload must complete before generation starts (asset needs to be processed first).
CODEBLOCK9
Other CLI Commands
CODEBLOCK10
Result URL
After upload or generation, construct the app link from the returned IDs:
CODEBLOCK11
Examples:
CODEBLOCK12
Always surface this URL to the user when a generation or upload completes.
Sharing & Public Previews
By default assets and projects are private. To share a public preview link:
CODEBLOCK13
For maximum device compatibility (especially mobile), don't share the project preview directly. Instead:
- 1. Export the project first — this renders a proper MP4: INLINECODE9
- The export produces a new asset ID
- Make that asset public: INLINECODE10
- Share: INLINECODE11
Project previews may not play on all devices; exported assets always will.
Credits & Support
Every upload, export, and generation request spends Tellers credits. To buy more, go to app.tellers.ai and click "Get more tokens".
Questions or issues:
Error Handling
- - Exit code 0 = success
- Exit code 1 = error (check stderr)
- HTTP 401 = bad/missing API key
- HTTP 402 = insufficient credits — direct user to app.tellers.ai to top up
Reference
Full API docs: https://www.tellers.ai/docs/dev/api
CLI source: https://github.com/tellers-ai/tellers-cli
OpenAPI spec: src/tellers_api/openapi.tellers_public_api.yaml in the repo
Tellers 技能
Tellers.ai 是一个视频创作平台。tellers 命令行界面允许你上传媒体文件，并通过对话式AI代理生成AI制作的视频。
安装
1. 安装命令行界面
bash
brew tap tellers-ai/tellers && brew install tellers
2. 获取API密钥
前往 app.tellers.ai → 用户菜单（右上角）→ API密钥 → 创建新密钥。
需要积分。新的Google SSO用户可获得免费入门积分。
3. 配置
bash
必需
export TELLERS
APIKEY=sk_...
将该导出命令添加到你的shell配置文件（~/.zshrc、~/.bashrc）中以使其持久化。
工作流程1：上传媒体（非阻塞）
始终为上传操作生成一个独立的子代理——上传可能需要几分钟，不应阻塞主会话。
bash
阻塞命令（在子代理内运行）：
tellers upload upload /path/to/footage \
--show-status-until-analysed \
--machine-readable
上传的OpenClaw模式：
sessions_spawn({
task: 运行此命令，并在完成后报告完整的JSON输出：\n\ntellers upload upload \/path/to/footage\ --show-status-until-analysed --machine-readable\n\n解析JSON，并在成功时回复asset_ids。,
runtime: subagent
})
子代理在完成时宣布结果。从输出中提取asset_ids以用于生成。
输出（从子代理结果解析）：
json
{
success: true,
elapsed_seconds: 161,
assets: [
{assetid: abc123, localpath: /path/to/file.mp4, status: success}
]
}
上传选项：
--show-status-until-analysed # 等待AI分析完成（推荐）
--show-status-until-done # 也等待转码完成
--disable-description-generation # 跳过AI时间描述（更快）
--force-upload # 即使已跟踪也重新上传
--parallel-uploads 4 # 并发上传数（默认：4）
--ext mp4 --ext mov # 按扩展名筛选
--in-app-path shoots/2026-03 # 在应用内组织路径
工作流程2：生成视频（长时间运行）
视频生成运行tellers AI代理，可能需要5-20分钟。始终在独立的子代理内运行生成——切勿阻塞主会话。
bash
阻塞命令：等待代理完成，打印最终JSON结果
tellers --background --json-response 根据今天的素材生成一个90秒的新闻摘要视频
输出（完成时）：
json
{
assets: [{id: abc123, type: video}],
chat_id: 88425c45-d302-4af2-89d6-e72d7bd13239,
message: ...,
projects: [7781484c-c396-44b3-a7b0-5dda23f33bef],
status: done
}
提取projects[0]作为项目ID，chat_id用于构建结果URL。
生成的OpenClaw模式：
生成一个独立的子代理，运行完整的阻塞命令。子代理等待所需时间，并在完成时宣布结果（预览链接）。主会话保持空闲。
sessions_spawn({
task: 运行此命令，并在完成后报告结果：\n\ntellers --background --json-response \<提示>\\n\n解析JSON输出，并回复项目ID和chat_id，以便构建URL。,
runtime: subagent
})
tellers.json_result SSE事件携带最终输出。--background --json-response标志会自动提取并打印它。
工作流程3：组合上传 + 生成
上传这些视频并制作剪辑的常见模式：
- 1. 生成上传子代理 → 等待其完成并返回asset_ids
- 使用素材上下文生成第二个生成子代理
两个步骤都使用独立的子代理。上传必须在生成开始之前完成（素材需要先处理）。
步骤1 — 生成上传子代理，等待结果
upload
result = sessionsspawn({
task: 运行：tellers upload upload \/path/to/footage\ --show-status-until-analysed --machine-readable\n报告完整的JSON输出。,
runtime: subagent
})
→ 从结果中提取asset_ids
步骤2 — 使用上下文生成生成子代理
sessions_spawn({
task: 运行：tellers --background --json-response \从asset_id创建精彩集锦：
\\n报告包含项目ID的完整JSON输出。,
runtime: subagent
})
其他CLI命令
bash
交互式聊天REPL（用于探索）
tellers 你的提示
单次响应，无REPL
tellers --no-interaction 你的提示
列出素材
tellers asset list
导出项目以生成可渲染和可下载的mp4文件
tellers project export
结果URL
上传或生成后，从返回的ID构建应用链接：
https://app.tellers.ai/?assetid={assetid 或 projectid}&chatid={chat_id}
示例：
上传后 — 链接到素材：
https://app.tellers.ai/?asset_id=1830d8d9-c64a-4941-bf24-bcba9acdb2e0
生成后 — 链接到带有聊天上下文的项目：
https://app.tellers.ai/?assetid=7781484c-c396-44b3-a7b0-5dda23f33bef&chatid=88425c45-d302-4af2-89d6-e72d7bd13239
当生成或上传完成时，始终向用户展示此URL。
分享与公开预览
默认情况下，素材和项目是私有的。要分享公开预览链接：
bash
使素材或项目可公开访问
tellers asset set-anonymous-read {id}
公开预览URL（可分享给任何人，无需登录）：
https://www.tellers.ai/preview/{asset_id}
为获得最大设备兼容性（尤其是移动设备），不要直接分享项目预览。而是：
- 1. 先导出项目——这会渲染一个合适的MP4：tellers project export
- 导出会产生一个新的素材ID
- 使该素材公开：tellers asset set-anonymous-read
- 分享：https://www.tellers.ai/preview/
项目预览可能无法在所有设备上播放；导出的素材始终可以。
积分与支持
每次上传、导出和生成请求都会消耗Tellers积分。要购买更多积分，请前往 app.tellers.ai 并点击 获取更多代币。
问题或疑问：
错误处理
- - 退出代码0 = 成功
- 退出代码1 = 错误（检查stderr）
- HTTP 401 = API密钥错误/缺失
- HTTP 402 = 积分不足——引导用户前往app.tellers.ai充值
参考
完整API文档：https://www.tellers.ai/docs/dev/api
CLI源代码：https://github.com/tellers-ai/tellers-cli
OpenAPI规范：仓库中的src/tellersapi/openapi.tellerspublic_api.yaml
