free-short-video 7.0.1 → 7.0.3

package/.env.example

@@ -36,11 +36,15 @@ HOST=0.0.0.0
 PORT=8765
 
 # 注：Agnes API 走哪个站点（国际站 / 国内站）**不通过环境变量配置**
-# （AGNES_BASE_URL 已废弃，代码中不再读取）。请在 Web 设置页的 API Key 面板
-# 选择域名，或用「自动探测域名」逐 Key 补全匹配域名（每个 Key 可绑定各自域名）。
+# （AGNES_BASE_URL 已废弃，代码中不再读取）。请在 Web 设置页的 API Key 面板选择全局默认域名。
+# ⚠️ 重要：通过本文件 / 环境变量写入的 Key 属于 env 来源，**无法逐个绑定域名，也不参与
+#    Web 页的「自动探测域名」**——它们一律使用你在 Web 页设定的「全局默认域名」。因此：
+#      - 单站点 Key：把全局默认域名设成与该 Key 站点一致即可；
+#      - 混用不同站点的 Key：请改到 Web 配置页逐个添加（config 来源），再逐 Key 绑定域名
+#        或点「自动探测域名」，才能各走各的站点（env Key 做不到这点）。
+#    跨站使用 Key（如国际站 Key 打到国内站专属域名）会得到 HTTP 401 / 无效的令牌。
 # 可选域名：com = apihub.agnes-ai.com（国际站）、cn = api.agnes-ai.cn（国内站，
-# 需国内站专属 Key）、cn_bak = apihub.agnes-ai.cn（备用，国际站 Key 亦可用）。
-# 跨站使用 Key 会得到 HTTP 401 / 无效的令牌。
+# 需国内站专属 Key）、cn_bak = apihub.agnes-ai.cn（备用，国内与国际 Key 均可用）。
 
 
 # ── 4. 限速（可选）─────────────────────────────────────────────────

package/README.md

@@ -1,39 +1,26 @@
 ---
 
-# What's New in v7.0.1
+# What's New in v7.0.3
 
 ## What's New
 
 ### Features & Improvements
 
-- **Provider setup guidance in Settings.** When adding a third-party text model provider, the
-  configuration panel now shows practical notes with a recommended provider (AMD Radeon
-  Cloud) and its OpenAI-compatible endpoint, plus a link to a step-by-step guide for
-  collecting free tokens. Available in all 22 UI languages.
-- **Localized backend messages everywhere.** The localization framework shipped in v7.0.0 has
-  been extended from high-impact messages to the complete set: ~120 remaining strings across
-  all six task types — progress updates for every pipeline step, task-creation and preview
-  validation errors, config/provider validation, voice-compatibility warnings and cleanup
-  tooling messages — are rendered in the task's UI language.
-
-### Refactoring & Optimizations
-
-- **Single bilingual message catalog for the backend.** All user-facing backend strings now
-  live in one translation catalog (~200 keys) with CI-enforced Chinese/English parity and a
-  documented contributor convention (domain-based key naming, keyword placeholders, per-request
-  vs per-task language sources), making the interface-language behavior a maintained invariant
-  rather than an ad-hoc practice.
+* **Survive Agnes queue saturation.** When Agnes rejects submissions with `503 video_queue_full` (the free Video 2.5 Flash queue can stay full for 10+ minutes), the app now retries on a dedicated track — every 30–60s for up to 900s (`AGNES_VIDEO_QUEUE_RETRY_SECONDS`) — without consuming the normal retry budget, so you no longer get a premature "generation failed" while you were simply never queued. Nothing is consumed by a rejected submit. The progress panel shows it live: `Agnes 视频队列已满（HTTP 503 · video_queue_full），正在排队重试（第 N 次 / 已等 X 分钟）。建议错峰重试或稍后再试。`
+* **Honest error messages.** Upstream failures now surface the real reason instead of a generic `HTTP 503: server error` or a raw dict dump: the submitted error's `code` and `message` are kept end-to-end (e.g. `ComfyUI internal error: inference not finished after 15 minutes (code=500)`), so "queue full" and "queued but stuck" are no longer indistinguishable. `error_logs/` stores readable text plus the upstream code.
+* **Queue notices in your language (all 22 locales).** Queue-full progress and failure notices are now rendered by the frontend from structured i18n keys, so Japanese, Arabic, Russian, etc. users see their own language instead of a Chinese fallback. The raw upstream error (HTTP status, `video_queue_full`) is quoted untranslated, as it comes from the API.
+* **Config panels start collapsed.** All four configuration cards (provider management, model selection, workspace, privacy) now start collapsed instead of expanded; your manual expand/collapse preference is still remembered per browser.
+* **Know when a model is not adapted.** Video models that appear in the upstream model list but have no capability entry in your installed version are now marked with `⚠` plus an explicit notice, instead of being silently submitted with the old v2.0 pixel protocol. The app version is shown in the page footer and returned by `GET /api/models`.
 
 ### Bug Fixes
 
