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):

export VISLA_API_KEY="your_key"
export VISLA_API_SECRET="your_secret"

For PowerShell (temporary session):

$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):

source ~/.config/visla/.credentials
./scripts/visla_cli.sh <command>

Python (cross-platform):

python3 scripts/visla_cli.py <command>

Windows native (PowerShell/CMD without Bash; Python):

# 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):

  @"
  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

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