Visla Video Generation

Version: 260811-1640

Create AI-generated videos from text scripts, web URLs, documents (PPT/PDF), or AI-generated visuals (AIGC) using Visla's OpenAPI. AIGC generates original storyboard images and motion videos for each scene with AI instead of matching stock footage.

Before You Start

Credentials (NEVER output API keys/secrets in responses):

IMPORTANT: Never output API keys/secrets in responses.

1. Check if ~/.config/visla/.credentials exists (do NOT read it yet).
2. If the file exists, use a choice-based confirmation to ask the user: "Found saved credentials. Allow reading ~/.config/visla/.credentials?" Options: Allow / No
3. If the user selects Allow: proceed with the command.
4. If the user selects No, or the file does not exist: Ask the user to provide credentials via one of:
   • Environment variables (VISLA_API_KEY, VISLA_API_SECRET)
   • CLI arguments (--key, --secret)
   • Direct input of API key and secret
5. If provided credentials fail with VISLA_CLI_ERROR_CODE=missing_credentials or VISLA_CLI_ERROR_CODE=auth_failed, ask the user to re-enter valid credentials.

Only process local files (scripts/docs) explicitly provided by the user, and remind users to avoid uploading sensitive data.

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

Script: scripts/visla_cli.py — pure Python standard library (no third-party dependencies, no pip install). Runs out-of-the-box on macOS, Linux, and Windows with Python 3.7+.

Platform Execution

The CLI is a single cross-platform Python script.

Python command differs by platform — the interpreter is launched differently:

Platform	Command
macOS / Linux	python3
Windows	python (or py -3 if python is not on PATH)

On Windows, python3 usually does not exist — always use python (or py -3). All examples below use python3; substitute python on Windows. When unsure, detect first: python3 --version 2>/dev/null || python --version.

macOS / Linux:

# With user consent, you may source ~/.config/visla/.credentials
export VISLA_API_KEY="your_key"
export VISLA_API_SECRET="your_secret"
python3 scripts/visla_cli.py <command>
# Or, credentials are auto-detected from ~/.config/visla/.credentials (with user consent):
python3 scripts/visla_cli.py <command>

Windows (PowerShell/CMD):

$env:VISLA_API_KEY = "your_key"
$env:VISLA_API_SECRET = "your_secret"
python scripts/visla_cli.py <command>

Windows notes:

• For multi-line or complex scripts, use stdin with - (recommended, no temp files):

  @"
  Scene 1: ...
  Scene 2: ...
  "@ | python scripts/visla_cli.py script -
  

• Credentials:
  • The CLI auto-detects ~/.config/visla/.credentials when present.
  • On Windows the default path is typically: %USERPROFILE%\.config\visla\.credentials.

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 idea <text-or-@file>	Create video from an idea
/visla visual <file> [file ...]	Create video from visual resources (images/videos), supports multiple files
/visla speech <file> [file ...]	Create video from speech (audio/video file), supports multiple files
/visla aigc-styles	List available AIGC visual styles
/visla aigc <script-or-@file>	Create AIGC video with AI-generated visuals (storyboard images + motion videos)
/visla aigc-status <projectUuid>	Show per-scene AIGC status (storyboard + motion video progress)
/visla aigc-image <projectUuid>	Generate/regenerate storyboard images for scenes
/visla aigc-motion <projectUuid>	Generate/regenerate motion videos for scenes
/visla account	Show account info and credit balance
/visla avatar	List available AI avatars
/visla voice	List available AI voices

Important: For avatar and voice commands:

• Run the full CLI command (python3 scripts/visla_cli.py avatar or python3 scripts/visla_cli.py voice).
• You may filter the output before presenting to the user:
  • For avatar: remove Thumbnail: lines
  • For voice: remove URL: lines
• Categorize and format avatar results as follows:
  • Group avatars by gender category (Female, Male, Neutral, Dynamic)
  • List each avatar name with (n) where n = number of looks
  • For each look, show: Look Name (lookUuid)
  • Format: - AvatarName (n): Look1 (uuid), Look2 (uuid), ...
  • Example:

    **Female (16):**
    - Emma (5): Blue Dress (1000145), Patterned Dress (1000146), Black Blazer (1000147), Light Gray Blazer (1000148), Emerald Green Pantsuit (1000149)
    

