free-short-video 5.1.7 → 5.2.1

package/README.md

@@ -20,6 +20,8 @@ free-short-video
 [![License](https://img.shields.io/github/license/lcy362/agnes-video-generator)](https://github.com/lcy362/agnes-video-generator/blob/main/LICENSE)
 [![Python](https://img.shields.io/badge/python-3.10+-blue)](https://www.python.org/)
 [![Website](https://img.shields.io/badge/website-video.lichuanyang.top-8A2BE2)](https://video.lichuanyang.top)
+[![Docker Hub](https://img.shields.io/docker/pulls/lcy362/free-short-video?label=docker%20pulls)](https://hub.docker.com/r/lcy362/free-short-video)
+[![npm](https://img.shields.io/npm/v/free-short-video?label=npm)](https://www.npmjs.com/package/free-short-video)
 
 > **Completely free AI video generator** — Built on Agnes AI's free models, no subscription, no high-end GPU, no usage limits. Type in a text idea and automatically generate multi-scene AI videos with narration and subtitles. Supports text-to-video, image-to-video, keyframes animation, digital anchor, and more. All AI compute runs in the cloud — a regular laptop is all you need. **[Try it online →](https://video.lichuanyang.top)**
 
@@ -31,6 +33,13 @@ free-short-video
 
 > **🖥️ Try it now — no install needed:** Visit [video.lichuanyang.top](https://video.lichuanyang.top) and experience **Simple Video** mode directly in your browser. Just enter a prompt and generate a free AI video instantly.
 
+## 🚀 Two Ways to Use — Both Completely Free
+
+| Project | Run Where | Features | Link |
+|---------|-----------|----------|------|
+| **[Agnes Video Generator](https://github.com/lcy362/agnes-video-generator)** (this project) | **Download & run locally** | **More powerful** — TTS narration, auto subtitles, digital anchor, image-to-video, keyframes animation, manuscript-to-video, checkpoint resume & more | [GitHub](https://github.com/lcy362/agnes-video-generator) |
+| **[FreeShortVideoStudio](https://github.com/lcy362/free-short-video-studio)** | **Fully online, in the browser** | Lightweight, zero install — no setup at all, **features under active construction** | [video.lichuanyang.top/studio](https://video.lichuanyang.top/studio) · [GitHub](https://github.com/lcy362/free-short-video-studio) |
+
 ## ⭐ Support & Contribute
 
 If you find this project useful, please **star the [GitHub repository](https://github.com/lcy362/agnes-video-generator)** ⭐ — your support helps more people discover this free and open-source AI video generator.
@@ -96,487 +105,14 @@ To be honest, Agnes's video model isn't perfect yet. The generated frames are so
 | **Watermark** | No watermark | Built-in watermark | Built-in watermark | C2PA metadata | Built-in watermark |
 | **Usage Limit** | No limit (16 req/min rate limit) | Billed by compute | Billed by generation | Billed by generation | Billed by generation |
 
-## ✨ Core Features
-
-### 🎬 Multiple Creation Modes
-
-| Mode | Description | Best For |
-|------|-------------|----------|
-| **Simple Video** | Single prompt → single AI video. Full control over all parameters (generation mode, duration, resolution, seed, negative prompt). Also supports image-to-video and keyframes mode. | Quick single-clip AI video |
-| **Creative Video** | Full AI pipeline: idea → story → script → character reference → multi-scene video → narration → subtitles → final output. 10-step pipeline, fully automated. | Storytelling, creative videos |
-| **Manuscript Video** | Paste a long article or script → auto-split by reading duration → per-segment AI video → unified TTS narration + subtitle overlay → final output. 5-step pipeline. | Explainers, course content, vlogs |
-| **Digital Anchor** | AI-generated digital anchor (or upload custom image) → dynamic anchor clip → TTS narration → subtitle positioning → looped concatenation. Optional reference image for appearance consistency. | Virtual anchors, product presentations, news broadcasts |
-
-### 🆓 Completely Free AI Model Chain
-
-All core AI capabilities are **completely free** — no trial period, no watermarks, no token limits:
-
-| Capability | Model | Cost |
-|-----------|-------|------|
-| Text / Script Generation | `agnes-2.0-flash` | Free |
-| Image Generation | `agnes-image-2.1-flash` | Free |
-| Video Generation | `agnes-video-v2.0` | Free |
-| Text-to-Speech Narration | Edge TTS (Microsoft) | Free, no extra API key needed |
-
-All AI API calls share a global token bucket rate limiter (16 requests/min), with automatic retries and exponential backoff to ensure stable operation.
-
-### 🎙️ AI Narration & Smart Subtitles
-
-Both Creative Video and Manuscript Video support:
-
-- **Free TTS narration**: Based on Microsoft Edge TTS, offering 4 Chinese voice roles (gentle female, steady male, lively female, young male) with adjustable speech rate (-30% to +30%)
-- **Word-level fine-grained subtitles**: SRT subtitles generated from TTS word-level timestamps, one entry every 2-3 seconds, with precise audio-video sync
-- **Multi-line auto-wrapping**: Long subtitle text is intelligently split into two lines, preferring punctuation break points to prevent screen overflow
-- **Fully configurable subtitle style**: Font, color, size, position (top/bottom), stroke, and semi-transparent background
-- **Audio-video sync strategy**: All video clips are concatenated first, then audio and subtitles are overlaid as a whole, avoiding cumulative errors from per-segment overlay. TTS output is automatically amplified 2.5× to compensate for Edge TTS's low default volume
-
-### 🎨 Flexible Creative Controls
-
-- **Custom reference images** — Upload character or scene reference images to maintain visual consistency across scenes
-- **Custom end frames** — Specify end frame images per scene for precise visual transition control
-- **Image-to-image end frames** — Auto-generate scene end frames via img2img from your reference image
-- **Three video chaining modes** — `keyframes` (first+last frame interpolation, recommended) / `ti2vid` (inter-scene transition frames) / `none` (independent scenes)
-- **Multiple resolutions** — Portrait 9:16 (768×1152), Landscape 16:9 (1152×768), Square 1:1 (1024×1024)
-- **Flexible duration** — Custom scene duration
-- **Smart manuscript splitting** — Splits by period/question mark/exclamation mark, greedily merges into 5-12 second segments based on reading speed (~4 chars/sec), preserves long sentences, auto-merges short sentences forward
-
-### 🔧 Production-Grade Reliability
-
-- **Checkpoint resume** — Automatically resumes from the last checkpoint after interruption; state is persisted after each step, no duplicate API calls
-- **Task management** — Create, view, resume, and stop tasks from the Web UI
-- **Real-time progress** — WebSocket pushes per-step generation progress (step name, status, percentage, current/total)
-- **Built-in CJK fonts** — Project ships with Chinese fonts, no garbled characters in subtitle rendering
-
-### 🤖 AI Agent Friendly
-
-Designed specifically for AI coding assistants (Claude, Cursor, QoderWork, etc.), with a complete `AGENTS.md` deployment guide. AI Agents can automatically:
-
-- Check environment (Python 3.10+, ffmpeg)
-- Install dependencies and start the server
-- Configure API key
-- Run 4-layer deployment verification (connectivity → static analysis → endpoint testing → subtitle feature)
-- Execute 10-scenario regression test suite
-
-### 🌐 Multilingual Web UI
-
-One-click launch, operate entirely in the browser. Interface available in **13 languages**: 中文, English, Deutsch, Français, Nederlands, Español, Português, Italiano, Русский, 日本語, 한국어, Bahasa Melayu, Bahasa Indonesia.
-
-## 🚀 Quick Start
-
-### Prerequisites
-
-- Python 3.10+
-- ffmpeg — required only for **manual setup** (Option A); the Docker (Option B) and npm (Option C) options bundle ffmpeg automatically, so no system ffmpeg install is needed there.
-
-That's it. No GPU, no large RAM, a regular laptop is all you need.
-
-### Option A: Manual Setup
-
-**Step 1 — Clone & Launch**
-
-```bash
-git clone https://github.com/lcy362/agnes-video-generator.git
-cd agnes-video-generator
-./start.sh
-```
-
-The script automatically creates a virtual environment, installs dependencies, and opens `http://localhost:8765` in your browser. You can also start manually:
-
-```bash
-python3 -m venv .venv
-.venv/bin/pip install -r requirements.txt
-.venv/bin/python server.py
-```
-
-**Step 2 — Configure API Key**
-
-Get a free API key from [Agnes AI](https://platform.agnes-ai.com), then choose one of two ways:
-
-```bash
-# Way 1: Environment variable
-export AGNES_API_KEY="your-api-key"
-
-# Way 2: Via API (same as entering it in the Web UI)
-curl -X POST http://localhost:8765/api/config \
-  -H "Content-Type: application/json" \
-  -d '{"api_key": "your-api-key"}'
-```
-
-**Step 3 — Create Your First Video**
-
-Open `http://localhost:8765`, choose a video mode (Simple / Creative / Manuscript / Anchor), enter your idea, and click "Start Generating".
-
-### Option B: Docker (No Python/FFmpeg Required)
-
-Pre-built multi-arch images (`linux/amd64`, `linux/arm64`) are published to both **GitHub Container Registry (GHCR)** and **Docker Hub** on every release.
-
-**Pull & Run**
-
-```bash
-# GHCR
-docker run -d -p 8765:8765 \
-  -e AGNES_API_KEY=<your-key> \
-  -v ~/agnes-data/working:/app/.working_dir \
-  -v ~/agnes-data/config:/app/.agnes_config \
-  ghcr.io/lcy362/free-short-video:latest
-
-# Docker Hub
-docker run -d -p 8765:8765 \
-  -e AGNES_API_KEY=<your-key> \
-  -v ~/agnes-data/working:/app/.working_dir \
-  -v ~/agnes-data/config:/app/.agnes_config \
-  lcy362/free-short-video:latest
-```
-
-Then open `http://localhost:8765`.
-
-**Data Persistence:** The app writes videos, uploads, and settings inside the container (`/app/.working_dir`, `/app/.agnes_config`). Mount them to your host so outputs survive container recreation and are accessible from your local filesystem. Your generated videos will be at `~/agnes-data/working/` on your machine.
-
-Or use `docker compose` with the included `docker-compose.yml`:
-
-```bash
-git clone https://github.com/lcy362/agnes-video-generator.git
-cd agnes-video-generator
-AGNES_API_KEY=<your-key> docker compose up -d
-```
-
-### Option C: npm (One Command)
-
-If you have **Node.js 18+** and **Python 3.10+** installed, the whole service ships as an npm package — no cloning, no manual venv:
-
-```bash
-# Run directly without installing
-npx free-short-video
-
-# Or install globally, then run
-npm install -g free-short-video
-free-short-video          # short alias: fsv
-```
-
-On first run the launcher automatically creates a local virtual environment, installs Python dependencies, wires up a bundled `ffmpeg` (via `imageio-ffmpeg`, so no system ffmpeg needed), starts the server on `http://localhost:8765`, and opens your browser. Pass your key through the environment or set it later in the Web UI:
-
-```bash
-AGNES_API_KEY=<your-key> npx free-short-video
-```
-
-Options: `--port <n>`, `--host <h>` (use `0.0.0.0` for LAN access), `--no-open`.
-
-#### ffmpeg: bundled by default, or install your own
-
-With the npm package you normally **don't need to install ffmpeg yourself** — the launcher (`bin/cli.js`) automatically installs `imageio-ffmpeg` (a static ffmpeg binary, now an explicit dependency in `requirements.txt`) into the local venv and prepends its directory to `PATH`, so every `ffmpeg` call inside the Python service resolves to the bundled binary. This works out of the box on macOS, Linux, and Windows.
-
-**If you prefer to install ffmpeg on your system** (recommended for production / maximum stability — your system ffmpeg takes precedence over the bundled one because it appears earlier on `PATH`):
-
-```bash
-# macOS
-brew install ffmpeg
-
-# Ubuntu / Debian
-sudo apt update && sudo apt install ffmpeg
-
-# CentOS / RHEL (requires RPM Fusion)
-sudo dnf install ffmpeg
-
-# Windows (Chocolatey)
-choco install ffmpeg
-
-# Windows (Scoop)
-scoop install ffmpeg
-```
-
-Or download a build from <https://ffmpeg.org/download.html> and add it to your `PATH`. Verify with:
-
-```bash
-ffmpeg -version
-```
-
-**Risks if you do NOT install a system ffmpeg (i.e. rely solely on the bundled `imageio-ffmpeg`):**
-
-- **Platform / architecture support** — `imageio-ffmpeg` ships pre-built binaries only for common platforms (macOS x86_64/arm64, Linux x86_64/arm64, Windows x64). On niche or very old architectures a matching wheel may not exist, and the bundled binary would be missing.
-- **Single source of truth** — all ffmpeg capability comes from that one static binary. If its install/extract fails (disk permissions, corruption), the failure only surfaces **when you generate a video**, not at server startup — the error is a low-level `FileNotFoundError: 'ffmpeg'`, which is harder to diagnose than a startup check.
-- **Pinned version** — the bundled ffmpeg is locked to whatever version `imageio-ffmpeg` ships (e.g. ffmpeg 7.1); you can't easily upgrade it on your own.
-- **Mitigation** — for production or stability-critical use, install a system ffmpeg as shown above; the bundled one then acts only as a fallback.
-
-### Option D: AI Agent Assisted Setup
-
-This project is designed for AI coding assistants. First, download the code and prepare your API key:
-
-```bash
-git clone https://github.com/lcy362/agnes-video-generator.git
-cd agnes-video-generator
-```
-
-Then tell your agent:
-
-> "Read the AGENTS.md in this project, install dependencies, configure the API key `<your-key>`, and start the server."
-
-The agent will read `AGENTS.md` (a comprehensive deployment guide) and handle: environment checks (Python 3.10+, ffmpeg), `pip install`, server launch, and API key configuration. After startup, you can also ask the agent to verify the deployment:
-
-> "Run the deployment verification checks."
-
-The agent will execute the 4-layer checklist from `AGENTS.md` (connectivity → static analysis → endpoint testing → subtitle feature) and report results.
-
-## 📖 Usage
-
-### 1. Configure API Key
-
-Enter your free [Agnes AI](https://platform.agnes-ai.com) API key at the top of the page and save it. Or set it via environment variable:
-
-```bash
-export AGNES_API_KEY="your-api-key"
-```
-
-### 2. Choose a Video Mode
-
-#### Simple Video
-
-Quick single-clip generation with full parameter control:
-
-| Field | Description |
-|-------|-------------|
-| Prompt | Describe the AI video scene in natural language |
-| Generation Mode | Text-to-Video / Image-to-Video / Text+Image / Keyframes |
-| Resolution | Portrait 9:16 / Landscape 16:9 / Square 1:1 |
-| Duration | 5s / 10s / 15s / 18s / 20s |
-| Reference Image | Optional upload for image-to-video modes |
-| End Frame Image | Optional end frame for keyframes mode |
-
-#### Creative Video
-
-AI-driven multi-scene storytelling:
-
-| Field | Description | Required |
-|-------|-------------|----------|
-| Idea | Describe your AI video concept | Yes |
-| User Requirements | Scene count, duration, and other constraints | - |
-| Visual Style | Cinematic realism, anime, cyberpunk, etc. | - |
-| Chaining Mode | keyframes (recommended) / ti2vid / none | - |
-| Narration | Enable/disable TTS narration, choose voice and speed | - |
-| Subtitle Style | Font, color, size, position, stroke, background | - |
-| Reference Image | Optional character reference for visual consistency | - |
-| End Frames | Custom or auto-generated per-scene end frames | - |
-
-#### Manuscript Video
-
-Long-form text to narrated video:
-
-| Field | Description | Required |
-|-------|-------------|----------|
-| Manuscript Text | Paste your full article, script, or narration | Yes |
-| Resolution | Portrait / Landscape / Square | - |
-| Narration | Voice role and speech rate | - |
-| Subtitle Style | Full subtitle customization | - |
-
-> **Note**: Segment duration is auto-calculated based on text length (~4 chars/sec, 5–12s per segment) — no manual setting needed.
-
-#### Digital Anchor
-
-| Field | Description | Required |
-|-------|-------------|----------|
-| Anchor Script | Enter the text the anchor will say | Yes |
-| Anchor Image | AI-generated or upload custom reference image | - |
-| Resolution | Portrait / Landscape / Square | - |
-| Narration | Voice role and speech rate | - |
-| Subtitle Style | Full subtitle customization | - |
-
-### 3. Click "Start Generating"
-
-The progress panel shows real-time generation status for each step. For Creative Video: Init → Image Analysis → Story → Character Reference → Script → Narration → End Frame Prompts → End Frame Generation → Video Generation → Audio & Subtitles → Concatenation.
-
-### 4. Checkpoint Resume & Task Management
-
-If the server is interrupted, restart it and find the incomplete task in the "Task List" tab. Click "Resume" to continue from the last checkpoint. Running tasks can also be stopped and resumed later.
-
-## 🏗️ Project Structure
-
-```
-agnes-video-generator/
-├── start.sh                          # One-click launch script
-├── requirements.txt                  # Python dependencies
-├── Dockerfile                        # Multi-arch Docker image (Python 3.11 + ffmpeg via imageio)
-├── docker-compose.yml                # Docker Compose with persisted volumes
-├── docker-run.sh                     # One-command Docker launch (wrapper with bind mounts)
-├── server.py                         # FastAPI server (REST + WebSocket)
-├── static/
-│   └── index.html                    # Frontend SPA — 5 task tabs, 13 languages (Tailwind CSS)
-├── core/
-│   ├── config.py                     # API key, font resolution, default configs
-│   ├── screenwriter.py               # Screenwriter Agent (LLM-powered story/script/narration)
-│   ├── task_manager.py               # Task state persistence & checkpoint resume
-│   ├── api/
-│   │   ├── agnes_chat.py             # LLM Chat API (agnes-2.0-flash)
-│   │   ├── agnes_image.py            # Image generation API (agnes-image-2.1-flash / 2.0-flash)
-│   │   ├── agnes_video.py            # Video generation API (agnes-video-v2.0)
-│   │   └── rate_limiter.py           # Global token bucket rate limiter (16 requests/min)
-│   ├── audio/
-│   │   ├── tts.py                    # Edge TTS engine + silent fallback engine
-│   │   └── subtitle.py               # SRT generation (fine-grained word-level) + overlay
-│   ├── compositor/
-│   │   ├── concatenator.py           # Video concatenation + audio/subtitle overlay
-│   │   └── processor.py              # Video resize, frame extraction, freeze, silence gen
-│   └── pipelines/
-│       ├── simple_video.py           # Pipeline: Simple Video
-│       ├── creative_video.py         # Pipeline: Creative Video (10-step)
-│       ├── manuscript_video.py       # Pipeline: Manuscript Video (5-step)
-│       └── anchor_video.py           # Pipeline: Digital Anchor
-├── models/
-│   └── task.py                       # Data models (5 task types, configs, requests)
-├── resource/
-│   └── fonts/                        # Built-in CJK fonts for subtitle rendering
-├── utils/
-│   ├── image.py                      # Image download / base64 conversion
-│   └── video.py                      # Video download
-├── scripts/
-│   └── regression_runner.py          # 10-scenario regression test suite
-└── docs/
-    ├── regression_test_plan.md       # Regression test plan
-    ├── plans-v1.0/                   # v1.0 design & planning docs
-    ├── plans-v2.0/                   # v2.0 review & optimization docs
-    └── plans-v3.0/                   # v3.0 feature planning docs
-```
-
-## 🔧 Tech Stack
-
-| Layer | Choice | Notes |
-|-------|--------|-------|
-| Backend | Python FastAPI | Async + WebSocket |
-| Frontend | HTML/CSS/JS + Tailwind CSS CDN | Zero build steps, single-file SPA |
-| LLM | Agnes Chat (`agnes-2.0-flash`) | Free — story, script, narration generation |
-| Image AI | `agnes-image-2.1-flash` (t2i) / `agnes-image-2.0-flash` (i2i) | Free — reference images, end frames, standalone image generation |
-| Video AI | `agnes-video-v2.0` | Free — text-to-video, image-to-video, keyframes |
-| TTS | Edge TTS (Microsoft) | Free — 4 Chinese voices, no extra API key needed |
-| Subtitles | moviepy + srt | Fine-grained word-level SRT, multi-line wrapping |
-| Video Processing | moviepy + ffmpeg | Concatenation, subtitle overlay, audio mixing |
-
-## 🎬 Three AI Video Chaining Modes
-
-| Mode | How It Works | Best For |
-|------|-------------|----------|
-| **keyframes** | Specify first + last frame per scene; server auto-interpolates transitions | Smooth transitions (recommended) |
-| **ti2vid** | Last frame of previous scene → img2img transition → first frame of next scene | Visual continuity between scenes |
-| **none** | All scenes share the same reference image, independent of each other | Fast output, independent scenes |
-
-## 📋 API Endpoints
-
-| Method | Path | Description |
-|--------|------|-------------|
-| GET | `/` | Serve Web UI |
-| GET | `/api/config` | Get API key (masked) |
-| POST | `/api/config` | Save API key |
-| DELETE | `/api/config` | Delete API key |
-| GET | `/api/voices` | List available TTS voices |
-| POST | `/api/image/generate` | Image generation |
-| GET | `/api/image/{task_id}` | Query image task status |
-| POST | `/api/tasks/simple` | Create simple video task |
-| POST | `/api/tasks/creative` | Create creative video task |
-| POST | `/api/tasks/manuscript` | Create manuscript video task |
-| POST | `/api/tasks/anchor` | Create digital anchor task |
-| POST | `/api/tasks` | Generic task creation (backward-compatible) |
-| GET | `/api/tasks` | List all tasks (with type badges) |
-| GET | `/api/tasks/{id}` | Get task details |
-| POST | `/api/tasks/{id}/resume` | Resume an interrupted task |
-| POST | `/api/tasks/{id}/stop` | Stop a running task |
-| GET | `/api/video/{id}` | Download/stream final video |
-| WS | `/ws/{id}` | WebSocket real-time progress |
-
-## ⚠️ Important Notes
-
-This project is in early stage — corner cases may not be fully handled. Recommended workflow:
-
-1. Fill in your idea on the page and submit an AI video task
-2. Watch the **console logs** (the terminal running `server.py`) and be patient
-3. All key operations are logged for easy debugging
-
-### Log Reference
-
-All important operations are logged to the server console:
-
-| Prefix | Module |
-|--------|--------|
-| `[Startup]` | Server startup, stale task reset |
-| `[WS]` | WebSocket connect/disconnect |
-| `[Resume]` / `[Stop]` | Task resume/stop |
-| `[Pipeline]` / `[Simple]` / `[Manuscript]` | Pipeline step execution |
-| `[TTS]` / `[Subtitle]` | Audio and subtitle generation |
-| `[Compositor]` | Video concatenation and processing |
-| `[AgnesImage]` / `[AgnesVideo]` / `[AgnesChat]` | AI API calls |
-| `[RateLimiter]` | Global rate limiter |
-| `[TaskManager]` | Task state persistence |
-| `[Screenwriter]` | Screenwriter Agent |
-
-### Output Directory
-
-All AI video task artifacts are stored under `.working_dir/{timestamp}_{task_id}/`:
-
-```
-.working_dir/{timestamp}_{task_id}/
-├── task_state.json              # Task state (required for checkpoint resume)
-├── final_video.mp4              # Final video with narration + subtitles
-├── story.txt                    # AI-generated story (creative mode)
-├── script.json                  # Scene script (JSON format)
-├── narration.mp3                # Combined TTS narration audio
-├── narration.srt                # Combined subtitle file
-├── scene_0/
-│   ├── video.mp4                # Scene 0 AI video
-│   ├── end_frame.png            # Scene 0 end frame
-│   └── task.json                # Video generation task ID
-├── scene_1/
-│   └── ...
-└── scene_2/
-    └── ...
-```
-
-## 🙏 Acknowledgments
-
-This project is built upon the following open-source projects:
-
-- [ViMax](https://github.com/HKUDS/ViMax) — AI video generation framework by HKU Data Science Lab
-- [vimax-agnes](https://github.com/easyeye163/vimax-agnes) — Agnes AI adaptation based on ViMax
-
-Special thanks to [Agnes AI](https://platform.agnes-ai.com) for providing **completely free**, high-quality AI model APIs (text, image, and video generation) — this project runs at absolute zero cost thanks to their generosity.
-
-## 📄 License
-
-MIT
-
----
-
-## ❓ FAQ
-
-### Is Agnes Video Generator really free? Are there any hidden costs?
-
-Yes, it is **completely free**. All AI model calls (Agnes Chat, Agnes Image, Agnes Video) are free of charge with no trial period, no watermarks, and no usage limits. The only TTS integration (Microsoft Edge TTS) is also free and requires no extra API key. You only need a free API key from [Agnes AI](https://platform.agnes-ai.com) to get started.
-
-### Do I need a GPU to run this AI video generator?
-
-No. All AI compute runs in the cloud via Agnes AI's free API. You just need a regular laptop or desktop computer that can run Python 3.10+ and ffmpeg. No GPU, no high RAM, no special hardware required.
-
-### How is this different from Runway, Pika, or Sora?
-
-Unlike commercial AI video tools that charge $10–$95/month, Agnes Video Generator is completely free and open-source (MIT). It offers built-in multi-scene pipelines, AI narration, auto subtitles, and digital anchor — features that require third-party tools or manual editing elsewhere. See the [comparison table](#comparison-agnes-vs-commercial-ai-video-tools) above for details.
-
-### What video generation modes are supported?
-
-Four modes: **Simple Video** (single prompt, full parameter control), **Creative Video** (AI story → multi-scene video with narration), **Manuscript Video** (long text → auto-split → narrated video), and **Digital Anchor** (AI anchor with TTS). Additional options include text-to-video, image-to-video, keyframes animation, and image-to-image end frame generation.
-
-### Can I use my own images as references?
-
-Yes. You can upload reference images for character or scene consistency across scenes, use custom end frames for precise visual transitions, or choose img2img to auto-generate end frames from your reference. Reference images are supported in both Creative Video and Digital Anchor modes.
-
-### What languages does the UI support?
-
-The Web UI supports 13 languages: 中文, English, Deutsch, Français, Nederlands, Español, Português, Italiano, Русский, 日本語, 한국어, Bahasa Melayu, and Bahasa Indonesia. Subtitles are generated in the source text language with CJK font support built-in.
-
-### Can I run this with Docker?
-
-Yes. Pre-built images are published to both [GHCR](https://github.com/lcy362/agnes-video-generator/pkgs/container/free-short-video) and [Docker Hub](https://hub.docker.com/r/lcy362/free-short-video). Just pull the `latest` tag and run — no Python or ffmpeg installation needed. See **[Option B: Docker](#option-b-docker-no-pythonffmpeg-required)** in Quick Start for the full command and volume mount instructions.
-
-### Can I host this on my own server?
-
-Absolutely. The project is designed for self-hosting. Just clone the repo, run `./start.sh`, and the server starts on `http://localhost:8765`. No external dependencies, no cloud lock-in. See the [Quick Start](#🚀-quick-start) section above.
-
-### How do I get help or report issues?
+## 📚 Documentation
 
-Check the [GitHub Issues](https://github.com/lcy362/agnes-video-generator/issues) page for existing reports or open a new one. The project also includes a comprehensive `AGENTS.md` for AI-agent-assisted debugging. For feature requests, bug reports, or questions, the Issues page is the best place.
+- **[Features](docs/features.md)** — Creation modes, the completely free AI model chain, AI narration & smart subtitles, flexible creative controls, production-grade reliability, and the multilingual Web UI.
+- **[Getting Started](docs/getting-started.md)** — Install and deploy in 4 ways: Manual (`start.sh`), Docker, npm (`npx free-short-video`), or AI-Agent assisted.
+- **[Usage Guide](docs/usage.md)** — Configure your API key, pick a video mode, resume from checkpoints, the three chaining modes, and logs & output layout.
+- **[Architecture](docs/architecture.md)** — Project structure and tech stack.
+- **[API Reference](docs/api.md)** — Full REST + WebSocket endpoint list.
+- **[FAQ](docs/faq.md)** — Frequently asked questions.
+- **[About & License](docs/about.md)** — Acknowledgments and the MIT license.
 
 **Keywords**: free AI video generator, AI video generation tool, text to video AI, free AI video maker, AI video creator, open source video generator, Agnes AI, text-to-video, image-to-video, keyframes video, AI narration, auto subtitles, multi-scene video, zero cost AI video, no subscription AI video tool, digital anchor, self-hosted AI video generator, open source alternative to Runway

package/core/api/agnes_chat.py

@@ -17,11 +17,10 @@ import requests
 
 from core.api.error_collector import collect_error, collect_error_from_exception
 from core.api.rate_limiter import get_rate_limiter
+from core.config import get_agnes_base_url
 
 logger = logging.getLogger(__name__)
 
-BASE_URL = "https://apihub.agnes-ai.com/v1"
-
 # 重试配置
 _MAX_RETRIES = 3
 _RETRY_BASE_DELAY = 15  # 秒，指数退避基数
@@ -111,7 +110,7 @@ class AgnesChatAPI:
             try:
                 get_rate_limiter().acquire()
                 resp = requests.post(
-                    f"{BASE_URL}/chat/completions",
+                    f"{get_agnes_base_url()}/chat/completions",
                     headers=self.headers,
                     json=payload,
                     timeout=timeout,

package/core/api/agnes_image.py

@@ -12,12 +12,11 @@ import requests
 
 from core.api.error_collector import collect_error, collect_error_from_exception
 from core.api.rate_limiter import get_rate_limiter
+from core.config import get_agnes_base_url
 from utils.image import download_image
 
 logger = logging.getLogger(__name__)
 
-BASE_URL = "https://apihub.agnes-ai.com/v1"
-
 
 class ImageOutput:
     def __init__(self, fmt: str, ext: str, data: str):
@@ -83,7 +82,7 @@ class AgnesImageAPI:
         prompt: str,
         reference_image_paths: List[str] = [],
         size: Optional[str] = None,
-        max_retries: int = 3,
+        max_retries: int = 4,
         retry_base_delay: float = 20.0,
         **kwargs,
     ) -> ImageOutput:
@@ -115,11 +114,11 @@ class AgnesImageAPI:
             try:
                 # 全局限速：在发起 HTTP 请求前获取令牌
                 await asyncio.to_thread(get_rate_limiter().acquire)
-                # 动态超时：第一次 60s，后续逐步增加
-                read_timeout = 60 * (attempt + 1)
+                # 动态超时：第一次 120s，后续逐步增加（图像生成较慢，放宽读超时）
+                read_timeout = 120 * (attempt + 1)
                 resp = await asyncio.to_thread(
                     requests.post,
-                    f"{BASE_URL}/images/generations",
+                    f"{get_agnes_base_url()}/images/generations",
                     headers=self.headers,
                     json=payload,
                     timeout=(30, read_timeout),

package/core/api/agnes_models.py

@@ -8,19 +8,15 @@ import logging
 
 import requests
 
-from core.api.agnes_chat import BASE_URL
 from core.config import (
     DEFAULT_TEXT_MODEL,
     DEFAULT_IMAGE_MODEL,
     DEFAULT_VIDEO_MODEL,
+    get_agnes_base_url,
 )
 
 logger = logging.getLogger(__name__)
 
-# 带 beta 开关的模型列表端点：裸 /v1/models 会被网关过滤掉内测模型，
-# 加 ?all=true（等价 X-Beta-Access: true / ?include_beta=true）才会返回全量（含 2.5-flash）。
-MODELS_ENDPOINT = f"{BASE_URL}/models?all=true"
-
 REQUEST_TIMEOUT = 20
 
 # 分组失败时的兜底列表
@@ -56,8 +52,9 @@ def fetch_available_models(api_key: str) -> dict:
         接口失败（网络/鉴权/非 200）时返回硬编码兜底列表。
     """
     try:
+        endpoint = f"{get_agnes_base_url()}/models?all=true"
         resp = requests.get(
-            MODELS_ENDPOINT,
+            endpoint,
             headers={"Authorization": f"Bearer {api_key}"},
             timeout=REQUEST_TIMEOUT,
         )