free-short-video 5.1.7 → 5.2.0

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)**
 
@@ -96,487 +98,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
+## 📚 Documentation
 
-### 🎬 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?
-
-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):
@@ -119,7 +118,7 @@ class AgnesImageAPI:
                 read_timeout = 60 * (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,
         )

package/core/api/agnes_video.py

@@ -13,13 +13,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, get_agnes_api_root
 from utils.video import download_video
 
 logger = logging.getLogger(__name__)
 
-BASE_URL = "https://apihub.agnes-ai.com/v1"
-API_ROOT = "https://apihub.agnes-ai.com"
-
 DURATION_PRESETS = {
     5: (121, 24),
     10: (241, 24),
@@ -82,7 +80,7 @@ class AgnesVideoAPI:
             _URL_CACHE_MAX_AGE = 3600  # 1 小时
             if os.path.exists(url_file):
                 try:
-                    with open(url_file, "r") as f:
+                    with open(url_file, "r", encoding="utf-8") as f:
                         cache_data = json.loads(f.read())
                     cached_url = cache_data.get("url", "")
                     cached_ts = cache_data.get("ts", 0)
@@ -107,7 +105,7 @@ class AgnesVideoAPI:
                 try:
                     cache_data = {"url": url, "ts": time.time()}
                     tmp_file = url_file + ".tmp"
-                    with open(tmp_file, "w") as f:
+                    with open(tmp_file, "w", encoding="utf-8") as f:
                         json.dump(cache_data, f)
                         f.flush()
                         os.fsync(f.fileno())
@@ -140,7 +138,7 @@ class AgnesVideoAPI:
                 await asyncio.to_thread(get_rate_limiter().acquire)
                 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, 120),
@@ -213,7 +211,7 @@ class AgnesVideoAPI:
         start_time = asyncio.get_event_loop().time()
         curl_cmd = (
             f'curl -s -H "Authorization: Bearer $AGNES_API_KEY" '
-            f'"{API_ROOT}/agnesapi?video_id={video_id}"'
+            f'"{get_agnes_api_root()}/agnesapi?video_id={video_id}"'
         )
         while True:
             # M2: 每次轮询前检查停止信号