• Categorize voice results by language/region (e.g., System, US English, Chinese, Japanese, French, etc.)
• You must NOT omit any items from the list. The user must see all available avatars/voices, even if the list is long.
• Agents must use the exact ID from the listing when configuring videos.

Optional Parameters

Parameter	Description
-c, --config <file>	Path to JSON config file with video options
--avatar <id>	Avatar ID to use for the video (get list from avatar command)
--voice <id>	Voice ID to use for the video (get list from voice command)

visual command specific

Parameter	Description
--script, -s <text>	Script or description text (or @filename)
--style <style>	Video style: montage, storytelling (default), explainer

speech command specific

Parameter	Description
--function <func>	Speech to video function: SPEECH_TO_VIDEO_SUMMARY or SPEECH_TO_VIDEO_FULL_LENGTH

aigc command specific

Parameter	Description
--style <style>	AIGC visual style (run aigc-styles to list; e.g. cinematic, photorealistic, anime, flat_vector). Omit to let AI pick.
--auto-motion	Automatically generate motion videos after storyboards (default)
--no-auto-motion	Stop after storyboard images; review, then run aigc-motion
--to-clip	Create and auto-export to a clip in a single step
--webpage <url>	Add a webpage URL as reference material (repeatable)
--doc <file>	Add a PDF/PPT as reference material (repeatable)
--media <file>	Add an image/video/audio as reference material (repeatable)

aigc-image / aigc-motion command specific

Parameter	Description
--scene <id>	Scene ID (repeatable, required; get IDs from aigc-status)
--prompt <text>	Override the prompt for the selected scene(s)
--aspect-ratio <r>	landscape / portrait / square
--ref <url|id>	Reference image: a URL or an asset entity ID (repeatable, up to 3)
--force	Force regeneration (aigc-image: override scenes that already have a motion video; aigc-motion: overwrite existing motion videos)
--mode <m>	(aigc-motion) prompt_to_video / first_frame_to_video / first_and_last_frame_to_video / ingredients_to_video. Must match the number of --ref images.
--audio / --no-audio	(aigc-motion) Enable/disable generated audio
--model <model>	(aigc-motion) Generation model (default: veo_3.1)

All other options (aspect_ratio, pace, burn_subtitles, footage_options, bgm_options, etc.) can be set in the config file.

Cleanup: After video creation completes, delete the config file unless it's intended for reuse.

Config File Format (JSON)

All video options can be stored in a JSON config file (nested structure matches API request body):

{
  "video_title": "My Video",
  "video_description": "Video description",
  "project_function": "SPEECH_TO_VIDEO_SUMMARY",
  "script_text_mode": "ai_rewrite",
  "doc_usage": "page_by_page_walkthrough",
  "speaker_notes_verbatim": false,
  "target_video": {
    "aspect_ratio": "16:9",
    "video_pace": "fast",
    "burn_subtitles": false,
    "video_duration_in_seconds": 60
  },
  "avatar_options": {
    "use_avatar": false,
    "look_id": 12345,
    "avatar_layout": "smart_composition",
    "enable_auto_wallpaper": true,
    "enable_in_preview": true
  },
  "voice_options": {
    "use_voice": false,
    "voice_id": 1
  },
  "footage_options": {
    "enable_footage": true,
    "use_free_stocks": true,
    "use_premium_stocks": true,
    "use_premium_stocks_getty": true,
    "use_private_stocks": true,
    "private_stock_ids": 123456
  },
  "bgm_options": {
    "enable_bgm": true,
    "use_free_stocks": true,
    "use_premium_stocks": true
  }
}

Note: avatar_options.avatar_layout accepts only: host_only, host_pip, smart_composition.

CLI arguments (avatar, voice) override config file values.

Source of truth for the exact CLI surface: run 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, doc, idea, visual, and speech 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

AIGC Video (AI-Generated Visuals)

The aigc command uses the AIGC pipeline: instead of matching your script to stock footage, Visla generates original visuals for each scene — a storyboard image first, then an animated motion video clip. Browse visual styles first with aigc-styles. (AIGC generation is credit- and time-heavier than stock-footage creation.)

Two control modes, set by --auto-motion / --no-auto-motion:

