feat: add POST /tts/preview endpoint for synchronous TTS preview (#1496)

Co-authored-by: xiaoxia <dev@xiaoxiajianji.com>
Co-committed-by: xiaoxia <dev@xiaoxiajianji.com>

apps/api/app/api/routes/generation_preview.py

@@ -264,6 +264,34 @@ def create_preview_generation_task(
     if not video_ratio and request.template_id:
         video_ratio = _infer_video_ratio_from_template(request.template_id, db, user_id)
 
+    # 根据 video_ratio 计算输出分辨率（默认竖屏 1080x1920）
+    output_width, output_height = 1080, 1920
+    if video_ratio:
+        parts = video_ratio.split(":")
+        if len(parts) == 2:
+            try:
+                w, h = int(parts[0]), int(parts[1])
+                base = 1920
+                if w < h:
+                    # 竖屏
+                    output_width = round(base * w / h)
+                    output_height = base
+                else:
+                    # 横屏
+                    output_width = base
+                    output_height = round(base * h / w)
+                # 对齐到偶数
+                output_width = output_width - output_width % 2
+                output_height = output_height - output_height % 2
+            except (ValueError, ZeroDivisionError):
+                output_width, output_height = 1080, 1920
+    resolution = f"{output_width}x{output_height}"
+
+    logger.info(
+        "[预览生成] 分辨率: video_ratio=%s → %s (%dx%d)",
+        video_ratio, resolution, output_width, output_height,
+    )
+
     # 从模板读取 editing_mode / mode 作为 strategy_id（渲染 pipeline 的 mode 参数）
     strategy_id = _resolve_strategy_id_from_template(request.template_id, db, user_id)
 
@@ -287,12 +315,14 @@ def create_preview_generation_task(
                 asset_select_mode="",
                 batch_id="",
                 video_title=request.video_title,
-                resolution="",
+                resolution=resolution,
                 bgm_config=request.bgm_config or {},
                 auto_retry_enabled=False,
                 auto_retry_max=0,
                 is_preview=True,
                 title_config=title_config,
+                output_width=output_width,
+                output_height=output_height,
             )
         )
     except ValueError as e:

apps/api/app/api/routes/tts.py

@@ -20,6 +20,8 @@ from app.schemas.tts import (
     SaveToLibraryRequest,
     SaveToLibraryResponse,
     TTSJobResponse,
+    TTSPreviewRequest,
+    TTSPreviewResponse,
     TTSStatusResponse,
     TTSSynthesizeRequest,
     TTSSynthesizeResponse,
@@ -31,7 +33,7 @@ from packages.adapters.sqlalchemy_impl.tts_job_repository import (
     SQLAlchemyTTSJobRepository,
 )
 from packages.adapters.sqlalchemy_impl.voice_library_repository import SQLAlchemyVoiceLibraryRepository
-from packages.application.cosyvoice_service import CosyVoiceService
+from packages.application.cosyvoice_service import CosyVoiceError, CosyVoiceService
 from packages.application.tts_job.streaming_service import TTSStreamingService
 from packages.application.tts_job.use_cases import (
     CreateTTSJobUseCase,
@@ -373,6 +375,40 @@ def save_tts_job_to_library(
     )
 
 
+
+@router.post("/preview", response_model=TTSPreviewResponse)
+def preview_tts(
+    request: TTSPreviewRequest,
+    authenticated_user: AuthenticatedUser = Depends(get_current_user),
+    cosyvoice_service: CosyVoiceService = Depends(get_cosyvoice_service),
+) -> TTSPreviewResponse:
+    """TTS 预览（试听）——同步合成，立即返回音频 URL。
+
+    用于前端预览配音效果，限制文本长度 200 字以内。
+    """
+    try:
+        result = cosyvoice_service.synthesize_speech(
+            text=request.text,
+            voice_id=request.voice_id,
+            speed=request.speed,
+        )
+    except CosyVoiceError as e:
+        raise HTTPException(
+            status_code=status.HTTP_502_BAD_GATEWAY,
+            detail=f"TTS 合成失败: {e}",
+        ) from e
+    except ValueError as e:
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(e),
+        ) from e
+
+    return TTSPreviewResponse(
+        audio_url=result.audio_url,
+        duration=result.duration if result.duration and result.duration > 0 else None,
+    )
+
+
 @router.websocket("/ws/tts/stream")
 async def tts_websocket_stream(
     websocket: WebSocket,

apps/api/app/schemas/tts.py

@@ -101,3 +101,19 @@ class SaveToLibraryResponse(BaseModel):
     voice_id: str
     voice_name: str
     status: str
+
+
+class TTSPreviewRequest(BaseModel):
+    """TTS 预览（试听）请求。"""
+
+    text: str = Field(..., min_length=1, max_length=200, description="合成文本，限制 200 字")
+    voice_id: str = Field(..., min_length=1, description="音色 ID")
+    speed: float = Field(1.0, ge=0.5, le=2.0, description="语速")
+    pitch: float = Field(1.0, ge=0.5, le=2.0, description="音调（预留，当前未使用）")
+
+
+class TTSPreviewResponse(BaseModel):
+    """TTS 预览（试听）响应。"""
+
+    audio_url: str = Field(..., description="合成音频 URL")
+    duration: Optional[float] = Field(default=None, description="音频时长（秒）")

apps/web/src/pages/generate/GeneratePage.tsx

@@ -1,21 +1,18 @@
 /**
- * 智能剪辑页面 — 服务器渲染预览架构
+ * 智能剪辑页面 — 前端实时预览架构
  * 7 步向导：选择模板 → 素材 → 配音 → 标题 → 预览 → 封面 → 确认生成
  * 左右布局：左侧 generate-form + 右侧 generate-preview
  *
  * 架构：
- * - Step4+ 右侧预览面板自动创建服务器预览渲染任务（POST /generation/preview）
- * - 轮询完成后播放服务器渲染的真实视频（<video> 标签）
- * - 标题样式编辑时 CSS 层实时叠加预览
- * - 素材/配音/BGM 变更自动重新渲染；标题变更标记 stale
- * - 点"确认生成"时走 confirm 路径，成品就是预览视频本身，100% 一致
+ * - Step4+ 右侧预览面板使用 FrontendPreviewPlayer 实时播放素材片段
+ * - 标题样式编辑时 CSS 层实时叠加预览，所见即所得
+ * - 点"确认生成"时调用 createGenerationTask 创建一次服务器渲染任务
  */
-import React, { useMemo, useCallback } from "react"
+import React, { useMemo, useState, useEffect, useRef } from "react"
 import { Modal, message } from "antd"
 import { useNavigate } from "react-router-dom"
 import type { VoiceClone } from "@/api/voice-clone"
 import { useCloneProgress } from "@/hooks/useCloneProgress"
-import { calculateResolution } from "./utils/calculateResolution"
 import CloneModal from "@/components/voice/CloneModal"
 import GenerateHeader from "./components/GenerateHeader"
 import {
@@ -24,15 +21,15 @@ import {
 } from "./utils/calculateTotalVideoDuration"
 import GenerateStepsBar from "./components/GenerateStepsBar"
 import GenerateResultPanel from "./components/GenerateResultPanel"
-import PreviewVideoPanel from "./components/PreviewVideoPanel"
+import FrontendPreviewPlayer from "./components/FrontendPreviewPlayer"
 import GenerateStepContent from "./components/GenerateStepContent"
 import GenerateStepActions from "./components/GenerateStepActions"
 import { useGenerateFormState } from "./hooks/useGenerateFormState"
 import { useStepNavigation } from "./hooks/useStepNavigation"
 import { useGenerateVideo } from "./hooks/useGenerateVideo"
 import { usePreviewAssets } from "./hooks/usePreviewAssets"
-import { useServerPreview } from "./hooks/useServerPreview"
 import { useTitleStyleUpdaters } from "./hooks/useStep4Title/useTitleStyleUpdaters"
+import { previewTts } from "@/api/tts"
 import "./generate.css"
 
 const GeneratePage: React.FC = () => {
@@ -90,6 +87,42 @@ const GeneratePage: React.FC = () => {
     onTitleSettingsChange: setTitleSettings,
   })
 
+  /* ── 配音预览音频（TTS 试听）── */
+  const [previewVoiceAudioUrl, setPreviewVoiceAudioUrl] = useState<string | null>(null)
+  const ttsAbortRef = useRef<AbortController | null>(null)
+
+  useEffect(() => {
+    const voiceId = selectedClonedVoice || selectedVoice
+    if (!voiceId || !titleSettings.title) {
+      setPreviewVoiceAudioUrl(null)
+      return
+    }
+    ttsAbortRef.current?.abort()
+    const controller = new AbortController()
+    ttsAbortRef.current = controller
+    let cancelled = false
+    previewTts({
+      text: titleSettings.title,
+      voice_id: voiceId,
+    })
+      .then((res) => {
+        if (!cancelled && res.audio_url) {
+          setPreviewVoiceAudioUrl(res.audio_url)
+        }
+      })
+      .catch((err) => {
+        if (!cancelled) {
+          console.warn("[预览配音生成失败]", err)
+          setPreviewVoiceAudioUrl(null)
+        }
+      })
+    return () => {
+      cancelled = true
+      controller.abort()
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [selectedVoice, selectedClonedVoice, titleSettings.title])
+
   /* ── 克隆声音 ── */
   const { clones: clonedVoices, addClone, hasProcessing } = useCloneProgress()
 
@@ -120,10 +153,7 @@ const GeneratePage: React.FC = () => {
     [bgm, currentTemplate],
   )
 
-  /* ── 输出分辨率（根据视频比例计算） ── */
-  const resolution = useMemo(() => calculateResolution(videoRatio), [videoRatio])
-
-  /* ── 加载素材详情（仅用于配音时长校验，不用于播放） ── */
+  /* ── 加载素材详情（供前端预览播放器使用 + 配音时长校验） ── */
   const previewAssetsEnabled = previewAssetIds.length > 0
   const { assets: previewAssets } = usePreviewAssets(previewAssetIds, previewAssetsEnabled)
 
@@ -134,74 +164,7 @@ const GeneratePage: React.FC = () => {
     return estimateTotalVideoDuration(currentTemplate ?? undefined)
   }, [previewAssets, currentTemplate])
 
-  /* ── 解析配音 ID ── */
-  const voiceLibraryId = useMemo(
-    () => (voiceMode === "clone" ? selectedClonedVoice || "" : selectedVoice || ""),
-    [voiceMode, selectedClonedVoice, selectedVoice],
-  )
-
-  /* ── 构建服务器预览请求参数 ── */
-  const buildPreviewRequest = useCallback(() => {
-    return {
-      template_id: selectedTemplate,
-      asset_ids: previewAssetIds,
-      duration: duration || 30,
-      video_ratio: videoRatio,
-      output_width: resolution.width,
-      output_height: resolution.height,
-      ...(voiceLibraryId ? { voice_library_id: voiceLibraryId } : {}),
-      bgm_config: {
-        enabled: bgm !== false,
-        ...(bgmConfig.music_id ? { preset_id: bgmConfig.music_id } : {}),
-      },
-      ...(titleSettings.title
-        ? {
-            title_config: {
-              text: titleSettings.title,
-              font: titleSettings.font,
-              font_size: titleSettings.size,
-              font_color: titleSettings.color,
-              position: titleSettings.position,
-              bold: titleSettings.bold,
-              stroke: titleSettings.stroke,
-              shadow: titleSettings.shadow,
-            },
-          }
-        : {}),
-    }
-  }, [
-    selectedTemplate,
-    previewAssetIds,
-    duration,
-    videoRatio,
-    resolution,
-    voiceLibraryId,
-    bgm,
-    bgmConfig,
-    titleSettings,
-  ])
-
-  /* ── 服务器预览 ── */
-  const serverPreviewEnabled = currentStep >= 4 && !!selectedTemplate && previewAssetIds.length > 0
-
-  const {
-    status: previewStatus,
-    videoUrl: previewVideoUrl,
-    progress: previewProgress,
-    error: previewError,
-    triggerPreview,
-  } = useServerPreview({
-    enabled: serverPreviewEnabled,
-    buildRequest: buildPreviewRequest,
-    onPreviewTaskCreated: (taskId, planId) => {
-      setPreviewTaskId(taskId)
-      if (planId) setStoredSourceEditPlanId(planId)
-    },
-  })
-
   /* ── 步骤导航 ── */
-  // Step5 需要服务器预览完成才能前进
-  const previewReady = previewStatus === "ready"
   const { goNext, goPrev } = useStepNavigation({
     currentStep,
     setCurrentStep,
@@ -210,7 +173,6 @@ const GeneratePage: React.FC = () => {
     selectedMaterials,
     smartSelectedIds,
     titleSettings,
-    previewReady,
   })
 
   /* ── 视频生成核心逻辑 ── */
@@ -250,11 +212,6 @@ const GeneratePage: React.FC = () => {
     },
   })
 
-  /* ── 手动重新预览（标题变更后或失败重试） ── */
-  const handleRetryPreview = useCallback(() => {
-    triggerPreview()
-  }, [triggerPreview])
-
   /* ================================================================
      渲染
      ================================================================ */
@@ -320,8 +277,6 @@ const GeneratePage: React.FC = () => {
             onRetry={handleRetryGenerate}
             onDismissError={handleDismissError}
             presetVoices={presetVoices}
-            previewStatus={previewStatus}
-            onRetryPreview={handleRetryPreview}
           />
 
           <GenerateStepActions
@@ -337,16 +292,24 @@ const GeneratePage: React.FC = () => {
 
         {/* ════ 右侧：预览 + 结果 ════ */}
         <div className="xx-generate-right-col">
-          {currentStep >= 4 && (
-            <PreviewVideoPanel
-              previewStatus={previewStatus}
-              videoUrl={previewVideoUrl}
-              progress={previewProgress}
-              error={previewError}
-              onRetry={handleRetryPreview}
+          {currentStep >= 4 && !!currentTemplate && (
+            <FrontendPreviewPlayer
+              assets={previewAssets}
+              template={currentTemplate}
               videoRatio={videoRatio}
-              titleSettings={titleSettings}
-              assetCount={previewAssetIds.length}
+              ready={previewAssets.length > 0}
+              voiceAudioUrl={previewVoiceAudioUrl || undefined}
+              titleSettings={{
+                title: titleSettings.title,
+                size: titleSettings.size,
+                font: titleSettings.font,
+                color: titleSettings.color,
+                position: titleSettings.position as "top" | "center" | "bottom",
+                bold: titleSettings.bold,
+                italic: titleSettings.italic,
+                stroke: titleSettings.stroke,
+                shadow: titleSettings.shadow,
+              }}
             />
           )}
           {currentStep >= 6 && (

apps/web/src/pages/generate/components/FrontendPreviewPlayer.tsx

@@ -277,20 +277,29 @@ const FrontendPreviewPlayer: React.FC<FrontendPreviewPlayerProps> = ({
   if (!ready || !assets.length) {
     return (
       <div
-        className="xx-preview-empty"
         style={{
-          position: "absolute",
-          inset: 0,
+          position: "relative",
+          width: "100%",
+          maxWidth: 280,
+          aspectRatio: "9 / 16",
+          background: "#0a0a0a",
+          borderRadius: 24,
+          overflow: "hidden",
+          boxShadow:
+            "0 4px 6px -1px rgba(0,0,0,0.3), 0 20px 50px -12px rgba(0,0,0,0.5), inset 0 0 0 1px rgba(255,255,255,0.06)",
           display: "flex",
           flexDirection: "column",
           alignItems: "center",
           justifyContent: "center",
-          zIndex: 1,
         }}
       >
-        <SoundOutlined style={{ fontSize: 48, color: "var(--text-tertiary)", marginBottom: 12 }} />
-        <p className="xx-preview-empty-title">准备预览素材...</p>
-        <p className="xx-preview-empty-desc">加载素材后即可预览播放</p>
+        <SoundOutlined style={{ fontSize: 40, color: "rgba(255,255,255,0.3)", marginBottom: 12 }} />
+        <p style={{ color: "rgba(255,255,255,0.6)", fontSize: 14, margin: "0 0 4px" }}>
+          准备预览素材...
+        </p>
+        <p style={{ color: "rgba(255,255,255,0.35)", fontSize: 12, margin: 0 }}>
+          加载素材后即可预览播放
+        </p>
       </div>
     )
   }
@@ -300,31 +309,48 @@ const FrontendPreviewPlayer: React.FC<FrontendPreviewPlayerProps> = ({
     const showDecodeError = forceVideoFallback && canvasState.hasDecodeError
     return (
       <div
-        className="xx-preview-empty"
         style={{
-          position: "absolute",
-          inset: 0,
+          position: "relative",
+          width: "100%",
+          maxWidth: 280,
+          aspectRatio: "9 / 16",
+          background: "#0a0a0a",
+          borderRadius: 24,
+          overflow: "hidden",
+          boxShadow:
+            "0 4px 6px -1px rgba(0,0,0,0.3), 0 20px 50px -12px rgba(0,0,0,0.5), inset 0 0 0 1px rgba(255,255,255,0.06)",
           display: "flex",
           flexDirection: "column",
           alignItems: "center",
           justifyContent: "center",
-          zIndex: 1,
+          padding: 24,
         }}
       >
         {isBuffering ? (
           <>
-            <LoadingOutlined style={{ fontSize: 48, color: "#fff", marginBottom: 12 }} spin />
-            <p style={{ color: "rgba(255,255,255,0.8)" }}>加载中...</p>
+            <LoadingOutlined style={{ fontSize: 40, color: "#fff", marginBottom: 12 }} spin />
+            <p style={{ color: "rgba(255,255,255,0.8)", fontSize: 14, margin: 0 }}>加载中...</p>
           </>
         ) : showDecodeError ? (
           <>
-            <PlayCircleOutlined style={{ fontSize: 48, color: "#ef4444", marginBottom: 12 }} />
-            <p className="xx-preview-empty-title" style={{ color: "rgba(255,255,255,0.9)" }}>
+            <PlayCircleOutlined style={{ fontSize: 40, color: "#ef4444", marginBottom: 12 }} />
+            <p
+              style={{
+                color: "rgba(255,255,255,0.9)",
+                fontSize: 14,
+                margin: "0 0 4px",
+                fontWeight: 500,
+              }}
+            >
               视频解码失败
             </p>
             <p
-              className="xx-preview-empty-desc"
-              style={{ color: "rgba(255,255,255,0.6)", maxWidth: 300, textAlign: "center" }}
+              style={{
+                color: "rgba(255,255,255,0.5)",
+                fontSize: 12,
+                margin: 0,
+                textAlign: "center",
+              }}
             >
               {canvasState.errorMessage || "当前浏览器不支持该视频编码格式，请刷新重试"}
             </p>
@@ -332,10 +358,14 @@ const FrontendPreviewPlayer: React.FC<FrontendPreviewPlayerProps> = ({
         ) : (
           <>
             <PlayCircleOutlined
-              style={{ fontSize: 48, color: "var(--text-tertiary)", marginBottom: 12 }}
+              style={{ fontSize: 40, color: "rgba(255,255,255,0.3)", marginBottom: 12 }}
             />
-            <p className="xx-preview-empty-title">暂无可播放素材</p>
-            <p className="xx-preview-empty-desc">请先在左侧选择素材</p>
+            <p style={{ color: "rgba(255,255,255,0.6)", fontSize: 14, margin: "0 0 4px" }}>
+              暂无可播放素材
+            </p>
+            <p style={{ color: "rgba(255,255,255,0.35)", fontSize: 12, margin: 0 }}>
+              请先在左侧选择素材
+            </p>
           </>
         )}
       </div>
@@ -343,7 +373,19 @@ const FrontendPreviewPlayer: React.FC<FrontendPreviewPlayerProps> = ({
   }
 
   return (
-    <>
+    <div
+      style={{
+        position: "relative",
+        width: "100%",
+        maxWidth: 280,
+        aspectRatio: "9 / 16",
+        background: "#0a0a0a",
+        borderRadius: 24,
+        overflow: "hidden",
+        boxShadow:
+          "0 4px 6px -1px rgba(0,0,0,0.3), 0 20px 50px -12px rgba(0,0,0,0.5), inset 0 0 0 1px rgba(255,255,255,0.06)",
+      }}
+    >
       {/* ── Canvas 渲染层（WebCodecs 路径） ── */}
       {effectiveUseWebCodecs && (
         <div
@@ -392,54 +434,114 @@ const FrontendPreviewPlayer: React.FC<FrontendPreviewPlayerProps> = ({
           />
         ))}
 
-      {/* 播放按钮 */}
+      {/* 标题CSS叠加层 — video fallback 路径也要渲染 */}
+      {titleSettings?.title && (
+        <div
+          style={{
+            position: "absolute",
+            left: 0,
+            right: 0,
+            zIndex: 5,
+            display: "flex",
+            justifyContent: "center",
+            pointerEvents: "none",
+            ...(titleSettings.position === "top"
+              ? { top: "10%" }
+              : titleSettings.position === "center"
+                ? { top: "50%", transform: "translateY(-50%)" }
+                : { bottom: "15%" }),
+          }}
+        >
+          <span
+            style={{
+              fontSize: titleSettings.size,
+              fontFamily: titleSettings.font || "思源黑体",
+              color: titleSettings.color || "#ffffff",
+              fontWeight: titleSettings.bold ? 700 : 400,
+              fontStyle: titleSettings.italic ? "italic" : "normal",
+              textShadow: [
+                titleSettings.shadow ? "0 2px 8px rgba(0,0,0,0.7)" : undefined,
+                titleSettings.stroke
+                  ? "1px 1px 0 rgba(0,0,0,0.5), -1px -1px 0 rgba(0,0,0,0.5), 1px -1px 0 rgba(0,0,0,0.5), -1px 1px 0 rgba(0,0,0,0.5)"
+                  : undefined,
+                "0 1px 3px rgba(0,0,0,0.4)",
+              ]
+                .filter(Boolean)
+                .join(", "),
+              maxWidth: "90%",
+              textAlign: "center",
+              lineHeight: 1.3,
+              wordBreak: "break-word",
+            }}
+          >
+            {titleSettings.title}
+          </span>
+        </div>
+      )}
+
+      {/* 中央播放按钮 */}
       {!isPlaying && (
         <button
-          className="xx-preview-play-btn"
           onClick={handleTogglePlay}
           style={{
             position: "absolute",
             top: "50%",
             left: "50%",
             transform: "translate(-50%, -50%)",
-            background: "rgba(0,0,0,0.5)",
-            border: "none",
+            background: "rgba(0,0,0,0.45)",
+            backdropFilter: "blur(12px)",
+            WebkitBackdropFilter: "blur(12px)",
+            border: "1px solid rgba(255,255,255,0.15)",
             borderRadius: "50%",
-            width: 56,
-            height: 56,
+            width: 52,
+            height: 52,
             cursor: "pointer",
             display: "flex",
             alignItems: "center",
             justifyContent: "center",
             color: "#fff",
-            fontSize: 28,
+            fontSize: 26,
             zIndex: 10,
+            transition: "transform 0.2s ease, background 0.2s ease",
+            boxShadow: "0 4px 20px rgba(0,0,0,0.4)",
+          }}
+          onMouseEnter={(e) => {
+            e.currentTarget.style.transform = "translate(-50%, -50%) scale(1.08)"
+            e.currentTarget.style.background = "rgba(0,0,0,0.6)"
+          }}
+          onMouseLeave={(e) => {
+            e.currentTarget.style.transform = "translate(-50%, -50%) scale(1)"
+            e.currentTarget.style.background = "rgba(0,0,0,0.45)"
           }}
         >
           <PlayCircleOutlined />
         </button>
       )}
 
-      {/* 片段指示器 */}
+      {/* 片段指示器 — 右上角胶囊 */}
       <div
         style={{
           position: "absolute",
           top: 8,
-          left: 8,
-          background: "rgba(0,0,0,0.6)",
-          color: "#fff",
-          fontSize: 11,
+          right: 8,
+          background: "rgba(0,0,0,0.45)",
+          backdropFilter: "blur(8px)",
+          WebkitBackdropFilter: "blur(8px)",
+          color: "rgba(255,255,255,0.9)",
+          fontSize: 10,
+          fontWeight: 500,
           padding: "2px 8px",
-          borderRadius: 4,
+          borderRadius: 999,
           zIndex: 10,
+          border: "1px solid rgba(255,255,255,0.1)",
+          letterSpacing: 0.3,
         }}
       >
-        {`片段 ${videoCurrentSegIdx + 1}/${segments.length}`}
+        {`${videoCurrentSegIdx + 1} / ${segments.length}`}
       </div>
 
-      {/* 控制条 */}
+      {/* 控制条 — 手机风格毛玻璃 */}
       <div
-        className="xx-preview-controls"
         style={{
           position: "absolute",
           bottom: 0,
@@ -447,23 +549,36 @@ const FrontendPreviewPlayer: React.FC<FrontendPreviewPlayerProps> = ({
           right: 0,
           display: "flex",
           alignItems: "center",
-          gap: 8,
-          padding: "8px 12px",
-          background: "linear-gradient(transparent, rgba(0,0,0,0.6))",
+          gap: 10,
+          padding: "12px 16px 16px",
+          background: "linear-gradient(transparent, rgba(0,0,0,0.7))",
+          backdropFilter: "blur(4px)",
+          WebkitBackdropFilter: "blur(4px)",
           zIndex: 10,
         }}
       >
         <button
           onClick={handleTogglePlay}
           style={{
-            background: "none",
+            background: "rgba(255,255,255,0.15)",
             border: "none",
             color: "#fff",
-            fontSize: 18,
+            fontSize: 16,
             cursor: "pointer",
-            padding: 4,
+            width: 32,
+            height: 32,
+            borderRadius: "50%",
             display: "flex",
             alignItems: "center",
+            justifyContent: "center",
+            flexShrink: 0,
+            transition: "background 0.15s",
+          }}
+          onMouseEnter={(e) => {
+            e.currentTarget.style.background = "rgba(255,255,255,0.25)"
+          }}
+          onMouseLeave={(e) => {
+            e.currentTarget.style.background = "rgba(255,255,255,0.15)"
           }}
         >
           {isPlaying ? <PauseCircleOutlined /> : <PlayCircleOutlined />}
@@ -471,10 +586,11 @@ const FrontendPreviewPlayer: React.FC<FrontendPreviewPlayerProps> = ({
 
         <span
           style={{
-            fontSize: 12,
-            color: "rgba(255,255,255,0.8)",
-            minWidth: 80,
+            fontSize: 11,
+            color: "rgba(255,255,255,0.85)",
+            minWidth: 72,
             fontVariantNumeric: "tabular-nums",
+            letterSpacing: 0.2,
           }}
         >
           {formatTime(currentTime)} / {formatTime(totalDuration)}
@@ -485,8 +601,8 @@ const FrontendPreviewPlayer: React.FC<FrontendPreviewPlayerProps> = ({
           onMouseDown={handleMouseDown}
           style={{
             flex: 1,
-            height: 4,
-            background: "rgba(255,255,255,0.15)",
+            height: 3,
+            background: "rgba(255,255,255,0.2)",
             borderRadius: 2,
             cursor: "pointer",
             position: "relative",
@@ -496,7 +612,7 @@ const FrontendPreviewPlayer: React.FC<FrontendPreviewPlayerProps> = ({
             style={{
               height: "100%",
               width: `${progressPercent}%`,
-              background: "#3b82f6",
+              background: "#fff",
               borderRadius: 2,
               transition: isDragging ? "none" : "width 0.1s linear",
             }}
@@ -510,15 +626,15 @@ const FrontendPreviewPlayer: React.FC<FrontendPreviewPlayerProps> = ({
               width: 10,
               height: 10,
               borderRadius: "50%",
-              background: "#3b82f6",
-              border: "2px solid #fff",
+              background: "#fff",
+              boxShadow: "0 0 6px rgba(255,255,255,0.5)",
               opacity: isDragging ? 1 : 0,
               transition: "opacity 0.15s",
             }}
           />
         </div>
       </div>
-    </>
+    </div>
   )
 }
 

apps/web/src/pages/generate/components/GenerateStepContent.tsx

@@ -84,10 +84,6 @@ export interface GenerateStepContentProps {
   bgm: boolean
   /** BGM 配置（来自模板） */
   bgmConfig?: { enabled: boolean; music_id?: string }
-  /** 服务器预览状态 */
-  previewStatus?: import("../hooks/useServerPreview").ServerPreviewStatus
-  /** 重新预览回调 */
-  onRetryPreview?: () => void
 }
 
 export const GenerateStepContent: React.FC<GenerateStepContentProps> = (props) => {
@@ -137,8 +133,6 @@ export const GenerateStepContent: React.FC<GenerateStepContentProps> = (props) =
     onSourceEditPlanIdExtracted,
     bgm,
     bgmConfig,
-    previewStatus,
-    onRetryPreview,
   } = props
 
   /* 当前模板的 segments，传给 Step2 构建 clips */
@@ -197,8 +191,6 @@ export const GenerateStepContent: React.FC<GenerateStepContentProps> = (props) =
           onApplyPreset={onApplyPreset}
           activePreset={activePreset}
           titlePresets={titlePresets}
-          previewStatus={previewStatus || "idle"}
-          onRetryPreview={onRetryPreview || (() => {})}
         />
       )
     case 6:

apps/web/src/pages/generate/components/Step5GeneratePreview.tsx

@@ -1,18 +1,15 @@
 /**
  * Step 5 预览设置组件
  *
- * 服务器渲染预览架构：
- * - 进入此步骤时右侧面板自动播放服务器渲染的真实视频
- * - 标题样式可实时调整（CSS 层叠加预览）
- * - 调整标题后点击"重新预览"可刷新服务器渲染结果
- * - 素材/配音/BGM 变更会自动重新渲染
+ * 前端实时预览架构：
+ * - 右侧面板使用 FrontendPreviewPlayer 实时播放素材片段
+ * - 标题样式可实时调整，CSS 层即时叠加预览
+ * - 点"确认生成"时触发一次服务器渲染
  */
 import React from "react"
-import { PlayCircleOutlined, ReloadOutlined } from "@ant-design/icons"
-import { Button } from "antd"
+import { PlayCircleOutlined } from "@ant-design/icons"
 import { POSITION_OPTIONS, FONT_OPTIONS } from "../constants"
 import type { TitleSettings } from "../types"
-import type { ServerPreviewStatus } from "../hooks/useServerPreview"
 import TitleStylePanel from "./title/TitleStylePanel"
 
 interface Step5GeneratePreviewProps {
@@ -27,10 +24,6 @@ interface Step5GeneratePreviewProps {
   onApplyPreset: (presetKey: string) => void
   activePreset: string | null
   titlePresets: { key: string; label: string; previewStyle: React.CSSProperties }[]
-  /** 服务器预览状态 */
-  previewStatus: ServerPreviewStatus
-  /** 重新预览回调 */
-  onRetryPreview: () => void
 }
 
 const Step5GeneratePreview: React.FC<Step5GeneratePreviewProps> = ({
@@ -45,13 +38,7 @@ const Step5GeneratePreview: React.FC<Step5GeneratePreviewProps> = ({
   onApplyPreset,
   activePreset,
   titlePresets,
-  previewStatus,
-  onRetryPreview,
 }) => {
-  const isLoading = previewStatus === "loading"
-  const isStale = previewStatus === "stale"
-  const isFailed = previewStatus === "failed"
-
   return (
     <div className="xx-form-section">
       <h3>🎬 预览设置</h3>
@@ -70,71 +57,10 @@ const Step5GeneratePreview: React.FC<Step5GeneratePreviewProps> = ({
       >
         <PlayCircleOutlined style={{ fontSize: 18, color: "#3b82f6" }} />
         <span style={{ fontSize: 13, color: "var(--text-secondary, #666)" }}>
-          右侧为服务器渲染的真实预览视频，最终成片与预览完全一致
+          右侧为实时预览，选完素材即可播放。确认生成后服务器渲染最终视频
         </span>
       </div>
 
-      {/* 配置变更提示条 */}
-      {isStale && (
-        <div
-          style={{
-            display: "flex",
-            alignItems: "center",
-            justifyContent: "space-between",
-            gap: 8,
-            padding: "10px 16px",
-            background: "rgba(250, 173, 20, 0.1)",
-            borderRadius: 8,
-            marginBottom: 16,
-            border: "1px solid rgba(250, 173, 20, 0.2)",
-          }}
-        >
-          <span style={{ fontSize: 13, color: "#d48806" }}>
-            标题已修改，点击重新预览刷新服务器渲染
-          </span>
-          <Button size="small" type="primary" icon={<ReloadOutlined />} onClick={onRetryPreview}>
-            重新预览
-          </Button>
-        </div>
-      )}
-
-      {isFailed && (
-        <div
-          style={{
-            display: "flex",
-            alignItems: "center",
-            justifyContent: "space-between",
-            gap: 8,
-            padding: "10px 16px",
-            background: "rgba(255, 77, 79, 0.1)",
-            borderRadius: 8,
-            marginBottom: 16,
-            border: "1px solid rgba(255, 77, 79, 0.2)",
-          }}
-        >
-          <span style={{ fontSize: 13, color: "#ff4d4f" }}>预览渲染失败</span>
-          <Button size="small" danger icon={<ReloadOutlined />} onClick={onRetryPreview}>
-            重新预览
-          </Button>
-        </div>
-      )}
-
-      {isLoading && (
-        <div
-          style={{
-            padding: "10px 16px",
-            background: "rgba(82, 196, 26, 0.08)",
-            borderRadius: 8,
-            marginBottom: 16,
-            border: "1px solid rgba(82, 196, 26, 0.15)",
-          }}
-        >
-          <span style={{ fontSize: 13, color: "#389e0d" }}>
-            ⏳ 正在服务器渲染预览视频，请稍候...
-          </span>
-        </div>
-      )}
-
       <TitleStylePanel
         settings={titleSettings}
         onUpdatePosition={onUpdatePosition}

apps/web/src/pages/generate/generate.css

@@ -2525,6 +2525,7 @@
 .xx-generate-right-col {
   display: flex;
   flex-direction: column;
+  align-items: center;
   gap: 16px;
 }
 

apps/web/src/pages/generate/hooks/useGenerateVideo.ts

@@ -6,7 +6,6 @@ import { useState, useCallback } from "react"
 import { message } from "antd"
 import type { GeneratedVideo } from "@/api/template-editor"
 import { createGenerationTask } from "@/api/tasks/tasks"
-import { confirmGeneration } from "@/api/generation/confirm"
 import type { UseGenerateVideoProps } from "./generate-video/types"
 import { getGenerationPhase } from "./generate-video/phase"
 import { useGenerationPolling } from "./generate-video/useGenerationPolling"
@@ -61,7 +60,7 @@ export function useGenerateVideo(props: UseGenerateVideoProps) {
     clearTimer()
 
     try {
-      // 解析分辨率（共享工具函数，与预览 API 一致）
+      // 解析分辨率（共享工具函数）
       const { width: outputWidth, height: outputHeight } = calculateResolution(
         props.videoRatio || "9:16",
       )
@@ -72,78 +71,45 @@ export function useGenerateVideo(props: UseGenerateVideoProps) {
       // 封面 URL：优先 AI 生成缩略图，兜底用户上传
       const coverUrl = props.coverSettings?.thumbnail_url || props.coverSettings?.upload_url || ""
 
-      // ── Step7 确认生成：优先复用预览产物（秒出），fallback 到全量渲染 ──
-      let taskId: string | undefined
-
-      // 主路径：如果有预览任务 ID 且只生成 1 个视频，调用 confirmGeneration 复用预览产物
-      // generateCount > 1 时需要走 createGenerationTask 支持批量生成
-      const isSingleGenerate = !props.generateCount || props.generateCount === 1
-      if (props.previewTaskId && isSingleGenerate) {
-        try {
-          console.log(
-            "[handleGenerate] 尝试 confirmGeneration 复用预览产物, previewTaskId:",
-            props.previewTaskId,
-          )
-          const confirmResp = await confirmGeneration(props.previewTaskId, {
-            output_width: outputWidth,
-            output_height: outputHeight,
-            cover_url: coverUrl,
-            custom_title: props.titleSettings?.title || "",
-          })
-          taskId = confirmResp.items?.[0]?.id
-          if (taskId) {
-            console.log("[handleGenerate] confirmGeneration 成功, taskId:", taskId)
-          }
-        } catch (confirmErr) {
-          console.warn(
-            "[handleGenerate] confirmGeneration 失败, fallback 到 createGenerationTask:",
-            confirmErr,
-          )
-          // 继续走 fallback 路径
-        }
-      }
-
-      // 解析配音参数：voiceMode=clone 时用 selectedClonedVoice，否则用 selectedVoice（配音素材库 asset ID）
+      // 解析配音参数：voiceMode=clone 时用 selectedClonedVoice，否则用 selectedVoice
       const voiceLibraryId =
         props.voiceMode === "clone" ? props.selectedClonedVoice || "" : props.selectedVoice || ""
 
-      // Fallback 路径：没有预览任务或 confirmGeneration 失败，创建新的生成任务
-      if (!taskId) {
-        const taskResp = await createGenerationTask({
-          template_id: selectedTemplate,
-          asset_ids: assetIds,
-          output_width: outputWidth,
-          output_height: outputHeight,
-          cover_url: coverUrl,
-          custom_title: props.titleSettings?.title || "",
-          duration: props.duration || undefined,
-          video_ratio: props.videoRatio,
-          // 配音：优先用 voice_library_id（配音素材库 asset），兜底 voice_ids
-          ...(voiceLibraryId ? { voice_library_id: voiceLibraryId } : {}),
-          ...(props.selectedVoice && !voiceLibraryId ? { voice_ids: [props.selectedVoice] } : {}),
-          // BGM 配置：受 bgm 开关控制，enabled=false 时也显式传覆盖模板 BGM
-          bgm_config: {
-            enabled: props.bgm !== false,
-            ...(props.bgmConfig?.music_id ? { preset_id: props.bgmConfig.music_id } : {}),
-          },
-          ...(props.sourceEditPlanId ? { source_edit_plan_id: props.sourceEditPlanId } : {}),
-          ...(props.titleSettings?.title
-            ? {
-                title_config: {
-                  text: props.titleSettings.title,
-                  font: props.titleSettings.font,
-                  font_size: props.titleSettings.size,
-                  font_color: props.titleSettings.color,
-                  position: props.titleSettings.position,
-                  bold: props.titleSettings.bold,
-                  stroke: props.titleSettings.stroke,
-                  shadow: props.titleSettings.shadow,
-                },
-              }
-            : {}),
-        })
-        taskId = taskResp.items?.[0]?.id
-      }
+      // 创建生成任务（服务器渲染）
+      const taskResp = await createGenerationTask({
+        template_id: selectedTemplate,
+        asset_ids: assetIds,
+        output_width: outputWidth,
+        output_height: outputHeight,
+        cover_url: coverUrl,
+        custom_title: props.titleSettings?.title || "",
+        duration: props.duration || undefined,
+        video_ratio: props.videoRatio,
+        // 配音：优先用 voice_library_id（配音素材库 asset），兜底 voice_ids
+        ...(voiceLibraryId ? { voice_library_id: voiceLibraryId } : {}),
+        ...(props.selectedVoice && !voiceLibraryId ? { voice_ids: [props.selectedVoice] } : {}),
+        // BGM 配置：受 bgm 开关控制，enabled=false 时也显式传覆盖模板 BGM
+        bgm_config: {
+          enabled: props.bgm !== false,
+          ...(props.bgmConfig?.music_id ? { preset_id: props.bgmConfig.music_id } : {}),
+        },
+        ...(props.sourceEditPlanId ? { source_edit_plan_id: props.sourceEditPlanId } : {}),
+        ...(props.titleSettings?.title
+          ? {
+              title_config: {
+                text: props.titleSettings.title,
+                font: props.titleSettings.font,
+                font_size: props.titleSettings.size,
+                font_color: props.titleSettings.color,
+                position: props.titleSettings.position,
+                bold: props.titleSettings.bold,
+                stroke: props.titleSettings.stroke,
+                shadow: props.titleSettings.shadow,
+              },
+            }
+          : {}),
+      })
+      const taskId = taskResp.items?.[0]?.id
 
       if (!taskId) {
         throw new Error("创建任务成功但未返回任务 ID，请稍后在任务列表查看")

apps/web/src/pages/generate/hooks/useStepNavigation.ts

@@ -3,7 +3,7 @@
  * 管理步骤切换与各步骤的前置校验
  * 步骤顺序：模板(1) → 素材(2) → 配音(3) → 标题(4) → 预览(5) → 封面(6) → 确认(7)
  *
- * 服务器预览架构：Step5 需要服务器渲染预览完成才能前进
+ * 前端实时预览架构：Step5 无需等待服务器渲染
  */
 import { message } from "antd"
 import type { TitleSettings } from "../types"
@@ -16,8 +16,6 @@ export interface UseStepNavigationOptions {
   selectedMaterials: string[]
   smartSelectedIds: string[]
   titleSettings: TitleSettings
-  /** 服务器预览是否已完成（ready 状态） */
-  previewReady: boolean
 }
 
 export interface UseStepNavigationReturn {
@@ -34,7 +32,6 @@ export const useStepNavigation = (options: UseStepNavigationOptions): UseStepNav
     selectedMaterials,
     smartSelectedIds,
     titleSettings,
-    previewReady,
   } = options
 
   const goNext = () => {
@@ -54,10 +51,6 @@ export const useStepNavigation = (options: UseStepNavigationOptions): UseStepNav
       message.warning("请选择或输入标题")
       return
     }
-    if (currentStep === 5 && !previewReady) {
-      message.warning("请等待预览视频渲染完成后再继续")
-      return
-    }
     if (currentStep < 7) {
       setCurrentStep((s) => s + 1)
     }

tests/unit/test_generation_preview.py

@@ -1206,7 +1206,10 @@ class TestPreviewRouteAutoInfersVideoRatio:
         # Verify the resolution passed to CreateGenerationTaskCommand
         call_args = MockUC.return_value.execute.call_args
         cmd = call_args[0][0]
-        assert cmd.resolution == "", f"Expected empty resolution, got {cmd.resolution}"
+        # video_ratio inferred from pip → 9:16 → resolution=1080x1920
+        assert cmd.resolution == "1080x1920", f"Expected 1080x1920, got {cmd.resolution}"
+        assert cmd.output_width == 1080, f"Expected output_width=1080, got {cmd.output_width}"
+        assert cmd.output_height == 1920, f"Expected output_height=1920, got {cmd.output_height}"
 
 
 # ═══════════════════════════════════════════════════════════════════════════════

tests/unit/test_tts_preview.py

@@ -0,0 +1,247 @@
+"""Tests for POST /tts/preview endpoint."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from unittest.mock import MagicMock, patch
+
+import pytest
+from pydantic import ValidationError
+
+
+@dataclass
+class FakeSynthesizeResult:
+    audio_url: str
+    duration: float = 0.0
+    file_size: int = 0
+    request_id: str = ""
+
+
+class TestTTSPreviewEndpoint:
+    """Integration-style tests for the /tts/preview route."""
+
+    def _make_client(self, app):
+        from fastapi.testclient import TestClient
+
+        return TestClient(app)
+
+    def test_schema_preview_request_validation(self):
+        """TTSPreviewRequest rejects text > 200 chars and empty voice_id."""
+        from app.schemas.tts import TTSPreviewRequest
+
+        # Valid
+        req = TTSPreviewRequest(text="hello", voice_id="v1")
+        assert req.text == "hello"
+        assert req.voice_id == "v1"
+        assert req.speed == 1.0
+
+        # Empty voice_id rejected
+        with pytest.raises(ValidationError):
+            TTSPreviewRequest(text="hello", voice_id="")
+
+        # Text > 200 chars rejected
+        with pytest.raises(ValidationError):
+            TTSPreviewRequest(text="a" * 201, voice_id="v1")
+
+    def test_schema_preview_response(self):
+        """TTSPreviewResponse serialization."""
+        from app.schemas.tts import TTSPreviewResponse
+
+        resp = TTSPreviewResponse(audio_url="https://example.com/audio.mp3")
+        assert resp.audio_url == "https://example.com/audio.mp3"
+        assert resp.duration is None
+
+        resp2 = TTSPreviewResponse(audio_url="https://x.com/a.mp3", duration=3.5)
+        assert resp2.duration == 3.5
+
+    def test_preview_success(self):
+        """Successful preview returns audio_url."""
+        from app.schemas.tts import TTSPreviewRequest
+        from fastapi import FastAPI
+
+        app = FastAPI()
+
+        # We need to register the route with proper dependencies
+        from app.api.routes.tts import router
+
+        app.include_router(router, prefix="/tts")
+
+        # Override dependencies
+        from app.auth import get_current_user
+        from app.dependencies import get_cosyvoice_service
+
+        fake_user = MagicMock()
+        fake_user.user.id = "user-1"
+        app.dependency_overrides[get_current_user] = lambda: fake_user
+
+        mock_service = MagicMock()
+        mock_service.synthesize_speech.return_value = FakeSynthesizeResult(
+            audio_url="https://cosyvoice.example.com/audio.mp3",
+            duration=2.5,
+        )
+        app.dependency_overrides[get_cosyvoice_service] = lambda: mock_service
+
+        client = self._make_client(app)
+        resp = client.post(
+            "/tts/preview",
+            json={"text": "你好世界", "voice_id": "longxiaochun"},
+        )
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["audio_url"] == "https://cosyvoice.example.com/audio.mp3"
+        assert data["duration"] == 2.5
+
+        mock_service.synthesize_speech.assert_called_once_with(
+            text="你好世界",
+            voice_id="longxiaochun",
+            speed=1.0,
+        )
+
+    def test_preview_with_speed(self):
+        """Custom speed is passed through to CosyVoice."""
+        from fastapi import FastAPI
+
+        app = FastAPI()
+        from app.api.routes.tts import router
+
+        app.include_router(router, prefix="/tts")
+
+        from app.auth import get_current_user
+        from app.dependencies import get_cosyvoice_service
+
+        fake_user = MagicMock()
+        fake_user.user.id = "user-1"
+        app.dependency_overrides[get_current_user] = lambda: fake_user
+
+        mock_service = MagicMock()
+        mock_service.synthesize_speech.return_value = FakeSynthesizeResult(
+            audio_url="https://x.com/a.mp3",
+            duration=0.0,
+        )
+        app.dependency_overrides[get_cosyvoice_service] = lambda: mock_service
+
+        client = self._make_client(app)
+        resp = client.post(
+            "/tts/preview",
+            json={"text": "测试", "voice_id": "v1", "speed": 1.5},
+        )
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["audio_url"] == "https://x.com/a.mp3"
+        assert data["duration"] is None  # 0.0 -> None
+
+        mock_service.synthesize_speech.assert_called_once_with(
+            text="测试",
+            voice_id="v1",
+            speed=1.5,
+        )
+
+    def test_preview_cosyvoice_error_returns_502(self):
+        """CosyVoice failure returns 502."""
+        from fastapi import FastAPI
+
+        from packages.application.cosyvoice_service import CosyVoiceError
+
+        app = FastAPI()
+        from app.api.routes.tts import router
+
+        app.include_router(router, prefix="/tts")
+
+        from app.auth import get_current_user
+        from app.dependencies import get_cosyvoice_service
+
+        fake_user = MagicMock()
+        fake_user.user.id = "user-1"
+        app.dependency_overrides[get_current_user] = lambda: fake_user
+
+        mock_service = MagicMock()
+        mock_service.synthesize_speech.side_effect = CosyVoiceError("API timeout")
+        app.dependency_overrides[get_cosyvoice_service] = lambda: mock_service
+
+        client = self._make_client(app)
+        resp = client.post(
+            "/tts/preview",
+            json={"text": "测试", "voice_id": "v1"},
+        )
+        assert resp.status_code == 502
+        assert "TTS 合成失败" in resp.json()["detail"]
+
+    def test_preview_value_error_returns_400(self):
+        """Invalid params return 400."""
+        from fastapi import FastAPI
+
+        app = FastAPI()
+        from app.api.routes.tts import router
+
+        app.include_router(router, prefix="/tts")
+
+        from app.auth import get_current_user
+        from app.dependencies import get_cosyvoice_service
+
+        fake_user = MagicMock()
+        fake_user.user.id = "user-1"
+        app.dependency_overrides[get_current_user] = lambda: fake_user
+
+        mock_service = MagicMock()
+        mock_service.synthesize_speech.side_effect = ValueError("text 不能为空")
+        app.dependency_overrides[get_cosyvoice_service] = lambda: mock_service
+
+        client = self._make_client(app)
+        resp = client.post(
+            "/tts/preview",
+            json={"text": "测试", "voice_id": "v1"},
+        )
+        assert resp.status_code == 400
+        assert "text 不能为空" in resp.json()["detail"]
+
+    def test_preview_text_too_long_returns_422(self):
+        """Text > 200 chars is rejected by Pydantic validation."""
+        from fastapi import FastAPI
+
+        app = FastAPI()
+        from app.api.routes.tts import router
+
+        app.include_router(router, prefix="/tts")
+
+        from app.auth import get_current_user
+        from app.dependencies import get_cosyvoice_service
+
+        fake_user = MagicMock()
+        fake_user.user.id = "user-1"
+        app.dependency_overrides[get_current_user] = lambda: fake_user
+
+        mock_service = MagicMock()
+        app.dependency_overrides[get_cosyvoice_service] = lambda: mock_service
+
+        client = self._make_client(app)
+        resp = client.post(
+            "/tts/preview",
+            json={"text": "a" * 201, "voice_id": "v1"},
+        )
+        assert resp.status_code == 422
+
+    def test_preview_empty_voice_id_returns_422(self):
+        """Empty voice_id is rejected by Pydantic validation."""
+        from fastapi import FastAPI
+
+        app = FastAPI()
+        from app.api.routes.tts import router
+
+        app.include_router(router, prefix="/tts")
+
+        from app.auth import get_current_user
+        from app.dependencies import get_cosyvoice_service
+
+        fake_user = MagicMock()
+        fake_user.user.id = "user-1"
+        app.dependency_overrides[get_current_user] = lambda: fake_user
+
+        mock_service = MagicMock()
+        app.dependency_overrides[get_cosyvoice_service] = lambda: mock_service
+
+        client = self._make_client(app)
+        resp = client.post(
+            "/tts/preview",
+            json={"text": "hello", "voice_id": ""},
+        )
+        assert resp.status_code == 422