@@ -244,7 +242,7 @@ class AgnesVideoAPI:
                 resp = await asyncio.wait_for(
                     asyncio.to_thread(
                         requests.get,
-                        f"{API_ROOT}/agnesapi?video_id={video_id}",
+                        f"{get_agnes_api_root()}/agnesapi?video_id={video_id}",
                         headers=self.headers,
                         timeout=15,
                     ),
@@ -319,7 +317,7 @@ class AgnesVideoAPI:
                 resp = await asyncio.wait_for(
                     asyncio.to_thread(
                         requests.post,
-                        f"{BASE_URL}/videos",
+                        f"{get_agnes_base_url()}/videos",
                         headers=self.headers,
                         json=payload,
                         timeout=(15, 60),

package/core/compositor/concatenator.py

@@ -534,7 +534,7 @@ class VideoConcatenator:
         # Step 3: Build concat file list for ffmpeg
         loop_dir = os.path.dirname(output_path)
         concat_file = os.path.join(loop_dir, "_anchor_concat.txt")
-        with open(concat_file, "w") as f:
+        with open(concat_file, "w", encoding="utf-8") as f:
             for _ in range(n):
                 f.write(f"file '{clip_path}'\n")
 

package/core/config.py

@@ -472,3 +472,50 @@ def set_selected_models(text: str = None, image: str = None, video: str = None)
     config["models"] = m
     save_config(config)
     return get_selected_models()
+
+
+# ═══════════════════════════════════════════════════
+# Agnes API 域名配置（v6.0）
+# ═══════════════════════════════════════════════════
+
+# 可用域名映射
+AGNES_DOMAIN_MAP = {
+    "com": "https://apihub.agnes-ai.com",
+    "cn": "https://apihub.agnes-ai.cn",
+}
+
+_DEFAULT_DOMAIN = "com"
+
+
+def get_agnes_domain() -> str:
+    """返回当前配置的域名后缀。
+
+    Returns:
+        "com" 或 "cn"
+    """
+    config = load_config()
+    return config.get("agnes_domain", _DEFAULT_DOMAIN)
+
+
+def set_agnes_domain(domain: str):
+    """设置 Agnes API 域名后缀。
+
+    Args:
+        domain: "com" 或 "cn"
+    """
+    config = load_config()
+    config["agnes_domain"] = domain
+    save_config(config)
+
+
+def get_agnes_base_url() -> str:
+    """返回基于当前域名配置的完整 API Base URL（含 /v1 后缀）。"""
+    domain = get_agnes_domain()
+    root = AGNES_DOMAIN_MAP.get(domain, AGNES_DOMAIN_MAP[_DEFAULT_DOMAIN])
+    return f"{root}/v1"
+
+
+def get_agnes_api_root() -> str:
+    """返回基于当前域名配置的 API Root URL（不含 /v1 后缀）。"""
+    domain = get_agnes_domain()
+    return AGNES_DOMAIN_MAP.get(domain, AGNES_DOMAIN_MAP[_DEFAULT_DOMAIN])

package/core/pipelines/__init__.py

@@ -393,10 +393,10 @@ class BasePipeline(ABC):
         """持久化任务元数据（video_id 等）到 sub_dir/task.json + curl.sh。"""
         os.makedirs(sub_dir, exist_ok=True)
         task_file = os.path.join(sub_dir, "task.json")
-        with open(task_file, "w") as f:
+        with open(task_file, "w", encoding="utf-8") as f:
             json.dump(data, f, indent=2)
         curl_file = os.path.join(sub_dir, "curl.sh")
-        with open(curl_file, "w") as f:
+        with open(curl_file, "w", encoding="utf-8") as f:
             f.write(self._make_curl(data.get("video_id", "")) + "\n")
 
     def _load_task_json(self, sub_dir: str) -> Optional[str]:
@@ -404,7 +404,7 @@ class BasePipeline(ABC):
         task_file = os.path.join(sub_dir, "task.json")
         if os.path.exists(task_file):
             try:
-                with open(task_file, "r") as f:
+                with open(task_file, "r", encoding="utf-8") as f:
                     data = json.load(f)
                 return data.get("video_id") or data.get("task_id")
             except Exception as e:

package/core/pipelines/creative_video.py

@@ -233,7 +233,7 @@ class CreativeVideoPipeline(MultiScenePipeline):
         if self._state.step_image_analysis == StepStatus.COMPLETED:
             analysis_file = self._state.image_analysis_file
             if os.path.exists(analysis_file):
-                with open(analysis_file, "r") as f:
+                with open(analysis_file, "r", encoding="utf-8") as f:
                     content = f.read()
                 # 检测之前分析失败留下的错误文本，强制重新分析
                 if "(分析失败" in content:
@@ -273,7 +273,7 @@ class CreativeVideoPipeline(MultiScenePipeline):
         )
 
         analysis_file = os.path.join(self.working_dir, "image_analysis.txt")
-        with open(analysis_file, "w") as f:
+        with open(analysis_file, "w", encoding="utf-8") as f:
             f.write(image_context)
 
         self._state.step_image_analysis = StepStatus.COMPLETED
@@ -411,7 +411,7 @@ class CreativeVideoPipeline(MultiScenePipeline):
             story_path = self._state.story_file
             if os.path.exists(story_path):
                 logger.info("[Pipeline] Step story: SKIP (already completed, file exists)")
-                with open(story_path, "r") as f:
+                with open(story_path, "r", encoding="utf-8") as f:
                     return f.read()
             logger.warning("[Pipeline] Step story: marked completed but file missing, re-running")
 
@@ -428,7 +428,7 @@ class CreativeVideoPipeline(MultiScenePipeline):
         )
 
         story_path = os.path.join(self.working_dir, "story.txt")
-        with open(story_path, "w") as f:
+        with open(story_path, "w", encoding="utf-8") as f:
             f.write(story)
 
         self._state.step_story = StepStatus.COMPLETED
@@ -481,7 +481,7 @@ class CreativeVideoPipeline(MultiScenePipeline):
         if os.path.exists(ref_img_path) and os.path.exists(ref_prompt_path):
             self._state.step_character_ref = StepStatus.COMPLETED
             self._state.character_ref_file = ref_img_path
-            with open(ref_prompt_path, "r") as f:
+            with open(ref_prompt_path, "r", encoding="utf-8") as f:
                 self._state.character_ref_prompt = f.read()
             self.task_manager.update_state(
                 step_character_ref=StepStatus.COMPLETED,
@@ -494,7 +494,7 @@ class CreativeVideoPipeline(MultiScenePipeline):
         char_prompt = await asyncio.to_thread(
             self.screenwriter.extract_character_description, story, self._state.style
         )
-        with open(ref_prompt_path, "w") as f:
+        with open(ref_prompt_path, "w", encoding="utf-8") as f:
             f.write(char_prompt)
 
         await self._emit("character_ref", "running", "正在生成角色参考图 (t2i)...", 0.12)
@@ -532,7 +532,7 @@ class CreativeVideoPipeline(MultiScenePipeline):
             script_path = self._state.script_file
             if os.path.exists(script_path):
                 logger.info("[Pipeline] Step script: SKIP (already completed, file exists)")
-                with open(script_path, "r") as f:
+                with open(script_path, "r", encoding="utf-8") as f:
                     scenes = json.load(f)
                 if self._state.scene_count == len(scenes):
                     return scenes
@@ -550,7 +550,7 @@ class CreativeVideoPipeline(MultiScenePipeline):
         )
 
         script_path = os.path.join(self.working_dir, "script.json")
-        with open(script_path, "w") as f:
+        with open(script_path, "w", encoding="utf-8") as f:
             json.dump(scenes, f, ensure_ascii=False, indent=2)
 
         self._state.scene_count = len(scenes)
@@ -620,7 +620,7 @@ class CreativeVideoPipeline(MultiScenePipeline):
             prompts_path = self._state.end_frame_prompts_file
             if os.path.exists(prompts_path):
                 logger.info("[Pipeline] Step end_frame_prompts: SKIP (already completed, file exists)")
-                with open(prompts_path, "r") as f:
+                with open(prompts_path, "r", encoding="utf-8") as f:
                     return json.load(f)
             logger.warning("[Pipeline] Step end_frame_prompts: marked completed but file missing, re-running")
 
@@ -638,7 +638,7 @@ class CreativeVideoPipeline(MultiScenePipeline):
         )
 
         prompts_path = os.path.join(self.working_dir, "end_frame_prompts.json")