-- English-interface users no longer receive Chinese progress messages and validation errors
-  in simple, creative, manuscript, anchor and poetry video tasks (follow-up to issue #64).
-- Reference-image analysis failures ("image analysis failed (Start Frame)") are reported in
-  the task's UI language instead of hard-coded Chinese (issue #65 follow-up).
+* **Switching the text model provider back to Agnes now works.** Previously the switch only changed the UI: the backend kept the previously selected third-party provider and kept calling its endpoint (an empty value was dropped by the form layer and treated as "no change"). The selection is now sent explicitly, and it persists when you click **Save**.
+* **Frontend no longer breaks after an update.** The app entry page is now served with `Cache-Control: no-cache`, so browsers can no longer keep a stale entry page that references deleted build assets — the "task list (or the whole app) silently stopped working after pulling a new version" failure mode is gone. After upgrading, do one hard refresh (`Cmd/Ctrl+Shift+R`); afterwards updates apply on normal reload.
+* Fixed the queue-full messaging to name Agnes, quote the raw upstream error, and include an actionable suggestion (retry off-peak), instead of the vague "upstream video queue is full".
 
 ---
 
-No action is required after upgrading.
+No action is required after upgrading. If your tasks sit at 0% for a long time, that is the Agnes free queue — the app now retries and tells you so; off-peak retries or switching to Video 2.0 (separate queue) remain the practical workarounds.
 
 ---
 

package/core/api/agnes_video.py

@@ -6,6 +6,8 @@ import json
 import logging
 import mimetypes
 import os
+import random
+import subprocess
 import time
 from typing import List, Optional
 
@@ -15,10 +17,10 @@ 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, get_video_submit_limiter
 from core.config import (
-    VIDEO_ASPECT_RATIOS,
     get_agnes_api_root,
     get_base_url_for_key,
     is_v25_video_model,
+    width_height_to_aspect_ratio,
 )
 from utils.image_normalizer import normalize_reference_path
 from utils.video import download_video
@@ -49,6 +51,105 @@ def _adaptive_poll_interval(interval: int, poll_count: int) -> int:
     return min(interval, 20 + (poll_count // 5) * 5)
 
 
+# ── v7.0 上游可靠性加固（docs/plans/v7.0/upstream_error_handling_plan.md）──
+
+# 提交侧「队列类」瞬时错误的 body code（U1）：走独立退避轨道，不消耗普通 5xx
+# 的重试配额。实测 video_queue_full 可持续 12 分钟以上（连续 25 次被拒），
+# 而普通 5xx 退避（5 次 × 30s 递增）约 5.5 分钟就会放弃。
+_QUEUE_FULL_CODES = {"video_queue_full", "fail_to_fetch_task"}
+
+# 队列满退避间隔（秒）：固定基数 + 随机抖动（模块级常量，便于测试缩小）
+_QUEUE_RETRY_BASE_DELAY = 30.0
+_QUEUE_RETRY_JITTER = 30.0
+
+
+def _upstream_error(body) -> tuple:
+    """U2：从上游响应体统一提取 ``(code, message)``。
+
+    兼容两种输入：已解析的 dict（轮询结果）或 ``requests.Response``（提交响应）。
+
+    - 提交侧 5xx：body 形如 ``{"code": "video_queue_full", "message": "..."}``
+    - 轮询侧 ``status=failed``：``error`` 字段是对象 ``{"code", "message"}``
+
+    提取失败返回 ``("", "")``，由调用方回退到通用文案。
+    """
+    data = body
+    if body is not None and hasattr(body, "json"):
+        try:
+            data = body.json()
+        except Exception:
+            return "", (getattr(body, "text", "") or "").strip()[:200]
+    if isinstance(data, dict):
+        code = str(data.get("code") or "")
+        message = str(data.get("message") or "")
+        err = data.get("error")
+        if isinstance(err, dict):
+            code = code or str(err.get("code") or "")
+            if not message:
+                message = str(err.get("message") or "")
+        return code, message
+    if data is None:
+        return "", ""
+    return "", str(data)[:200]
+
+
+def _needs_portrait_rotation_fix(perf_w, perf_h, cont_w, cont_h) -> bool:
+    """U3：判定 2.5 系列「容器竖、像素横」的竖屏躺倒缺陷签名。
+
+    低代价代理判定（docs/dev/agnes_video_upstream_behavior.md §5.2）：
+    推理内部尺寸（``perf_params``）为横屏而产物容器为竖屏 → 命中。
+    任一尺寸缺失 / 方向一致 → 不命中（保守：宁可漏判，不可误转）。
+    """
+    try:
+        pw, ph, cw, ch = int(perf_w), int(perf_h), int(cont_w), int(cont_h)
+    except (TypeError, ValueError):
+        return False
+    if pw <= 0 or ph <= 0 or cw <= 0 or ch <= 0:
+        return False
+    return pw > ph and ch > cw
+
+
+def _probe_video_size(path: str) -> tuple:
+    """ffprobe 读取视频容器宽高（U3 判定用；失败返回 ``(None, None)``）。"""
+    try:
+        from core.compositor.ffmpeg_tool import resolve_binary
+        ffprobe = resolve_binary("ffprobe")
+        if not ffprobe:
+            return None, None
+        result = subprocess.run(
+            [ffprobe, "-v", "error", "-select_streams", "v:0",
+             "-show_entries", "stream=width,height", "-of", "json", path],
+            capture_output=True, text=True, timeout=60,
+        )
+        streams = json.loads(result.stdout).get("streams") or []
+        if streams:
+            return streams[0].get("width"), streams[0].get("height")
+    except Exception as e:
+        logger.debug(f"[UpstreamRotate] ffprobe failed: {e}")
+    return None, None
+
+
+class AgnesQueueFullError(RuntimeError):
+    """U1（v7.0）：队列类 503 在预算内始终没排进队——**未产生任务、未消耗配额**。
+
+    消息体只放技术事实（日志/traceback 用）；用户可见文案交给 UI 层：
+    - 前端：按 ``i18n key = error.video.queue_full`` + 参数用 22 语言渲染；
+    - 后端兜底：``core.i18n_backend`` 的 zh/en（``utils.network.describe_queue_full_error``）。
+
+    注意：``is_remote_video_failure`` 对本类返回 False（提交阶段就被拒，
+    video_id 都不存在，自然不需要「服务端确认失败才丢弃 video_id」的判定）。
+    """
+
+    def __init__(self, status: int, code: str, waited_s: int):
+        super().__init__(
+            f"Agnes video queue full (HTTP {status} · {code}) after {waited_s}s "
+            f"of retrying; no job was created"
+        )
+        self.queue_full_status = status
+        self.queue_full_code = code
+        self.queue_full_waited_s = waited_s
+
+
 class VideoTaskCancelled(RuntimeError):
     """用户停止任务导致的取消（优化路线图 0.2）。
 
@@ -88,10 +189,16 @@ def _write_json_cache(path: str, data: dict) -> None:
 
 
 class VideoOutput:
-    def __init__(self, fmt: str, ext: str, data: str):
+    def __init__(self, fmt: str, ext: str, data: str,
+                 perf_params: Optional[dict] = None,
+                 fix_rotation: bool = False):
         self.fmt = fmt
         self.ext = ext
         self.data = data
+        # U3：perf_params 为上游推理内部尺寸（非产物尺寸，勿用于产物校验）；
+        # fix_rotation 开启时保存后探测「容器竖、像素横」签名并做方向校正
+        self.perf_params = perf_params or {}
+        self.fix_rotation = fix_rotation
 
     async def save(self, path: str) -> None:
         """保存视频到 path（异步）。
@@ -108,6 +215,62 @@ class VideoOutput:
         else:
             with open(path, "wb") as f:
                 f.write(self.data if isinstance(self.data, bytes) else self.data.encode())
+        if self.fix_rotation:
+            self._maybe_fix_rotation(path)
+
+    def _maybe_fix_rotation(self, path: str) -> None:
+        """U3：2.5 系列竖屏（9:16）上游躺倒缺陷的探测式校正（默认关闭）。
+
+        判定签名见 ``_needs_portrait_rotation_fix``（容器竖 + 推理内部横）；
+        校正 = ffmpeg ``transpose=2``（逆时针 90°，实测可还原正确构图）。
+        任何一步失败保留原片并告警，不影响主流程。
+        开关：``AGNES_FIX_V25_PORTRAIT_ROTATION``（默认关闭，见计划 §三）。
+        """
+        perf = self.perf_params or {}
+        perf_w, perf_h = perf.get("width"), perf.get("height")
+        if perf_w is None or perf_h is None:
+            return
+        try:
+            cont_w, cont_h = _probe_video_size(path)
+            if not _needs_portrait_rotation_fix(perf_w, perf_h, cont_w, cont_h):
+                return
+            from core.compositor.ffmpeg_tool import resolve_binary
+            ffmpeg = resolve_binary("ffmpeg")
+            if not ffmpeg:
+                logger.warning("[UpstreamRotate] ffmpeg unavailable, keep original video")
+                return
+            tmp_path = path + ".rotated.mp4"
+            cmd = [
+                ffmpeg, "-y", "-i", path,
+                "-vf", "transpose=2",
+                "-c:v", "libx264", "-crf", "18", "-preset", "fast",
+                "-c:a", "copy",
+                tmp_path,
+            ]
+            result = subprocess.run(cmd, capture_output=True, text=True, timeout=600)
+            if result.returncode != 0:
+                logger.warning(
+                    f"[UpstreamRotate] ffmpeg failed (rc={result.returncode}): "
+                    f"{result.stderr[:300]}"
+                )
+                _silent_remove(tmp_path)
+                return
+            os.replace(tmp_path, path)
+            logger.info(
+                f"[UpstreamRotate] Fixed portrait rotation: perf={perf_w}x{perf_h} "
+                f"container={cont_w}x{cont_h} -> transposed {os.path.basename(path)}"
+            )
+        except Exception as e:
+            logger.warning(f"[UpstreamRotate] rotation fix skipped: {e}")
+
+
+def _silent_remove(path: str) -> None:
+    """尽力删除临时文件（失败静默，供 U3 校正失败清理）。"""
+    try:
+        if os.path.exists(path):
+            os.remove(path)
+    except OSError:
+        pass
 
 
 class AgnesVideoAPI:
@@ -271,7 +434,7 @@ class AgnesVideoAPI:
             return 961   # 480p tier
 
     def _get_frame_config(self, duration: Optional[int] = None,
-                          width: int = 1152, height: int = 768) -> tuple:
+                          width: int = 1280, height: int = 720) -> tuple:
         d = duration or self.default_duration
         max_nf = self._get_max_frames(width, height)
         if d in DURATION_PRESETS:
@@ -351,6 +514,9 @@ class AgnesVideoAPI:
                 resp.raise_for_status()
                 result = resp.json()
                 status = result.get("status", "")
+                # U5：progress 与 internal_progress 实测互相矛盾（可 0 vs 100）、
+                # started_at 可为 null——仅作日志展示，任何逻辑不得依赖其数值
+                # （自适应间隔 _adaptive_poll_interval 也只按次数推进）。
                 progress = result.get("progress", 0)
                 poll_count += 1
                 consecutive_failures = 0  # reset on success
@@ -366,15 +532,23 @@ class AgnesVideoAPI:
                     return result
 
                 if status in ("failed", "FAILED"):
-                    err = result.get("error") or "unknown error"
-                    error_msg = f"Video generation failed: {err}"
+                    # U2：error 是对象 {code, message}，统一提取而非字面量化
+                    code, message = _upstream_error(result)
+                    if not message:
+                        message = str(result.get("error") or "unknown error")
+                    error_msg = f"Video generation failed: {message}"
+                    if code:
+                        error_msg += f" (code={code})"
                     collect_error(
                         "video", "poll_task",
                         prompt=curl_cmd,
                         error_type="VideoFailed",
-                        error_message=error_msg,
+                        error_message=message,
                         response_body=resp.text,
-                        extra={"video_id": video_id[:16], "status": status},
+                        extra={
+                            "video_id": video_id[:16], "status": status,
+                            "upstream_code": code,
+                        },
                     )
                     raise RuntimeError(error_msg)
             except (requests.exceptions.RequestException, asyncio.TimeoutError) as e:
@@ -405,12 +579,18 @@ class AgnesVideoAPI:
             # 优化路线图 1.3：自适应轮询间隔（20s 起步，每 5 次 +5s，上限 interval）
             await asyncio.sleep(_adaptive_poll_interval(interval, poll_count))
 
-    async def _submit_with_retry(self, payload: dict, mode_desc: str) -> str:
+    async def _submit_with_retry(self, payload: dict, mode_desc: str,
+                                 progress_callback=None) -> str:
         frame_reductions_left = 2  # allow up to 2 frame-count reductions on 400
         attempt = 0
         rotations = 0
         ring = get_key_ring()
         max_rotations = len(ring) * self.max_retries
+        # U1：队列类 503（video_queue_full / fail_to_fetch_task）独立退避轨道
+        # —— 不计入普通 5xx 的 max_retries 配额，预算单独可配
+        queue_started = None   # 首次命中时的时间戳（time.monotonic）
+        queue_deadline = None  # queue_started + 预算秒数
+        queue_retries = 0
         while attempt < self.max_retries:
             if self.shutdown_event and self.shutdown_event.is_set():
                 raise VideoTaskCancelled("Video generation cancelled by user")
@@ -468,20 +648,100 @@ class AgnesVideoAPI:
                     continue
 
                 if resp.status_code >= 500:
+                    # U2：解析响应体的 code/message（此前统一丢成 "server error"）
+                    code, message = _upstream_error(resp)
+
+                    # U1：队列满走独立退避轨道（不计入普通 5xx 配额）
+                    if code in _QUEUE_FULL_CODES:
+                        if queue_deadline is None:
+                            from core.config import get_settings
+                            budget = get_settings().agnes_video_queue_retry_seconds
+                            queue_started = time.monotonic()
+                            queue_deadline = queue_started + budget
+                            logger.warning(
+                                f"[AgnesVideo] {mode_desc}: Agnes video queue full "
+                                f"(HTTP {resp.status_code} · {code}), entering queue "
+                                f"retry track (budget {budget}s)"
+                            )
+                        waited = time.monotonic() - queue_started
+                        if time.monotonic() >= queue_deadline:
+                            collect_error(
+                                "video", "submit_video",
+                                prompt=payload.get("prompt", ""),
+                                error_type=f"QueueFull_{code}",
+                                error_message=message or f"HTTP {resp.status_code}: {code}",
+                                status_code=resp.status_code,
+                                response_body=resp.text,
+                                retry_count=queue_retries,
+                                extra={
+                                    "mode": mode_desc, "upstream_code": code,
+                                    "waited_s": int(waited),
+                                },
+                            )
+                            # 结构化异常：用户可见文案由 UI 层按 22 语言渲染，
+                            # 此处只保留技术事实（含 HTTP 码 / body code / 等待时长）
+                            raise AgnesQueueFullError(
+                                status=resp.status_code, code=code, waited_s=int(waited),
+                            )
+                        delay = _QUEUE_RETRY_BASE_DELAY + random.uniform(0, _QUEUE_RETRY_JITTER)
+                        queue_retries += 1
+                        logger.warning(
+                            f"[AgnesVideo] Agnes video queue full on {mode_desc} "
+                            f"(HTTP {resp.status_code} · {code}), queue retry "
+                            f"#{queue_retries} (waited {waited:.0f}s) in {delay:.0f}s..."
+                        )
+                        collect_error(
+                            "video", "submit_video",
+                            prompt=payload.get("prompt", ""),
+                            error_type=f"QueueFull_{code}",
+                            error_message=message or f"HTTP {resp.status_code}: {code}",
+                            status_code=resp.status_code,
+                            response_body=resp.text,
+                            retry_count=queue_retries,
+                            extra={
+                                "mode": mode_desc, "upstream_code": code,
+                                "waited_s": int(waited),
+                            },
+                        )
+                        if progress_callback:
+                            try:
+                                # (stage, payload)：payload 带原样报错（HTTP 码 + body code）
+                                # 与等待信息，供前端拼出「Agnes 队列已满 + 原始报错 + 错峰建议」
+                                progress_callback("queue_full", {
+                                    "attempt": queue_retries,
+                                    "waited_s": waited,
+                                    "status": resp.status_code,
+                                    "code": code,
+                                    "message": message,
+                                })
+                            except Exception:
+                                logger.debug(
+                                    "[AgnesVideo] queue progress callback failed",
+                                    exc_info=True,
+                                )
+                        await asyncio.sleep(delay)
+                        continue
+
+                    # 普通 5xx：沿用 5 次退避配额
                     delay = self.retry_base_delay * (attempt + 1)
                     logger.warning(
-                        f"[AgnesVideo] {resp.status_code} server error on {mode_desc}, "
+                        f"[AgnesVideo] {resp.status_code} server error on {mode_desc}"
+                        f"{f' (code={code})' if code else ''}, "
                         f"retry {attempt + 1}/{self.max_retries} in {delay:.0f}s..."
                     )
+                    error_message = (
+                        f"HTTP {resp.status_code}: {message}"
+                        if message else f"HTTP {resp.status_code}: server error"
+                    )
                     collect_error(
                         "video", "submit_video",
                         prompt=payload.get("prompt", ""),
                         error_type=f"HTTP{resp.status_code}",
-                        error_message=f"HTTP {resp.status_code}: server error",
+                        error_message=error_message,
                         status_code=resp.status_code,
                         response_body=resp.text,
                         retry_count=attempt + 1,
-                        extra={"mode": mode_desc},
+                        extra={"mode": mode_desc, "upstream_code": code},
                     )
                     await asyncio.sleep(delay)
                     attempt += 1
@@ -563,8 +823,8 @@ class AgnesVideoAPI:
         prompt: str,
         reference_image_paths: List[str] = [],
         duration: Optional[int] = None,
-        width: int = 1152,
-        height: int = 768,
+        width: int = 1280,
+        height: int = 720,
         seed: Optional[int] = None,
         negative_prompt: Optional[str] = None,
         progress_callback=None,
@@ -578,6 +838,7 @@ class AgnesVideoAPI:
             height=height,
             seed=seed,
             negative_prompt=negative_prompt,
+            progress_callback=progress_callback,
             **kwargs,
         )
         return await self.wait_for_video(video_id, progress_callback)
@@ -587,10 +848,11 @@ class AgnesVideoAPI:
         prompt: str,
         reference_image_paths: List[str] = [],
         duration: Optional[int] = None,
-        width: int = 1152,
-        height: int = 768,
+        width: int = 1280,
+        height: int = 720,
         seed: Optional[int] = None,
         negative_prompt: Optional[str] = None,
+        progress_callback=None,
         **kwargs,
     ) -> str:
         # 2.5 系列模型（v6.2）：新参数协议（mode/seconds/size/aspect_ratio）
