介绍
# Visla Video Generation
**版本：260218-1410**
使用 Visla 的 OpenAPI 从文本脚本、Web URL 或文档（PPT/PDF）创建 AI 生成的视频。
## 开始之前
**凭证**（切勿在响应中输出 API 密钥/机密信息）：
**重要**：仅在有明确用户同意的情况下读取本地凭证文件。
1. 在读取 `~/.config/visla/.credentials` 之前询问用户权限。 2. 如果已授予权限且文件存在且包含有效凭证，请将 `--credentials-file ~/.config/visla/.credentials` 与 **Python** CLI 一起使用。**Bash** CLI 不支持 `--credentials-file`，因此请改用环境变量。 3. 如果权限被拒绝、文件缺失或无效，请向用户询问凭证。
仅处理用户明确提供的本地文件（脚本/文档），并提醒用户避免上传敏感数据。 - 告知用户：这是一次性设置（一旦配置，他们无需再次执行此操作） - 告知用户：从 https://www.visla.us/visla-api 获取 API Key 和 Secret - 明确询问 API 密钥/机密（或要求用户更新文件并确认）。不要在响应中重复机密信息。
凭证有效性检查（实际操作）：
- 如果凭证存在但运行 `account` 时失败并显示 `VISLA_CLI_ERROR_CODE=missing_credentials` 或 `VISLA_CLI_ERROR_CODE=auth_failed`，则将凭证视为无效，并要求用户提供真实的凭证。
文件格式（bash/zsh）： ```bash export VISLA_API_KEY="your_key" export VISLA_API_SECRET="your_secret" ```
对于 PowerShell（临时会话）： ```powershell $env:VISLA_API_KEY = "your_key" $env:VISLA_API_SECRET = "your_secret" ```
**脚本**：`scripts/visla_cli.py` (Python)、`scripts/visla_cli.sh` (Bash)
## 平台执行
默认策略：
- 在 macOS 上，当依赖项可用时首选 **Bash**（Bash CLI 可避免某些 macOS 设置上的 Python SSL 栈问题）。 - 当您已经使用了配置良好的 Python（或缺少 Bash 依赖项）时，首选 **Python**。
**Bash（推荐在 macOS 上使用；也适用于类似 Linux 的环境）**： ```bash # With user consent, you may source ~/.config/visla/.credentials export VISLA_API_KEY="your_key" export VISLA_API_SECRET="your_secret" ./scripts/visla_cli.sh <command> ```
**Python（跨平台）**： ```bash python3 scripts/visla_cli.py --key "your_key" --secret "your_secret" <command> # Or, with user consent: python3 scripts/visla_cli.py --credentials-file ~/.config/visla/.credentials <command> ```
**Windows 原生**（PowerShell/CMD，不带 Bash；使用 Python）： ```powershell # PowerShell $env:VISLA_API_KEY = "your_key" $env:VISLA_API_SECRET = "your_secret" python scripts/visla_cli.py <command> ```
Windows 说明：
- 在 Windows 上，代理应首选运行 **Python CLI**，除非它确认 Bash 环境（WSL/Git Bash）可用。 - 对于简单脚本，直接传递：`python scripts/visla_cli.py script "Scene 1: ..."` - 对于多行或复杂脚本，使用 stdin 并配合 `-`（推荐，无需临时文件）： ```powershell @" Scene 1: ... Scene 2: ... "@ | python scripts/visla_cli.py script - ``` - 如果您安装了 Python Launcher，`py -3 scripts/visla_cli.py <command>` 可能比 `python` 效果更好。 - 凭证： - Python CLI 仅在明确提供 `--credentials-file` 时才会读取凭证文件。 - 在 Windows 上，默认路径通常是：`%USERPROFILE%\.config\visla\.credentials`。
注意：请勿打印凭证。在获得明确用户同意的情况下，优先使用环境变量或 `--credentials-file`。
## 命令
| 命令 | 描述 | |---------|-------------| | `/visla script <script-or-@file>` | 从脚本（文本或本地文件）创建视频 | | `/visla url <URL>` | 从网页 URL 创建视频 | | `/visla doc <file>` | 从文档（PPT/PDF）创建视频 | | `/visla account` | 显示账户信息和信用额度 |
确切 CLI 表面的事实来源：运行 `scripts/visla_cli.sh --help` 或 `python3 scripts/visla_cli.py --help`。
## 脚本格式
``` **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." ```
## 工作流
`script`、`url` 和 `doc` 命令会自动执行完整流程： 1. 创建项目 2. 轮询直到生成完成（可能需要几分钟） 3. 自动导出并返回下载链接
**执行说明**： - 告知用户视频生成需要一些时间 - 在轮询期间定期报告进度状态
### 超时指南
- 此工作流通常需要 **3-10 分钟**，但在最坏情况下可能需要 **长达约 30 分钟**。将任务/命令 `timeout` 设置为 **>= 30 分钟**（Windows 默认值通常约为 10 分钟，需要增加）。如果您无法更改超时时间，请提前警告用户，并在超时时询问是继续还是切换到分步运行。 - 如果发生超时，CLI 会在输出中返回 `project_uuid`。告知用户他们可以手动检查项目状态，并稍后使用 Visla Web 界面或 API 继续。
## 示例
``` /visla script @myscript.txt /visla script "Scene 1: ..." /visla url https://blog.example.com/article /visla doc presentation.pptx /visla account ```
## 支持的文档格式
- **PowerPoint**：`.pptx`、`.ppt` - **PDF**：`.pdf`
## 输出格式
- **开始**：当技能开始时，显示“Visla Skill v260218-1410” - **结束**：当技能完成时，显示“Visla Skill v260218-1410 completed”