-        with open(prompts_path, "w") as f:
+        with open(prompts_path, "w", encoding="utf-8") as f:
             json.dump(end_frame_prompts, f, ensure_ascii=False, indent=2)
 
         self._state.step_end_frame_prompts = StepStatus.COMPLETED
@@ -921,10 +921,10 @@ class CreativeVideoPipeline(MultiScenePipeline):
             video_id: Remote video task identifier.
         """
         task_file = os.path.join(scene_dir, "task.json")
-        with open(task_file, "w") as f:
+        with open(task_file, "w", encoding="utf-8") as f:
             json.dump({"video_id": video_id}, f, indent=2)
         curl_file = os.path.join(scene_dir, "curl.sh")
-        with open(curl_file, "w") as f:
+        with open(curl_file, "w", encoding="utf-8") as f:
             f.write(self._make_curl(video_id) + "\n")
 
     def _load_scene_task(self, scene_dir: str) -> Optional[str]:
@@ -939,7 +939,7 @@ class CreativeVideoPipeline(MultiScenePipeline):
         task_file = os.path.join(scene_dir, "task.json")
         if os.path.exists(task_file):
             try:
-                with open(task_file, "r") as f:
+                with open(task_file, "r", encoding="utf-8") as f:
                     data = json.load(f)
                 return data.get("video_id") or data.get("task_id")
             except Exception as e:

package/core/task_manager.py

@@ -77,7 +77,7 @@ class TaskManager:
             return None
 
         try:
-            with open(self._task_file, "r") as f:
+            with open(self._task_file, "r", encoding="utf-8") as f:
                 data = json.load(f)
 
             # v2.0：通过 parse_task_state 工厂函数反序列化
@@ -195,7 +195,7 @@ class TaskManager:
             task_file = os.path.join(working_dir, name, "task_state.json")
             if os.path.exists(task_file):
                 try:
-                    with open(task_file, "r") as f:
+                    with open(task_file, "r", encoding="utf-8") as f:
                         data = json.load(f)
                     tasks.append({
                         "task_id": data.get("task_id", name),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "free-short-video",
-  "version": "5.1.7",
+  "version": "5.2.0",
   "description": "Free AI short-video generator — run the full free-short-video service locally with one command. Text-to-video, image generation, Edge-TTS narration, subtitles, and compositing, all free.",
   "bin": {
     "free-short-video": "bin/cli.js",

package/server.py

@@ -34,7 +34,7 @@ from fastapi import FastAPI, UploadFile, File, Form, HTTPException
 from fastapi.staticfiles import StaticFiles
 from fastapi.responses import FileResponse, JSONResponse
 
-from core.config import get_api_key, set_api_key, delete_api_key, get_api_key_source, get_working_dir, DURATION_FRAME_MAP, get_workspaces, add_workspace, remove_workspace, set_active_workspace, get_active_workspace, REGRESSION_WORKING_DIR_ENV, get_watermark_config, set_watermark_config, WATERMARK_PROMO_TEXT_ZH, WATERMARK_PROMO_TEXT_EN, get_selected_models, set_selected_models
+from core.config import get_api_key, set_api_key, delete_api_key, get_api_key_source, get_working_dir, DURATION_FRAME_MAP, get_workspaces, add_workspace, remove_workspace, set_active_workspace, get_active_workspace, REGRESSION_WORKING_DIR_ENV, get_watermark_config, set_watermark_config, WATERMARK_PROMO_TEXT_ZH, WATERMARK_PROMO_TEXT_EN, get_selected_models, set_selected_models, get_agnes_domain, set_agnes_domain, AGNES_DOMAIN_MAP
 from core.path_security import safe_join, safe_workspace_path, UnsafePathError
 from core.audio.voices import (
     get_voice_catalog,
@@ -369,6 +369,8 @@ async def get_config():
         "watermark_promo_zh": WATERMARK_PROMO_TEXT_ZH,
         "watermark_promo_en": WATERMARK_PROMO_TEXT_EN,
         "models": get_selected_models(),
+        "agnes_domain": get_agnes_domain(),
+        "agnes_domains": list(AGNES_DOMAIN_MAP.keys()),
     }
     return data
 
@@ -461,6 +463,28 @@ async def save_watermark_config(enabled: bool = Form(False)):
     return {"ok": True, "enabled": enabled}
 
 
+# ═══════════════════════════════════════════════════
+# 域名配置（v6.0）
+# ═══════════════════════════════════════════════════
+
+
+@app.post("/api/config/domain")
+async def save_agnes_domain(domain: str = Form(...)):
+    """设置 Agnes API 域名后缀。
+
+    Args:
+        domain: "com" 或 "cn"
+    """
+    domain = domain.strip().lower()
+    if domain not in AGNES_DOMAIN_MAP:
+        raise HTTPException(
+            status_code=422,
+            detail=f"域名后缀必须为 {list(AGNES_DOMAIN_MAP.keys())} 之一",
+        )
+    set_agnes_domain(domain)
+    return {"ok": True, "agnes_domain": domain}
+
+
 # ═══════════════════════════════════════════════════
 # 工作目录管理（多工作目录，同时仅一个 active）
 # ═══════════════════════════════════════════════════

package/static/index.html

@@ -405,6 +405,50 @@
     </div>
   </div>
 
+  <!-- 域名配置（v6.0） -->
+  <div id="domain-section" class="glass-card rounded-2xl mb-6 overflow-hidden transition-all duration-300">
+    <!-- Compact bar (shown when collapsed) -->
+    <div id="domain-compact" class="hidden flex items-center justify-between px-6 py-3 cursor-pointer hover:bg-white/[0.02] transition" onclick="toggleConfigPanel('domain')" role="button" tabindex="0" aria-expanded="false" aria-label="展开域名配置" onkeydown="if(event.key==='Enter')toggleConfigPanel('domain')">
+      <div class="flex items-center gap-3">
+        <span class="text-sm">🌐</span>
+        <span id="domain-compact-text" class="text-sm text-gray-400"></span>
+      </div>
+      <span id="domain-arrow" class="text-gray-600 text-xs transition-transform duration-300">▶</span>
+    </div>
+    <!-- Expanded body -->
+    <div id="domain-body" class="p-6 pt-4">
+      <div class="flex items-center justify-between mb-3">
+        <h2 class="text-lg font-semibold text-blue-300" data-i18n="domainTitle">Agnes 域名配置</h2>
+        <div class="flex items-center gap-2">
+          <span id="domain-status" class="text-xs px-2 py-1 rounded-full bg-gray-800 text-gray-400">apihub.agnes-ai.com</span>
+          <button onclick="toggleConfigPanel('domain')" class="text-xs text-gray-500 hover:text-gray-300 transition px-2 py-1 rounded" title="收起" aria-label="收起域名配置">▲</button>
+        </div>
+      </div>
+      <p class="text-xs text-gray-500 mb-4" data-i18n="domainHint">选择 Agnes API 的接入域名。在中国大陆推荐使用 .cn 域名，以获得更稳定流畅的访问体验。</p>
+      <div class="space-y-3">
+        <label class="flex items-center gap-3 glass-input rounded-lg px-4 py-3 cursor-pointer hover:border-blue-500/40 transition">
+          <input type="radio" name="agnes-domain" value="com" class="accent-blue-500 w-4 h-4 cursor-pointer">
+          <div>
+            <span class="text-sm text-gray-200 font-medium">apihub.agnes-ai.com</span>
+            <span class="text-xs text-gray-500 ml-2" data-i18n="domainComLabel">国际域名</span>
+          </div>
+        </label>
+        <label class="flex items-center gap-3 glass-input rounded-lg px-4 py-3 cursor-pointer hover:border-blue-500/40 transition">
+          <input type="radio" name="agnes-domain" value="cn" class="accent-blue-500 w-4 h-4 cursor-pointer">
+          <div>
+            <span class="text-sm text-gray-200 font-medium">apihub.agnes-ai.cn</span>
+            <span class="text-xs text-gray-500 ml-2" data-i18n="domainCnLabel">中国大陆推荐</span>
+          </div>
+        </label>
+      </div>
+      <div class="flex gap-3 mt-4">
+        <button id="domain-save" class="px-5 py-2.5 bg-blue-600 hover:bg-blue-500 rounded-lg text-sm font-medium transition shadow-lg shadow-blue-600/20" data-i18n="save">保存</button>
+        <span id="domain-save-status" class="self-center text-xs text-green-400 hidden" data-i18n="domainSaved">已保存</span>
+        <span id="domain-save-error" class="self-center text-xs text-red-400 hidden"></span>
+      </div>
+    </div>
+  </div>
+
   <!-- 工作目录 -->
   <div id="workspace-section" class="glass-card rounded-2xl mb-6 overflow-hidden transition-all duration-300">
     <!-- Compact bar (shown when collapsed) -->
@@ -1603,6 +1647,12 @@ const T = {
     connLostMsg: '与服务端的实时连接已断开。服务可能仍在后台运行。可到任务列表查看状态并续传。',
     gotoList: '前往任务列表',     reconnecting: '实时连接断开，正在重试...',
     ttAnchor: '数字人口播',
+    domainTitle: 'Agnes 域名配置',
+    domainHint: '选择 Agnes API 的接入域名。在中国大陆推荐使用 .cn 域名，以获得更稳定流畅的访问体验。',
+    domainComLabel: '国际域名',
+    domainCnLabel: '中国大陆推荐',
+    domainSaved: '已保存',
+    domainSaveFailed: '保存失败',
     ttPoetry: '诗词视频', poetrySettings: '诗词设置',
     poemLabel: '古诗原文', poemPlaceholder: '输入完整古诗原文，例如：春眠不觉晓，处处闻啼鸟...',
     poemHint: '可多段；诗句间用换行或标点自然分隔。AI 会按诗意拆分为若干场景。',
@@ -1743,6 +1793,12 @@ const T = {
     connLostMsg: 'Connection lost. Server may still be running. Check task list for status.',
     gotoList: 'Go to task list', reconnecting: 'Connection lost, retrying...',
     ttAnchor: 'Digital Human',
+    domainTitle: 'Agnes Domain',
+    domainHint: 'Choose the Agnes API access domain. In China, .cn is recommended for better connectivity.',
+    domainComLabel: 'Global',
+    domainCnLabel: 'China (recommended)',
+    domainSaved: 'Saved',
+    domainSaveFailed: 'Save failed',
     ttPoetry: 'Poetry Video', poetrySettings: 'Poetry Settings',
     poemLabel: 'Poem Text', poemPlaceholder: 'Enter the full poem, e.g. 春眠不觉晓，处处闻啼鸟...', poemHint: 'Multiple stanzas allowed; separated by line breaks or punctuation. AI splits into scenes by meaning.',
     scenePromptsOptional: 'Scene Prompts (Optional)', scenePromptsPlaceholder: 'Format: verse | visual description (one scene per line)', scenePromptsHint: 'Optional. One scene per line, fixed format "verse | visual description". Two ways give identical results: ① leave empty and let the system generate; ② copy the prompt below to any AI, then paste the result back.', scenePromptsExample: 'e.g. Spring sleeps, unaware of dawn... | Misty spring morning, birds singing',
@@ -1872,8 +1928,14 @@ const T = {
     resumed: 'Задача возобновлена', watchLog: 'Следите за логами.',
     task_: 'Задача', genFailed: 'Ошибка', genFailedMsg: 'Проверьте логи.',
     gotoResume: 'К списку задач', connLost: 'Соединение потеряно',
-    connLostMsg: 'Соединение потеряно.', gotoList: 'К списку', reconnecting: 'Переподключение...',
+    connLostMsg: 'Соединение потеряно.', gotoList: 'К списку',     reconnecting: 'Переподключение...',
     ttAnchor: 'Цифровой человек',
+    domainTitle: 'Домен Agnes',
+    domainHint: 'Выберите домен для API Agnes. В Китае рекомендуется .cn для стабильного доступа.',
+    domainComLabel: 'Глобальный',
+    domainCnLabel: 'Китай (рекомендуется)',
+    domainSaved: 'Сохранено',
+    domainSaveFailed: 'Ошибка сохранения',
     ttImage: 'Простое изображение', imageSettings: 'Настройки изображения',
     imagePrompt: 'Описание', imagePromptPlaceholder: 'Опишите желаемое изображение...',
     imageSize: 'Размер', refImageHint: 'Опционально. Загрузите для создания вариаций.',
@@ -1981,6 +2043,12 @@ const T = {
     task_: 'タスク', genFailed: '生成失敗', genFailedMsg: 'ログを確認。',
     gotoResume: 'タスク一覧へ', connLost: '接続切断', connLostMsg: '接続が切れました。',     gotoList: '一覧へ', reconnecting: '再接続中...',
     ttAnchor: 'デジタルヒューマン',
+    domainTitle: 'Agnes ドメイン',
+    domainHint: 'Agnes API のドメインを選択。中国では .cn が推奨されます。',
+    domainComLabel: 'グローバル',
+    domainCnLabel: '中国 (推奨)',
+    domainSaved: '保存しました',
+    domainSaveFailed: '保存に失敗しました',
     ttImage: '簡単画像', imageSettings: '画像設定',
     imagePrompt: '画像説明', imagePromptPlaceholder: '希望する画像を説明してください...',
     imageSize: '画像サイズ', refImageHint: '任意。アップロードしてバリエーションを生成。',
@@ -2088,6 +2156,12 @@ const T = {
     task_: '작업', genFailed: '생성 실패', genFailedMsg: '로그를 확인하세요.',
     gotoResume: '작업 목록으로', connLost: '연결 끊김', connLostMsg: '연결이 끊어졌습니다.',     gotoList: '목록으로', reconnecting: '재연결 중...',
     ttAnchor: '디지털 휴먼',
+    domainTitle: 'Agnes 도메인',
+    domainHint: 'Agnes API 도메인을 선택하세요. 중국에서는 .cn 사용을 권장합니다.',
+    domainComLabel: '글로벌',
+    domainCnLabel: '중국 (권장)',
+    domainSaved: '저장됨',
+    domainSaveFailed: '저장 실패',
     ttImage: '간단 이미지', imageSettings: '이미지 설정',
     imagePrompt: '이미지 설명', imagePromptPlaceholder: '원하는 이미지를 설명하세요...',
     imageSize: '이미지 크기', refImageHint: '선택사항. 업로드하여 변형을 생성합니다.',
@@ -2195,6 +2269,12 @@ const T = {
     task_: 'Tugas', genFailed: 'Gagal', genFailedMsg: 'Periksa log.',
     gotoResume: 'Ke senarai', connLost: 'Sambungan terputus', connLostMsg: 'Sambungan terputus.',     gotoList: 'Ke senarai', reconnecting: 'Menyambung semula...',
     ttAnchor: 'Digital Human',
+    domainTitle: 'Domain Agnes',
+    domainHint: 'Pilih domain API Agnes. Di China, .cn disyorkan untuk akses yang lebih stabil.',
+    domainComLabel: 'Global',
+    domainCnLabel: 'China (disyorkan)',
+    domainSaved: 'Disimpan',
+    domainSaveFailed: 'Gagal simpan',
     ttImage: 'Imej Ringkas', imageSettings: 'Tetapan Imej',
     imagePrompt: 'Penerangan Imej', imagePromptPlaceholder: 'Huraikan imej yang anda mahukan...',
     imageSize: 'Saiz Imej', refImageHint: 'Pilihan. Muat naik untuk hasilkan variasi.',
@@ -2301,6 +2381,12 @@ const T = {
     task_: 'Tugas', genFailed: 'Gagal', genFailedMsg: 'Periksa log.',
     gotoResume: 'Ke daftar', connLost: 'Koneksi terputus', connLostMsg: 'Koneksi terputus.',     gotoList: 'Ke daftar', reconnecting: 'Menyambung ulang...',
     ttAnchor: 'Digital Human',
+    domainTitle: 'Domain Agnes',
+    domainHint: 'Pilih domain API Agnes. Di China, .cn direkomendasikan untuk akses lebih stabil.',
+    domainComLabel: 'Global',
+    domainCnLabel: 'China (direkomendasikan)',
+    domainSaved: 'Disimpan',
+    domainSaveFailed: 'Gagal simpan',
     ttImage: 'Gambar Sederhana', imageSettings: 'Pengaturan Gambar',
     imagePrompt: 'Deskripsi Gambar', imagePromptPlaceholder: 'Jelaskan gambar yang Anda inginkan...',
     imageSize: 'Ukuran Gambar', refImageHint: 'Opsional. Unggah untuk menghasilkan variasi.',
@@ -2413,6 +2499,12 @@ const T = {
     connLostMsg: 'Verbindung zum Server verloren. Server läuft möglicherweise noch. Aufgabenliste prüfen.',
     gotoList: 'Zur Aufgabenliste', reconnecting: 'Verbindung verloren, neuer Versuch...',
     ttAnchor: 'Digitaler Mensch',
+    domainTitle: 'Agnes-Domain',
+    domainHint: 'Wählen Sie die API-Domain für Agnes. In China wird .cn für bessere Konnektivität empfohlen.',
+    domainComLabel: 'Global',
+    domainCnLabel: 'China (empfohlen)',
+    domainSaved: 'Gespeichert',
+    domainSaveFailed: 'Speichern fehlgeschlagen',
     ttImage: 'Einfaches Bild', imageSettings: 'Bildeinstellungen',
     imagePrompt: 'Bildbeschreibung', imagePromptPlaceholder: 'Gewünschtes Bild beschreiben...',
     imageSize: 'Bildgröße', refImageHint: 'Optional. Hochladen für Varianten; leer lassen für reine KI-Generierung.',
@@ -2525,6 +2617,12 @@ const T = {
     connLostMsg: 'Connexion au serveur perdue. Le serveur fonctionne peut-être encore. Vérifiez la liste des tâches.',
     gotoList: 'Aller à la liste', reconnecting: 'Connexion perdue, nouvelle tentative...',
     ttAnchor: 'Humain numérique',
+    domainTitle: 'Domaine Agnes',
+    domainHint: 'Choisissez le domaine API Agnes. En Chine, .cn est recommandé pour une meilleure connectivité.',
+    domainComLabel: 'Mondial',
+    domainCnLabel: 'Chine (recommandé)',
+    domainSaved: 'Enregistré',
+    domainSaveFailed: 'Échec de l\'enregistrement',
     ttImage: 'Image simple', imageSettings: 'Paramètres image',
     imagePrompt: 'Description image', imagePromptPlaceholder: 'Décrivez l\'image souhaitée...',
     imageSize: 'Taille image', refImageHint: 'Optionnel. Télécharger pour générer des variations ; laisser vide pour génération IA pure.',
@@ -2637,6 +2735,12 @@ const T = {
     connLostMsg: 'Verbinding met server verbroken. Server draait mogelijk nog. Controleer de takenlijst.',
     gotoList: 'Naar takenlijst', reconnecting: 'Verbinding verbroken, opnieuw proberen...',
     ttAnchor: 'Digitale mens',
+    domainTitle: 'Agnes-domein',
+    domainHint: 'Kies het API-domein voor Agnes. In China wordt .cn aanbevolen voor een betere connectiviteit.',
+    domainComLabel: 'Globaal',
+    domainCnLabel: 'China (aanbevolen)',
+    domainSaved: 'Opgeslagen',
+    domainSaveFailed: 'Opslaan mislukt',
     ttImage: 'Eenvoudige afbeelding', imageSettings: 'Afbeeldingsinstellingen',
     imagePrompt: 'Afbeeldingsbeschrijving', imagePromptPlaceholder: 'Beschrijf de gewenste afbeelding...',
     imageSize: 'Afbeeldingsgrootte', refImageHint: 'Optioneel. Uploaden voor variaties; leeg laten voor pure AI-generatie.',
@@ -2749,6 +2853,12 @@ const T = {
     connLostMsg: 'Conexión con el servidor perdida. El servidor puede seguir funcionando. Revise la lista de tareas.',
     gotoList: 'Ir a la lista', reconnecting: 'Conexión perdida, reintentando...',
     ttAnchor: 'Humano digital',
+    domainTitle: 'Dominio de Agnes',
+    domainHint: 'Elija el dominio de API de Agnes. En China, se recomienda .cn para una mejor conectividad.',
+    domainComLabel: 'Global',
+    domainCnLabel: 'China (recomendado)',
+    domainSaved: 'Guardado',
+    domainSaveFailed: 'Error al guardar',
     ttImage: 'Imagen simple', imageSettings: 'Configuración de imagen',
     imagePrompt: 'Descripción de imagen', imagePromptPlaceholder: 'Describa la imagen deseada...',
     imageSize: 'Tamaño de imagen', refImageHint: 'Opcional. Subir para generar variaciones; dejar vacío para generación IA pura.',
@@ -2861,6 +2971,12 @@ const T = {
     connLostMsg: 'Conexão com o servidor perdida. O servidor pode ainda estar funcionando. Verifique a lista de tarefas.',
     gotoList: 'Ir para a lista', reconnecting: 'Conexão perdida, tentando novamente...',
     ttAnchor: 'Humano digital',
+    domainTitle: 'Domínio Agnes',
+    domainHint: 'Escolha o domínio da API Agnes. Na China, recomenda-se .cn para melhor conectividade.',
+    domainComLabel: 'Global',
+    domainCnLabel: 'China (recomendado)',
+    domainSaved: 'Salvo',
+    domainSaveFailed: 'Falha ao salvar',
     ttImage: 'Imagem simples', imageSettings: 'Configurações de imagem',
     imagePrompt: 'Descrição da imagem', imagePromptPlaceholder: 'Descreva a imagem desejada...',
     imageSize: 'Tamanho da imagem', refImageHint: 'Opcional. Enviar para gerar variações; deixar vazio para geração IA pura.',
@@ -2973,6 +3089,12 @@ const T = {
     connLostMsg: 'Connessione al server persa. Il server potrebbe essere ancora in esecuzione. Controlla l\'elenco dei task.',
     gotoList: 'Vai all\'elenco', reconnecting: 'Connessione persa, nuovo tentativo...',
     ttAnchor: 'Umano digitale',
+    domainTitle: 'Dominio Agnes',
+    domainHint: 'Scegli il dominio API per Agnes. In Cina, .cn è consigliato per una migliore connettività.',
+    domainComLabel: 'Globale',
+    domainCnLabel: 'Cina (consigliato)',
+    domainSaved: 'Salvato',
+    domainSaveFailed: 'Salvataggio fallito',
     ttImage: 'Immagine semplice', imageSettings: 'Impostazioni immagine',
     imagePrompt: 'Descrizione immagine', imagePromptPlaceholder: 'Descrivi l\'immagine desiderata...',
     imageSize: 'Dimensione immagine', refImageHint: 'Opzionale. Carica per generare varianti; lascia vuoto per generazione IA pura.',
@@ -3067,6 +3189,9 @@ function applyLanguage(lang) {
     image: (document.getElementById('model-image') || {}).value || '',
     video: (document.getElementById('model-video') || {}).value || ''
   });
+  // 刷新域名紧凑栏（含 i18n 标题）
+  const domainRadio = document.querySelector('input[name="agnes-domain"]:checked');
+  if (domainRadio) updateDomainCompact(domainRadio.value);
 }
 
 function switchLang(lang) { applyLanguage(lang); }
@@ -3149,6 +3274,15 @@ const STEPS = {
     }
     // 加载模型选择（v5.0）
     try { await loadModels(); } catch(e) { console.error('init models error:', e); }
+    // 加载域名配置（v6.0）
+    if (d.agnes_domain) {
+      const radios = document.querySelectorAll('input[name="agnes-domain"]');
+      for (const r of radios) {
+        if (r.value === d.agnes_domain) r.checked = true;
+      }
+      updateDomainCompact(d.agnes_domain);
+      updateDomainStatus(d.agnes_domain);
+    }
   } catch(e) { console.error('init config load error:', e); }
 
   // Character count for manuscript
@@ -5062,6 +5196,60 @@ document.getElementById('model-save').onclick = async () => {
   }
 };
 
+// ═══════════════════════════════════════════════════
+// 域名配置（v6.0）
+// ═══════════════════════════════════════════════════
+
+function updateDomainCompact(domain) {
+  const compact = document.getElementById('domain-compact');
+  const textEl = document.getElementById('domain-compact-text');
+  const isCn = domain === 'cn';
+  textEl.innerHTML =
+    '<span class="text-gray-300 font-medium">' + t('domainTitle') + '</span>' +
+    '<span class="text-gray-600 mx-2">·</span>' +
+    '<span class="' + (isCn ? 'text-green-400' : 'text-gray-400') + '">' +
+    'apihub.agnes-ai.' + escapeHtml(domain) +
+    '</span>';
+}
+
+function updateDomainStatus(domain) {
+  const statusEl = document.getElementById('domain-status');
+  statusEl.textContent = 'apihub.agnes-ai.' + domain;
+  if (domain === 'cn') {
+    statusEl.className = 'text-xs px-2 py-1 rounded-full bg-green-900/40 text-green-300';
+  } else {
+    statusEl.className = 'text-xs px-2 py-1 rounded-full bg-gray-800 text-gray-400';
+  }
+}
+
+document.getElementById('domain-save').onclick = async () => {
+  const selected = document.querySelector('input[name="agnes-domain"]:checked');
+  if (!selected) return;
+  const domain = selected.value;
+  const errEl = document.getElementById('domain-save-error');
+  const okEl = document.getElementById('domain-save-status');
+  errEl.classList.add('hidden');
+  okEl.classList.add('hidden');
+  const form = new FormData();
+  form.append('domain', domain);
+  try {
+    const r = await fetch('/api/config/domain', { method: 'POST', body: form });
+    if (r.ok) {
+      okEl.classList.remove('hidden');
+      updateDomainCompact(domain);
+      updateDomainStatus(domain);
+      setTimeout(() => okEl.classList.add('hidden'), 2000);
+    } else {
+      const d = await r.json().catch(() => ({}));
+      errEl.textContent = d.detail || (t('domainSaveFailed') || '保存失败');
+      errEl.classList.remove('hidden');
+    }
+  } catch (e) {
+    errEl.textContent = '网络错误';
+    errEl.classList.remove('hidden');
+  }
+};
+
 // ═══════════════════════════════════════════════════
 // 水印开关
 // ═══════════════════════════════════════════════════