@@ -602,6 +864,7 @@ class AgnesVideoAPI:
                 width=width,
                 height=height,
                 seed=seed,
+                progress_callback=progress_callback,
                 **kwargs,
             )
         num_frames, frame_rate = self._get_frame_config(duration, width, height)
@@ -643,38 +906,29 @@ class AgnesVideoAPI:
 
         logger.info(f"[AgnesVideo] {mode_desc}: {prompt[:80]}...")
 
-        video_id = await self._submit_with_retry(payload, mode_desc)
+        video_id = await self._submit_with_retry(payload, mode_desc, progress_callback)
         logger.info(f"[AgnesVideo] Video submitted: {video_id[:20]}...")
         return video_id
 
     @staticmethod
     def _width_height_to_aspect_ratio(width: int, height: int) -> str:
-        """将像素宽高映射到最接近的 2.5 系列 aspect_ratio 枚举。
+        """将像素宽高映射到 2.5 系列 aspect_ratio 枚举（委托 ``core.config``）。
 
-        找不到精确比例时取误差最小的档位（默认 16:9）。
+        映射规则已上提到 ``core.config.width_height_to_aspect_ratio``，供回归
+        校验脚本共用（保证「提交」与「校验」同一套规则）；此方法保留为类内
+        调用入口，行为与上提前完全一致。
         """
-        if not width or not height:
-            return "16:9"
-        ratio = width / height
-        best = "16:9"
-        best_dist = float("inf")
-        for ar in VIDEO_ASPECT_RATIOS:
-            w, h = ar.split(":")
-            target = int(w) / int(h)
-            dist = abs(ratio - target)
-            if dist < best_dist:
-                best_dist = dist
-                best = ar
-        return best
+        return width_height_to_aspect_ratio(width, height)
 
     async def _submit_video_v25(
         self,
         prompt: str,
         reference_image_paths: List[str],
         duration: Optional[int] = None,
-        width: int = 1152,
-        height: int = 768,
+        width: int = 1280,
+        height: int = 720,
         seed: Optional[int] = None,
+        progress_callback=None,
         **kwargs,
     ) -> str:
         """2.5 / 2.5-flash 新协议提交：mode / seconds / size / aspect_ratio。