• Automatic (default) — storyboard images and motion videos are generated end-to-end, then the video is auto-exported. One-shot, like the other commands: /visla aigc "Scene 1: ..." --style cinematic
• Manual (--no-auto-motion) — generates storyboard images only, then reports each scene's image and the project UUID. Review the frames, optionally regenerate any you dislike, then generate motion videos yourself: /visla aigc "Scene 1: ..." --style anime --no-auto-motion → /visla aigc-status <uuid> → /visla aigc-motion <uuid> --scene <id>

Add --to-clip to create and auto-export to a clip in a single step (the clip is populated when the pipeline finishes).

Scene-level operations

Use these after an AIGC project exists (the project UUID is printed by aigc):

• aigc-status <projectUuid> — per-scene status: storyboard + motion video progress, image/video links, and scene IDs.
• aigc-image <projectUuid> --scene <id> [--scene ...] — generate/regenerate storyboard images. Pass --force to regenerate scenes that already have a motion video.
• aigc-motion <projectUuid> --scene <id> [--scene ...] — generate/regenerate motion videos. Choose --mode to match the number of reference images (prompt_to_video=0, first_frame_to_video=1, first_and_last_frame_to_video=2). Use --force to overwrite existing motion videos.

Scene IDs come from the aigc-status output. Both endpoints pre-check credits and reject early if the workspace balance is insufficient.

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. AIGC videos (storyboard images plus motion videos) are heavier — allow up to ~30-45 minutes in the worst case. Set the task/command timeout to >= 30 minutes for stock-footage videos and >= 45 minutes for AIGC (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 (e.g. aigc-status <projectUuid>).

Examples

/visla script @myscript.txt
/visla script "Scene 1: ..."
/visla url https://blog.example.com/article
/visla doc presentation.pptx
/visla idea "Create a video about machine learning"
/visla idea @my_idea.txt
/visla visual image.jpg
/visla visual photo1.jpg photo2.jpg photo3.jpg
/visla visual image.jpg --script "Description of the images..."
/visla visual image.jpg --style montage
/visla speech interview.m4a
/visla speech podcast.mp3 audio1.mp3 audio2.mp3
/visla speech podcast.mp3 --function SPEECH_TO_VIDEO_SUMMARY

# AIGC: AI-generated visuals (browse styles first)
/visla aigc-styles
/visla aigc "Scene 1: A robot waving hello." --style flat_vector
/visla aigc @script.txt --style cinematic --to-clip

# AIGC manual mode: storyboards first, review, then motion videos
/visla aigc "Scene 1: ..." --style anime --no-auto-motion
/visla aigc-status 1536918152879824988
/visla aigc-image 1536918152879824988 --scene 1536919353067339776 --prompt "Brighter lighting"
/visla aigc-motion 1536918152879824988 --scene 1536919353067339776 --scene 1536919353067339777

/visla account
/visla avatar
/visla voice

# With config file
/visla script "Scene 1: Hello" -c config.json

# With avatar/voice (CLI overrides config)
/visla script "Scene 1: Hello" --avatar avatar_123 --voice voice_456

Supported Document Formats

• PowerPoint: .pptx, .ppt
• PDF: .pdf

Supported Media Formats

Visual Resources (visual command)

• Images: .jpg, .jpeg, .png, .gif, .webp
• Videos: .mp4, .mov, .avi, .mkv

Audio/Speech (speech command)

• Audio: .mp3, .wav, .m4a, .aac, .flac
• Videos: .mp4, .mov, .avi, .mkv

Output Format

• Start: Display "Visla Skill v260811-1640" when skill begins
• End: Display "Visla Skill v260811-1640 completed" when skill finishes

Security

The CLI scripts enforce the following safety measures to prevent unauthorized file access:

• Path traversal: Paths containing .. are rejected.
• System directories: Access to /etc/, /proc/, /sys/, /dev/, /run/, /var/log/ (and Windows equivalents) is denied.
• Text file extension restriction: The @file syntax in script, idea, and visual --script commands only accepts .txt, .md, .srt, .vtt, .csv files.
• Document/media file validation: The doc, visual, and speech commands validate file extensions against supported formats before upload.
• Credentials: The Python CLI auto-detects ~/.config/visla/.credentials only. No arbitrary credential file paths are accepted.
• User consent: The agent must ask for user consent before accessing local files, as specified in the "Before You Start" section.