visla

# Visla Video Generation **Version: 260201-2257** Create AI-generated videos from text scripts, web URLs, or documents (PPT/PDF) using Visla's OpenAPI. ## Before You Start **Credentials** (NEVER output API keys/secrets in responses): **IMPORTANT**: Always try to read the credentials file before asking the user for credentials. 1. Try to read `~/.config/visla/.credentials` 2. If the file exists and contains valid credentials, use them directly (do NOT ask the user) 3. Only if the file is missing or invalid, ask the user for credentials - Tell the user: this is a one-time setup (once configured, they won't need to do this again) - Tell the user: get API Key and Secret from https://www.visla.us/visla-api - Ask for the API key/secret explicitly (or ask the user to update the file and confirm). Do not repeat the secrets back in the response. Credential validity check (practical): - If credentials exist but running `account` fails with `VISLA_CLI_ERROR_CODE=missing_credentials` or `VISLA_CLI_ERROR_CODE=auth_failed`, treat credentials as invalid and ask the user to provide real ones. File format (bash/zsh): ```bash export VISLA_API_KEY="your_key" export VISLA_API_SECRET="your_secret" ``` For PowerShell (temporary session): ```powershell $env:VISLA_API_KEY = "your_key" $env:VISLA_API_SECRET = "your_secret" ``` **Scripts**: `scripts/visla_cli.py` (Python), `scripts/visla_cli.sh` (Bash) ## Platform Execution Default strategy: - Prefer **Bash** on macOS when dependencies are available (the Bash CLI avoids Python SSL-stack issues on some macOS setups). - Prefer **Python** when you're already using a well-configured Python (or when Bash dependencies are missing). **Bash (recommended on macOS; also works on Linux-like environments)**: ```bash source ~/.config/visla/.credentials ./scripts/visla_cli.sh <command> ``` **Python (cross-platform)**: ```bash python3 scripts/visla_cli.py <command> ``` **Windows native** (PowerShell/CMD without Bash; Python): ```powershell # PowerShell $env:VISLA_API_KEY = "your_key" $env:VISLA_API_SECRET = "your_secret" python scripts/visla_cli.py <command> ``` Windows note: - The agent should prefer running the **Python CLI** on Windows unless it has verified a Bash environment (WSL/Git Bash) is available. - For simple scripts, pass directly: `python scripts/visla_cli.py script "Scene 1: ..."` - For multi-line or complex scripts, use stdin with `-` (recommended, no temp files): ```powershell @" Scene 1: ... Scene 2: ... "@ | python scripts/visla_cli.py script - ``` - If you have Python Launcher installed, `py -3 scripts/visla_cli.py <command>` may work better than `python`. - Credentials: - The Python CLI will also try to read `~/.config/visla/.credentials` automatically if env vars are not set. - On Windows this typically maps to: `%USERPROFILE%\\.config\\visla\\.credentials`. Note: do not print credentials. Prefer reading them from `~/.config/visla/.credentials` or environment variables. ## Commands | Command | Description | |---------|-------------| | `/visla script <script-or-@file>` | Create video from a script (text or a local file) | | `/visla url <URL>` | Create video from web page URL | | `/visla doc <file>` | Create video from document (PPT/PDF) | | `/visla account` | Show account info and credit balance | Source of truth for the exact CLI surface: run `scripts/visla_cli.sh --help` or `python3 scripts/visla_cli.py --help`. ## Script Format ``` **Scene 1** (0-10 sec): **Visual:** A futuristic calendar flipping to 2025 with digital patterns. **Narrator:** "AI is evolving rapidly! Here are 3 game-changing AI trends." **Scene 2** (10-25 sec): **Visual:** Text: "Trend #1: Generative AI Everywhere." Show tools like ChatGPT. **Narrator:** "Generative AI is dominating industries—creating content and images." ``` ## Workflow The `script`, `url`, and `doc` commands execute the complete flow automatically: 1. Create project 2. Poll until generation completes (may take a few minutes) 3. Auto-export and return download link **Execution Instructions**: - Inform user that video generation takes some time - Report progress status periodically during polling ### Timeout Guidance - This workflow typically takes **3-10 minutes**, but can take **up to ~30 minutes** in the worst case. Set the task/command `timeout` to **>= 30 minutes** (Windows defaults are often ~10 minutes and need to be increased). If you cannot change the timeout, warn the user up front and, on timeout, ask whether to continue or switch to a step-by-step run. - If timeout occurs, the CLI returns `project_uuid` in the output. Inform the user they can manually check project status and continue later using the Visla web interface or API. ## Examples ``` /visla script @myscript.txt /visla script "Scene 1: ..." /visla url https://blog.example.com/article /visla doc presentation.pptx /visla account ``` ## Supported Document Formats - **PowerPoint**: `.pptx`, `.ppt` - **PDF**: `.pdf` ## Error Recovery When a command fails, enter **Autonomous Repair Mode**. The goal is to repair the bundled scripts so future runs succeed, without requiring the user to debug. Hard rules (always): - Never print or persist secrets (API key/secret). - Treat `https://www.visla.us/visla-api` as the only authoritative reference for API/auth/signing details. - Prefer continuing an existing project/clip if IDs already exist (avoid starting over). Safety constraints (cost / duplication control): - Avoid blindly retrying `create`/`export` calls. They can create duplicate projects or consume credits. - If you must retry a `create` or `export` call, do it at most **once** automatically. If it still fails, stop retrying and switch to repair/debug actions. Repair workflow: 1. Re-run once to confirm the failure mode (do not spam retries). 2. Classify the failure quickly: - auth/credits/rate-limit -> explain clearly and ask the user to fix credentials/credits; do not “fix code” - network -> surface the error; optionally retry polling/read-only calls; do not “fix code” - script logic/compatibility -> proceed with repair 3. Repair the script: - Read the failing script (`scripts/visla_cli.sh` or `scripts/visla_cli.py`) - Patch the minimal code necessary (signing, payloads, parsing, timeouts, error handling) - Keep the CLI surface unchanged (no new required arguments; do not expose advanced knobs) 4. Make the fix durable for the user: - Before overwriting, create a timestamped backup next to the script (e.g., `visla_cli.py.bak-YYYYMMDD-HHMMSS`) - Overwrite the installed script in the Skill directory (same path the agent executes from) - Backup/overwrite templates: - Bash: - `ts=$(date +%Y%m%d-%H%M%S); cp scripts/visla_cli.py scripts/visla_cli.py.bak-$ts` - `ts=$(date +%Y%m%d-%H%M%S); cp scripts/visla_cli.sh scripts/visla_cli.sh.bak-$ts` - PowerShell: - `$ts = Get-Date -Format "yyyyMMdd-HHmmss"; Copy-Item scripts\\visla_cli.py scripts\\visla_cli.py.bak-$ts` - `$ts = Get-Date -Format "yyyyMMdd-HHmmss"; Copy-Item scripts\\visla_cli.sh scripts\\visla_cli.sh.bak-$ts` 5. Verify: - Run local no-network checks (`--help`, Python syntax check) - Re-run the original command and verify it succeeds (or reaches a stable intermediate state like a known `project_uuid`) ## Output Format - **Start**: Display "Visla Skill v260131-0031" when skill begins - **End**: Display "Visla Skill v260131-0031 completed" when skill finishes