free-short-video 5.6.1 → 5.7.2

package/.dockerignore

@@ -14,6 +14,9 @@ __pycache__/
 build/
 dist/
 
+# 前端源码与依赖（构建产物已在 static/，镜像无需携带源码与 node_modules）
+frontend/
+
 # 运行时产物与媒体（体积大，不进镜像）
 .working_dir/
 static/generated/

package/.env.example

@@ -0,0 +1,35 @@
+# ═══════════════════════════════════════════════════════════════════
+# Agnes Video Generator 配置模板（示例文件，绝不要放入真实 Key！）
+#
+# 使用方式：
+#   1. 复制本文件为 .env：cp .env.example .env
+#   2. 填入你自己的 Key（从 https://platform.agnes-ai.com 获取，免费）
+#   3. 重启服务生效（需已安装 python-dotenv；未安装时跳过 .env 读取，
+#      Key 仍可通过环境变量或 Web 设置页 POST /api/config/keys 配置）
+#
+# 完整多 Key / 限速说明见 docs/plans/v5.0/optimization_roadmap.md §1
+# ═══════════════════════════════════════════════════════════════════
+
+# Agnes AI API Key（必填）
+# 从 https://platform.agnes-ai.com 获取免费 Key
+AGNES_API_KEY=your-api-key-here
+
+# 多 Key 轮询（可选，见 optimization_roadmap §1.3）
+# 每个 Key 的配额独立，总量 ≈ 20 × Key 数 / 分钟
+# AGNES_API_KEY_2=your-second-api-key
+# AGNES_API_KEY_3=your-third-api-key
+
+# 限速配额覆盖（次/分钟，默认 = 20 × Key 数 × 0.8 安全系数）
+# AGNES_RATE_LIMIT=160
+
+# 桶容量覆盖（默认 = 4 × Key 数；仅需调节突发并发时使用）
+# AGNES_RATE_BURST=32
+
+# 视频提交独立限速（次/分钟，默认 = 1 × Key 数；服务端为全局 1/min 时设 =1）
+# AGNES_VIDEO_RATE_LIMIT=8
+# AGNES_VIDEO_RATE_BURST=8
+
+# 可选端点/模型覆盖
+# AGNES_BASE_URL=https://apihub.agnes-ai.com/v1
+# AGNES_IMAGE_MODEL=agnes-image-2.1-flash
+# AGNES_VIDEO_MODEL=agnes-video-v2.0

package/README.md

