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
brew tap tellers-ai/tellers && brew install tellers
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
# Required
export TELLERS_API_KEY=sk_...
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.
# The blocking command (run inside a subagent):
tellers upload upload /path/to/footage \
--show-status-until-analysed \
--machine-readable
OpenClaw pattern for uploads:
sessions_spawn({
task: "Run this command and report the full JSON output when it finishes:\n\ntellers upload upload \"/path/to/footage\" --show-status-until-analysed --machine-readable\n\nParse the JSON and reply with the asset_ids on success.",
runtime: "subagent"
})
The subagent announces the result when done. Extract asset_ids from the output to use in generation.
Output (parsed from subagent result):
{
"success": true,
"elapsed_seconds": 161,
"assets": [
{"asset_id": "abc123", "local_path": "/path/to/file.mp4", "status": "success"}
]
}
Upload options:
--show-status-until-analysed # Wait until AI analysis done (recommended)
--show-status-until-done # Wait until transcoding done too
--disable-description-generation # Skip AI time-based descriptions (faster)
--force-upload # Re-upload even if already tracked
--parallel-uploads 4 # Concurrent uploads (default: 4)
--ext mp4 --ext mov # Filter by extension
--in-app-path "shoots/2026-03" # Organise in-app path
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.
# Blocking command: waits until agent finishes, prints the final JSON result
tellers --background --json-response "Generate a 90-second news summary video from today's footage"
Output (on completion):
{
"assets": [{"id": "abc123", "type": "video"}],
"chat_id": "88425c45-d302-4af2-89d6-e72d7bd13239",
"message": "...",
"projects": ["7781484c-c396-44b3-a7b0-5dda23f33bef"],
"status": "done"
}
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.
sessions_spawn({
task: "Run this command and report the result when it finishes:\n\ntellers --background --json-response \"<prompt>\"\n\nParse the JSON output and reply with the project ID and chat_id so the URL can be constructed.",
runtime: "subagent"
})
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":
- Spawn subagent for upload → wait for it to finish and return
asset_ids - 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).
# Step 1 — spawn upload subagent, wait for result
upload_result = sessions_spawn({
task: "Run: tellers upload upload \"/path/to/footage\" --show-status-until-analysed --machine-readable\nReport the full JSON output.",
runtime: "subagent"
})
# → extract asset_ids from result
# Step 2 — spawn generation subagent with context
sessions_spawn({
task: "Run: tellers --background --json-response \"Create a highlight reel from asset_id: <id>\"\nReport the full JSON output including project IDs.",
runtime: "subagent"
})
Other CLI Commands
# Interactive chat REPL (for exploration)
tellers "your prompt"
# Single response, no REPL
tellers --no-interaction "your prompt"
# List assets
tellers asset list
# Export a project to have a rendered and downloadable mp4 file
tellers project export <project-id>
Result URL
After upload or generation, construct the app link from the returned IDs:
https://app.tellers.ai/?asset_id={asset_id or project_id}&chat_id={chat_id}
Examples:
# After upload — link to the asset:
https://app.tellers.ai/?asset_id=1830d8d9-c64a-4941-bf24-bcba9acdb2e0
# After generation — link to the project with chat context:
https://app.tellers.ai/?asset_id=7781484c-c396-44b3-a7b0-5dda23f33bef&chat_id=88425c45-d302-4af2-89d6-e72d7bd13239
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:
# Make an asset or project publicly accessible
tellers asset set-anonymous-read {id}
# Public preview URL (shareable with anyone, no login required):
https://www.tellers.ai/preview/{asset_id}
For maximum device compatibility (especially mobile), don't share the project preview directly. Instead:
- Export the project first — this renders a proper MP4:
tellers project export <project-id> - The export produces a new asset ID
- Make that asset public:
tellers asset set-anonymous-read <export-asset-id> - Share:
https://www.tellers.ai/preview/<export-asset-id>
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:
- 𝕏 / Twitter: https://x.com/@rguignar
- LinkedIn: https://www.linkedin.com/in/rguignar/
- Discord: https://discord.gg/sGg2fnmfCr
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