@@ -727,14 +981,15 @@ class AgnesVideoAPI:
             mode_desc = "text-to-video"
 
         logger.info(f"[AgnesVideo] {mode_desc}: {prompt[:80]}...")
-        video_id = await self._submit_with_retry(payload, mode_desc)
+        video_id = await self._submit_with_retry(payload, mode_desc, progress_callback)
         logger.info(f"[AgnesVideo] Video submitted: {video_id[:20]}...")
         return video_id
 
     async def wait_for_video(self, video_id: str, progress_callback=None) -> VideoOutput:
         # 1.2：轮询总超时可经 AGNES_VIDEO_POLL_TIMEOUT 配置（3.5 RuntimeSettings 收敛）
         from core.config import get_settings
-        poll_timeout = get_settings().agnes_video_poll_timeout
+        settings = get_settings()
+        poll_timeout = settings.agnes_video_poll_timeout
         final = await self._poll_task(
             video_id, progress_callback=progress_callback,
             max_poll_duration=poll_timeout,
@@ -753,4 +1008,14 @@ class AgnesVideoAPI:
                 raise RuntimeError(f"Agnes video: no URL in completed task: {final}")
 
         logger.info(f"[AgnesVideo] Done: {video_url[:80]}...")
-        return VideoOutput(fmt="url", ext="mp4", data=video_url)
+        # U3：携带推理内部尺寸 + 校正开关（默认关闭；仅 2.5 系列探测「容器竖、
+        # 像素横」签名后 ffmpeg transpose=2 校正，详见计划 §三）
+        fix_rotation = (
+            settings.agnes_fix_v25_portrait_rotation
+            and is_v25_video_model(self.model)
+        )
+        return VideoOutput(
+            fmt="url", ext="mp4", data=video_url,
+            perf_params=final.get("perf_params") or {},
+            fix_rotation=fix_rotation,
+        )