@@ -1,3 +1,19 @@
+---
+
+# What's New in v5.7.2
+
+## What's New
+
+### Bug Fixes
+
+- **Intermediate artifacts restored in the progress panel** — after the v5.7.0 frontend re-architecture, intermediate artifacts (story, reference images, scene videos, subtitles, etc.) were no longer shown while a task runs. The progress panel now loads artifacts on task start, refreshes them as each step completes during polling, and shows the final output when finished. Viewing a task from the task list also opens the progress panel with its artifacts and result video.
+- **GitHub Code Scanning security fixes** — sensitive data no longer logged at startup (`get_api_keys_source`); key IDs are now derived with HMAC-SHA256 (blake2b keyed mode) instead of plain SHA-256; task-directory deletion/existence checks operate only on realpath-resolved paths (path-injection hardening).
+- **Release pipeline fixes** — the npm README preparation step no longer fails when the format string starts with `-`, and the release workflow now tolerates missing release-notes docs with a warning instead of aborting.
+
+---
+
+---
+
 ## Quick Start (npm)
 
 ```bash
@@ -111,12 +127,12 @@ To be honest, Agnes's video model isn't perfect yet. The generated frames are so
 
 ## 📚 Documentation
 
-- **[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.
+- **[Features](docs/public/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/public/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/public/usage.md)** — Configure your API key, pick a video mode, resume from checkpoints, the three chaining modes, and logs & output layout.
+- **[Architecture](docs/public/architecture.md)** — Project structure and tech stack.
+- **[API Reference](docs/public/api.md)** — Full REST + WebSocket endpoint list.
+- **[FAQ](docs/public/faq.md)** — Frequently asked questions.
+- **[About & License](docs/public/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

@@ -16,11 +16,17 @@ from typing import List
 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.api.rate_limiter import get_rate_limiter, request_with_key_rotation
 from core.config import get_agnes_base_url
 
 logger = logging.getLogger(__name__)
 
+# json_repair 可选依赖（优化 4）：未安装时行为与现状完全一致
+try:
+    from json_repair import repair_json
+except ImportError:
+    repair_json = None
+
 # 重试配置
 _MAX_RETRIES = 3
 _RETRY_BASE_DELAY = 15  # 秒，指数退避基数
@@ -57,10 +63,21 @@ class AgnesChatAPI:
     def __init__(self, api_key: str, model: str = "agnes-2.0-flash"):
         self.api_key = api_key
         self.model = model
-        self.headers = {
-            "Authorization": f"Bearer {api_key}",
+        # 基础 headers（不含 Authorization）：每次请求前经 _auth_headers() 注入当前 Key
+        self._base_headers = {
             "Content-Type": "application/json",
         }
+        # 向后兼容：旧调用方可能读取 self.headers
+        self.headers = dict(self._base_headers)
+
+    def _auth_headers(self) -> dict:
+        """每次请求前生成带当前 Key 的 headers 副本（从 KeyRing 轮转取 Key）。"""
+        from core.api.key_manager import get_key_ring
+
+        key = get_key_ring().next()
+        h = dict(self._base_headers)
+        h["Authorization"] = f"Bearer {key}"
+        return h
 
     def _image_to_b64_uri(self, path: str) -> str:
         with open(path, "rb") as f:
@@ -89,10 +106,12 @@ class AgnesChatAPI:
         return ""
 
     def _request_with_retry(self, payload: dict, timeout: int = 120) -> dict:
-        """带重试的 API 请求。
+        """带重试的 API 请求（429 换 Key + 5xx/超时/连接错误指数退避）。
 
-        对 5xx/429/超时/连接错误进行最多 3 次指数退避重试。
-        4xx 错误（非 429）直接抛出不重试。
+        经 ``request_with_key_rotation`` 统一封装：
+        - 多 Key 下 429 换 Key 立即重试（不计入退避）；
+        - 全 Key 429 / 5xx / 超时 / 连接错误 指数退避最多 3 次；
+        - 4xx（非 429）不重试，直接抛出。
         每次请求前通过全局限速器控制调用频率。
 
         Args:
@@ -105,75 +124,51 @@ class AgnesChatAPI:
         Raises:
             requests.HTTPError: 4xx 客户端错误或重试耗尽。
         """
-        last_exc = None
-        for attempt in range(_MAX_RETRIES):
-            try:
-                get_rate_limiter().acquire()
-                resp = requests.post(
-                    f"{get_agnes_base_url()}/chat/completions",
-                    headers=self.headers,
-                    json=payload,
-                    timeout=timeout,
+        prompt = self._extract_prompt_from_payload(payload)
+        try:
+            get_rate_limiter().acquire()
+            resp = request_with_key_rotation(
+                requests.post,
+                f"{get_agnes_base_url()}/chat/completions",
+                max_retries=_MAX_RETRIES,
+                retry_base_delay=_RETRY_BASE_DELAY,
+                json=payload,
+                timeout=timeout,
+            )
+            if self._should_retry(resp):
+                # helper 内部重试已耗尽（单 Key 429 或持续 5xx），记录最终失败
+                collect_error(
+                    "chat", "chat",
+                    prompt=prompt,
+                    error_type="RateLimit429" if resp.status_code == 429 else f"HTTP{resp.status_code}",
+                    error_message=f"HTTP {resp.status_code}: retries exhausted",
+                    status_code=resp.status_code,
+                    response_body=resp.text,
+                    retry_count=_MAX_RETRIES,
                 )
-                if self._should_retry(resp) and attempt < _MAX_RETRIES - 1:
-                    delay = _RETRY_BASE_DELAY * (attempt + 1)
-                    logger.warning(
-                        f"[AgnesChat] Server error {resp.status_code}, "
-                        f"retry {attempt + 1}/{_MAX_RETRIES} in {delay}s..."
-                    )
-                    collect_error(
-                        "chat", "chat",
-                        prompt=self._extract_prompt_from_payload(payload),
-                        error_type=f"HTTP{resp.status_code}",
-                        error_message=f"HTTP {resp.status_code}: server error",
-                        status_code=resp.status_code,
-                        response_body=resp.text,
-                        retry_count=attempt + 1,
-                    )
-                    time.sleep(delay)
-                    continue
-                resp.raise_for_status()
-                return resp.json()
-            except (requests.ConnectionError, requests.Timeout) as e:
-                last_exc = e
-                # 每次失败都记录（包括中间重试）
-                collect_error_from_exception(
+            resp.raise_for_status()
+            return resp.json()
+        except requests.HTTPError as e:
+            resp = getattr(e, "response", None)
+            if resp is not None and resp.status_code < 500 and resp.status_code != 429:
+                # 4xx（非 429）不可重试
+                collect_error(
                     "chat", "chat",
-                    exc=e, prompt=self._extract_prompt_from_payload(payload),
-                    retry_count=attempt + 1,
+                    prompt=prompt,
+                    error_type=type(e).__name__,
+                    error_message=str(e),
+                    status_code=resp.status_code,
+                    response_body=resp.text[:5000],
+                    retry_count=_MAX_RETRIES,
                 )
-                if attempt < _MAX_RETRIES - 1:
-                    delay = _RETRY_BASE_DELAY * (attempt + 1)
-                    logger.warning(
-                        f"[AgnesChat] {type(e).__name__}, "
-                        f"retry {attempt + 1}/{_MAX_RETRIES} in {delay}s..."
-                    )
-                    time.sleep(delay)
-                    continue
-                raise
-        # 重试耗尽
-        if last_exc:
+            raise
+        except (requests.ConnectionError, requests.Timeout) as e:
             collect_error_from_exception(
                 "chat", "chat",
-                exc=last_exc, prompt=self._extract_prompt_from_payload(payload),
-                retry_count=_MAX_RETRIES,
-            )
-            raise last_exc
-        # 不可重试的 HTTP 错误（4xx 非 429）
-        try:
-            resp.raise_for_status()  # type: ignore[possibly-undefined]
-        except requests.HTTPError as e:
-            collect_error(
-                "chat", "chat",
-                prompt=self._extract_prompt_from_payload(payload),
-                error_type=type(e).__name__,
-                error_message=str(e),
-                status_code=resp.status_code,  # type: ignore[possibly-undefined]
-                response_body=resp.text[:5000],  # type: ignore[possibly-undefined]
+                exc=e, prompt=prompt,
                 retry_count=_MAX_RETRIES,
             )
             raise
-        return resp.json()  # type: ignore[possibly-undefined]
 
     def chat(self, system_prompt: str, user_prompt: str, max_tokens: int = 4096) -> str:
         """纯文本 Chat 调用（含重试）。"""
@@ -230,6 +225,15 @@ class AgnesChatAPI:
                     return json.loads(match.group())
                 except (json.JSONDecodeError, ValueError):
                     pass
+            # Step 3.5: json_repair 修复（可选依赖，修复 LLM 常见缺冒号/尾随逗号/单引号）
+            if repair_json is not None:
+                try:
+                    repaired = repair_json(cleaned, return_objects=True)
+                    if isinstance(repaired, dict):
+                        logger.info("[AgnesChat] JSON repaired via json_repair")
+                        return repaired
+                except Exception:
+                    pass
             # Step 4: 首轮失败则重试一次 chat 调用
             if retry == 0:
                 logger.warning("[AgnesChat] JSON parse failed, retrying chat call...")

package/core/api/agnes_image.py

@@ -11,9 +11,11 @@ from typing import List, Optional
 import requests
 
 from core.api.error_collector import collect_error, collect_error_from_exception
+from core.api.key_manager import get_key_ring
 from core.api.rate_limiter import get_rate_limiter
 from core.config import get_agnes_base_url
 from utils.image import download_image
+from utils.image_normalizer import normalize_reference_path
 
 logger = logging.getLogger(__name__)
 
@@ -59,10 +61,19 @@ class AgnesImageAPI:
         # i2i 默认与 t2i 同模型（官方 2.1 同时支持 t2i/i2i）；环境变量可回退到 2.0。
         env_i2i = os.environ.get("AGNES_IMAGE_I2I_MODEL")
         self.i2i_model = i2i_model or env_i2i or model
-        self.headers = {
-            "Authorization": f"Bearer {api_key}",
+        # 基础 headers（不含 Authorization）：每次请求前经 _auth_headers() 注入当前 Key
+        self._base_headers = {
             "Content-Type": "application/json",
         }
+        # 向后兼容：旧调用方可能读取 self.headers
+        self.headers = dict(self._base_headers)
+
+    def _auth_headers(self) -> dict:
+        """每次请求前生成带当前 Key 的 headers 副本（从 KeyRing 轮转取 Key）。"""
+        key = get_key_ring().next()
+        h = dict(self._base_headers)
+        h["Authorization"] = f"Bearer {key}"
+        return h
 
     async def _path_to_b64(self, path: str) -> str:
         def _read():
@@ -102,7 +113,20 @@ class AgnesImageAPI:
             payload["negative_prompt"] = kwargs["negative_prompt"]
 
         if reference_image_paths:
-            resolved = [await self._resolve_image_ref(p) for p in reference_image_paths]
+            # 优化 2：入参处先归一化参考图（尺寸统一 + 体积压缩），再 resolve。
+            # 目标尺寸从 size（"768x1152"）解析，失败回退 1024x1024。
+            sw, sh = 1024, 1024
+            try:
+                parts = (size or "").lower().split("x")
+                if len(parts) == 2:
+                    sw, sh = int(parts[0]), int(parts[1])
+            except (ValueError, TypeError):
+                sw, sh = 1024, 1024
+            normalized_paths = []
+            for p in reference_image_paths:
+                norm = await asyncio.to_thread(normalize_reference_path, p, sw, sh)
+                normalized_paths.append(norm)
+            resolved = [await self._resolve_image_ref(p) for p in normalized_paths]
             # 官方文档所有 i2i 示例均用 image 数组形式（extra_body.image=[url]），
             # 单图也统一传数组，保持与官方协议一致。
             payload["extra_body"] = {
@@ -113,7 +137,11 @@ class AgnesImageAPI:
         logger.info(f"[AgnesImage] Generating ({'i2i' if use_i2i else 't2i'}): {prompt[:80]}...")
 
         resp = None
-        for attempt in range(max_retries):
+        attempt = 0
+        rotations = 0
+        ring = get_key_ring()
+        max_rotations = len(ring) * max_retries
+        while attempt < max_retries:
             try:
                 # 全局限速：在发起 HTTP 请求前获取令牌
                 await asyncio.to_thread(get_rate_limiter().acquire)
@@ -122,29 +150,51 @@ class AgnesImageAPI:
                 resp = await asyncio.to_thread(
                     requests.post,
                     f"{get_agnes_base_url()}/images/generations",
-                    headers=self.headers,
+                    headers=self._auth_headers(),
                     json=payload,
                     timeout=(30, read_timeout),
                 )
 
-                # 429 限流：退避重试
-                if resp.status_code == 429 and attempt < max_retries - 1:
-                    delay = retry_base_delay * (attempt + 1)
-                    logger.warning(
-                        f"[AgnesImage] 429 rate limit, "
-                        f"retry {attempt + 1}/{max_retries} in {delay:.0f}s..."
-                    )
+                # 429 限流：多 Key 换 Key 立即重试；否则指数退避
+                if resp.status_code == 429:
+                    if ring.has_multiple() and rotations < max_rotations:
+                        rotations += 1
+                        ring.rotate()
+                        logger.warning(
+                            f"[KeyRotation] HTTP 429, 换 Key 立即重试 "
+                            f"(image, rotation {rotations})"
+                        )
+                        continue
+                    if attempt < max_retries - 1:
+                        delay = retry_base_delay * (attempt + 1)
+                        logger.warning(
+                            f"[AgnesImage] 429 rate limit, "
+                            f"retry {attempt + 1}/{max_retries} in {delay:.0f}s..."
+                        )
+                        collect_error(
+                            "image", "generate_single_image",
+                            prompt=prompt,
+                            error_type="RateLimit429",
+                            error_message=f"HTTP 429: rate limited",
+                            status_code=429,
+                            response_body=resp.text,
+                            retry_count=attempt + 1,
+                        )
+                        await asyncio.sleep(delay)
+                        attempt += 1
+                        continue
+                    # 退避耗尽：记录最终失败并抛出
                     collect_error(
                         "image", "generate_single_image",
                         prompt=prompt,
                         error_type="RateLimit429",
-                        error_message=f"HTTP 429: rate limited",
+                        error_message=f"HTTP 429: retries exhausted",
                         status_code=429,
                         response_body=resp.text,
-                        retry_count=attempt + 1,
+                        retry_count=max_retries,
                     )
-                    await asyncio.sleep(delay)
-                    continue
+                    resp.raise_for_status()
+                    break
 
                 # 5xx 服务端错误：退避重试
                 if resp.status_code >= 500 and attempt < max_retries - 1:
@@ -163,6 +213,7 @@ class AgnesImageAPI:
                         retry_count=attempt + 1,
                     )
                     await asyncio.sleep(delay)
+                    attempt += 1
                     continue
 
                 if resp.status_code != 200:
@@ -183,6 +234,7 @@ class AgnesImageAPI:
                         f"retry {attempt + 1}/{max_retries} in {delay:.0f}s..."
                     )
                     await asyncio.sleep(delay)
+                    attempt += 1
                     continue
                 raise
         else:

package/core/api/agnes_video.py

@@ -12,8 +12,10 @@ from typing import List, Optional
 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.api.key_manager import get_key_ring
+from core.api.rate_limiter import get_rate_limiter, get_video_submit_limiter
 from core.config import get_agnes_base_url, get_agnes_api_root
+from utils.image_normalizer import normalize_reference_path
 from utils.video import download_video
 
 logger = logging.getLogger(__name__)
@@ -61,10 +63,19 @@ class AgnesVideoAPI:
         self.max_retries = max_retries
         self.retry_base_delay = retry_base_delay
         self.shutdown_event = None
-        self.headers = {
-            "Authorization": f"Bearer {api_key}",
+        # 基础 headers（不含 Authorization）：每次请求前经 _auth_headers() 注入当前 Key
+        self._base_headers = {
             "Content-Type": "application/json",
         }
+        # 向后兼容：旧调用方可能读取 self.headers
+        self.headers = dict(self._base_headers)
+
+    def _auth_headers(self) -> dict:
+        """每次请求前生成带当前 Key 的 headers 副本（从 KeyRing 轮转取 Key）。"""
+        key = get_key_ring().next()
+        h = dict(self._base_headers)
+        h["Authorization"] = f"Bearer {key}"
+        return h
 
     def _path_to_b64(self, path: str) -> str:
         with open(path, "rb") as f:
@@ -121,7 +132,11 @@ class AgnesVideoAPI:
         return ref
 
     async def _upload_image_to_url(self, image_path: str, retries: int = 3) -> Optional[str]:
-        for attempt in range(retries):
+        attempt = 0
+        rotations = 0
+        ring = get_key_ring()
+        max_rotations = len(ring) * retries
+        while attempt < retries:
             if self.shutdown_event and self.shutdown_event.is_set():
                 logger.info("[AgnesVideo] Image upload cancelled by shutdown")
                 return None
@@ -142,14 +157,23 @@ class AgnesVideoAPI:
                 resp = await asyncio.to_thread(
                     requests.post,
                     f"{get_agnes_base_url()}/images/generations",
-                    headers=self.headers,
+                    headers=self._auth_headers(),
                     json=payload,
                     timeout=(30, 120),
                 )
                 if resp.status_code == 429:
+                    if ring.has_multiple() and rotations < max_rotations:
+                        rotations += 1
+                        ring.rotate()
+                        logger.warning(
+                            f"[KeyRotation] HTTP 429, 换 Key 立即重试 "
+                            f"(upload, rotation {rotations})"
+                        )
+                        continue
                     delay = _UPLOAD_RETRY_BASE_DELAY_SECONDS * (attempt + 1)
                     logger.warning(f"[AgnesVideo] Image upload 429, retry in {delay}s...")
                     await asyncio.sleep(delay)
+                    attempt += 1
                     continue
                 resp.raise_for_status()
                 result = resp.json()
@@ -241,16 +265,24 @@ class AgnesVideoAPI:
                     logger.info(f"[AgnesVideo] Polling video {video_id[:16]}... (poll #{poll_count + 1}, elapsed {elapsed:.0f}s)")
                 # 全局限速：每次轮询都消耗一个令牌
                 await asyncio.to_thread(get_rate_limiter().acquire)
-                # M2: 用 wait_for 包裹以支持取消
-                resp = await asyncio.wait_for(
-                    asyncio.to_thread(
-                        requests.get,
-                        f"{get_agnes_api_root()}/agnesapi?video_id={video_id}",
-                        headers=self.headers,
-                        timeout=15,
-                    ),
-                    timeout=30,
-                )
+                # M2: 用 wait_for 包裹以支持取消；429 换 Key 立即重试（轮询也轮转 Key 分摊配额）
+                poll_attempts = 0
+                while True:
+                    resp = await asyncio.wait_for(
+                        asyncio.to_thread(
+                            requests.get,
+                            f"{get_agnes_api_root()}/agnesapi?video_id={video_id}",
+                            headers=self._auth_headers(),
+                            timeout=15,
+                        ),
+                        timeout=30,
+                    )
+                    if resp.status_code == 429 and get_key_ring().has_multiple() and poll_attempts < 5:
+                        get_key_ring().rotate()
+                        poll_attempts += 1
+                        logger.warning("[KeyRotation] HTTP 429 on poll, 换 Key 立即重试")
+                        continue
+                    break
                 resp.raise_for_status()
                 result = resp.json()
                 status = result.get("status", "")
@@ -309,19 +341,23 @@ class AgnesVideoAPI:
 
     async def _submit_with_retry(self, payload: dict, mode_desc: str) -> str:
         frame_reductions_left = 2  # allow up to 2 frame-count reductions on 400
-        for attempt in range(self.max_retries):
+        attempt = 0
+        rotations = 0
+        ring = get_key_ring()
+        max_rotations = len(ring) * self.max_retries
+        while attempt < self.max_retries:
             if self.shutdown_event and self.shutdown_event.is_set():
                 raise RuntimeError("Video generation cancelled by user")
             try:
                 logger.info(f"[AgnesVideo] Submitting {mode_desc} (attempt {attempt + 1}/{self.max_retries})...")
-                # 全局限速：在发起提交请求前获取令牌
-                await asyncio.to_thread(get_rate_limiter().acquire)
+                # 视频提交独立限速桶（服务端 1/min 硬限制，不与 chat/image 共享配额）
+                await asyncio.to_thread(get_video_submit_limiter().acquire)
                 # M2: 缩短读超时从 180s 到 60s，使 stop() 更快生效
                 resp = await asyncio.wait_for(
                     asyncio.to_thread(
                         requests.post,
                         f"{get_agnes_base_url()}/videos",
-                        headers=self.headers,
+                        headers=self._auth_headers(),
                         json=payload,
                         timeout=(15, 60),
                     ),
@@ -335,6 +371,15 @@ class AgnesVideoAPI:
                         return video_id
 
                 if resp.status_code == 429:
+                    # 多 Key：换 Key 立即重试（不 sleep、不计入退避）
+                    if ring.has_multiple() and rotations < max_rotations:
+                        rotations += 1
+                        ring.rotate()
+                        logger.warning(
+                            f"[KeyRotation] HTTP 429 on submit, 换 Key 立即重试 "
+                            f"(rotation {rotations})"
+                        )
+                        continue
                     delay = self.retry_base_delay * (attempt + 1)
                     logger.warning(
                         f"[AgnesVideo] 429 rate limit on {mode_desc}, "
@@ -351,6 +396,7 @@ class AgnesVideoAPI:
                         extra={"mode": mode_desc},
                     )
                     await asyncio.sleep(delay)
+                    attempt += 1
                     continue
 
                 if resp.status_code >= 500:
@@ -370,6 +416,7 @@ class AgnesVideoAPI:
                         extra={"mode": mode_desc},
                     )
                     await asyncio.sleep(delay)
+                    attempt += 1
                     continue
 
                 # HTTP 400 with num_frames exceeded → reduce frames and retry
@@ -427,6 +474,7 @@ class AgnesVideoAPI:
                         f"retry {attempt + 1}/{self.max_retries} in {delay:.0f}s..."
                     )
                     await asyncio.sleep(delay)
+                    attempt += 1
                     continue
                 raise
 
@@ -495,7 +543,10 @@ class AgnesVideoAPI:
 
         resolved_refs = []
         for p in reference_image_paths:
-            resolved_refs.append(await self._resolve_image_ref(p))
+            # 优化 2：入参处先归一化参考图（尺寸统一 + 体积压缩），再 resolve。
+            # URL/data: 透传、失败回退原图，安全无回归。
+            norm = await asyncio.to_thread(normalize_reference_path, p, width, height)
+            resolved_refs.append(await self._resolve_image_ref(norm))
         n_refs = len(resolved_refs)
 
         if n_refs == 0: