AI story writer enhancements, text to video and voice generation, subscription management, and more.

backend/api/story_writer/routes/__init__.py

@@ -0,0 +1,21 @@
+"""
+Collection of modular routers for Story Writer endpoints.
+Each module focuses on a related set of routes to keep the primary
+`router.py` concise and easier to maintain.
+"""
+
+from . import story_setup
+from . import story_content
+from . import story_tasks
+from . import media_generation
+from . import video_generation
+from . import cache_routes
+
+__all__ = [
+    "story_setup",
+    "story_content",
+    "story_tasks",
+    "media_generation",
+    "video_generation",
+    "cache_routes",
+]

backend/api/story_writer/routes/cache_routes.py

@@ -0,0 +1,42 @@
+from typing import Any, Dict
+
+from fastapi import APIRouter, Depends, HTTPException
+from loguru import logger
+
+from middleware.auth_middleware import get_current_user
+
+from ..cache_manager import cache_manager
+from ..utils.auth import require_authenticated_user
+
+
+router = APIRouter()
+
+
+@router.get("/cache/stats")
+async def get_cache_stats(
+    current_user: Dict[str, Any] = Depends(get_current_user),
+) -> Dict[str, Any]:
+    """Get cache statistics."""
+    try:
+        require_authenticated_user(current_user)
+        stats = cache_manager.get_cache_stats()
+        return {"success": True, "stats": stats}
+    except Exception as exc:
+        logger.error(f"[StoryWriter] Failed to get cache stats: {exc}")
+        raise HTTPException(status_code=500, detail=str(exc))
+
+
+@router.post("/cache/clear")
+async def clear_cache(
+    current_user: Dict[str, Any] = Depends(get_current_user),
+) -> Dict[str, Any]:
+    """Clear the story generation cache."""
+    try:
+        require_authenticated_user(current_user)
+        result = cache_manager.clear_cache()
+        return {"success": True, **result}
+    except Exception as exc:
+        logger.error(f"[StoryWriter] Failed to clear cache: {exc}")
+        raise HTTPException(status_code=500, detail=str(exc))
+
+

backend/api/story_writer/routes/media_generation.py

@@ -0,0 +1,289 @@
+from typing import Any, Dict, List
+
+from fastapi import APIRouter, Depends, HTTPException
+from fastapi.responses import FileResponse
+from loguru import logger
+
+from middleware.auth_middleware import get_current_user, get_current_user_with_query_token
+from models.story_models import (
+    StoryImageGenerationRequest,
+    StoryImageGenerationResponse,
+    StoryImageResult,
+    RegenerateImageRequest,
+    RegenerateImageResponse,
+    StoryAudioGenerationRequest,
+    StoryAudioGenerationResponse,
+    StoryAudioResult,
+    GenerateAIAudioRequest,
+    GenerateAIAudioResponse,
+    StoryScene,
+)
+from services.story_writer.image_generation_service import StoryImageGenerationService
+from services.story_writer.audio_generation_service import StoryAudioGenerationService
+
+from ..utils.auth import require_authenticated_user
+from ..utils.media_utils import resolve_media_file
+
+
+router = APIRouter()
+image_service = StoryImageGenerationService()
+audio_service = StoryAudioGenerationService()
+
+
+@router.post("/generate-images", response_model=StoryImageGenerationResponse)
+async def generate_scene_images(
+    request: StoryImageGenerationRequest,
+    current_user: Dict[str, Any] = Depends(get_current_user),
+) -> StoryImageGenerationResponse:
+    """Generate images for story scenes."""
+    try:
+        user_id = require_authenticated_user(current_user)
+
+        if not request.scenes or len(request.scenes) == 0:
+            raise HTTPException(status_code=400, detail="At least one scene is required")
+
+        logger.info(f"[StoryWriter] Generating images for {len(request.scenes)} scenes for user {user_id}")
+
+        scenes_data = [scene.dict() if isinstance(scene, StoryScene) else scene for scene in request.scenes]
+        image_results = image_service.generate_scene_images(
+            scenes=scenes_data,
+            user_id=user_id,
+            provider=request.provider,
+            width=request.width or 1024,
+            height=request.height or 1024,
+            model=request.model,
+        )
+
+        image_models: List[StoryImageResult] = [
+            StoryImageResult(
+                scene_number=result.get("scene_number", 0),
+                scene_title=result.get("scene_title", "Untitled"),
+                image_filename=result.get("image_filename", ""),
+                image_url=result.get("image_url", ""),
+                width=result.get("width", 1024),
+                height=result.get("height", 1024),
+                provider=result.get("provider", "unknown"),
+                model=result.get("model"),
+                seed=result.get("seed"),
+                error=result.get("error"),
+            )
+            for result in image_results
+        ]
+
+        return StoryImageGenerationResponse(images=image_models, success=True)
+
+    except HTTPException:
+        raise
+    except Exception as exc:
+        logger.error(f"[StoryWriter] Failed to generate images: {exc}")
+        raise HTTPException(status_code=500, detail=str(exc))
+
+
+@router.post("/regenerate-images", response_model=RegenerateImageResponse)
+async def regenerate_scene_image(
+    request: RegenerateImageRequest,
+    current_user: Dict[str, Any] = Depends(get_current_user),
+) -> RegenerateImageResponse:
+    """Regenerate a single scene image using a direct prompt (no AI prompt generation)."""
+    try:
+        user_id = require_authenticated_user(current_user)
+
+        if not request.prompt or not request.prompt.strip():
+            raise HTTPException(status_code=400, detail="Prompt is required")
+
+        logger.info(
+            f"[StoryWriter] Regenerating image for scene {request.scene_number} "
+            f"({request.scene_title}) for user {user_id}"
+        )
+
+        result = image_service.regenerate_scene_image(
+            scene_number=request.scene_number,
+            scene_title=request.scene_title,
+            prompt=request.prompt.strip(),
+            user_id=user_id,
+            provider=request.provider,
+            width=request.width or 1024,
+            height=request.height or 1024,
+            model=request.model,
+        )
+
+        return RegenerateImageResponse(
+            scene_number=result.get("scene_number", request.scene_number),
+            scene_title=result.get("scene_title", request.scene_title),
+            image_filename=result.get("image_filename", ""),
+            image_url=result.get("image_url", ""),
+            width=result.get("width", request.width or 1024),
+            height=result.get("height", request.height or 1024),
+            provider=result.get("provider", "unknown"),
+            model=result.get("model"),
+            seed=result.get("seed"),
+            success=True,
+        )
+
+    except HTTPException:
+        raise
+    except Exception as exc:
+        logger.error(f"[StoryWriter] Failed to regenerate image: {exc}")
+        return RegenerateImageResponse(
+            scene_number=request.scene_number,
+            scene_title=request.scene_title,
+            image_filename="",
+            image_url="",
+            width=request.width or 1024,
+            height=request.height or 1024,
+            provider=request.provider or "unknown",
+            success=False,
+            error=str(exc),
+        )
+
+
+@router.get("/images/{image_filename}")
+async def serve_scene_image(
+    image_filename: str,
+    current_user: Dict[str, Any] = Depends(get_current_user_with_query_token),
+):
+    """Serve a generated story scene image.
+    
+    Supports authentication via Authorization header or token query parameter.
+    Query parameter is useful for HTML elements like <img> that cannot send custom headers.
+    """
+    try:
+        require_authenticated_user(current_user)
+        image_path = resolve_media_file(image_service.output_dir, image_filename)
+        return FileResponse(path=str(image_path), media_type="image/png", filename=image_filename)
+
+    except HTTPException:
+        raise
+    except Exception as exc:
+        logger.error(f"[StoryWriter] Failed to serve image: {exc}")
+        raise HTTPException(status_code=500, detail=str(exc))
+
+
+@router.post("/generate-audio", response_model=StoryAudioGenerationResponse)
+async def generate_scene_audio(
+    request: StoryAudioGenerationRequest,
+    current_user: Dict[str, Any] = Depends(get_current_user),
+) -> StoryAudioGenerationResponse:
+    """Generate audio narration for story scenes."""
+    try:
+        user_id = require_authenticated_user(current_user)
+
+        if not request.scenes or len(request.scenes) == 0:
+            raise HTTPException(status_code=400, detail="At least one scene is required")
+
+        logger.info(f"[StoryWriter] Generating audio for {len(request.scenes)} scenes for user {user_id}")
+
+        scenes_data = [scene.dict() if isinstance(scene, StoryScene) else scene for scene in request.scenes]
+        audio_results = audio_service.generate_scene_audio_list(
+            scenes=scenes_data,
+            user_id=user_id,
+            provider=request.provider or "gtts",
+            lang=request.lang or "en",
+            slow=request.slow or False,
+            rate=request.rate or 150,
+        )
+
+        audio_models: List[StoryAudioResult] = []
+        for result in audio_results:
+            audio_models.append(
+                StoryAudioResult(
+                    scene_number=result.get("scene_number", 0),
+                    scene_title=result.get("scene_title", "Untitled"),
+                    audio_filename=result.get("audio_filename") or "",
+                    audio_url=result.get("audio_url") or "",
+                    provider=result.get("provider", "unknown"),
+                    file_size=result.get("file_size", 0),
+                    error=result.get("error"),
+                )
+            )
+
+        return StoryAudioGenerationResponse(audio_files=audio_models, success=True)
+
+    except HTTPException:
+        raise
+    except Exception as exc:
+        logger.error(f"[StoryWriter] Failed to generate audio: {exc}")
+        raise HTTPException(status_code=500, detail=str(exc))
+
+
+@router.post("/generate-ai-audio", response_model=GenerateAIAudioResponse)
+async def generate_ai_audio(
+    request: GenerateAIAudioRequest,
+    current_user: Dict[str, Any] = Depends(get_current_user),
+) -> GenerateAIAudioResponse:
+    """Generate AI audio for a single scene using WaveSpeed Minimax Speech 02 HD."""
+    try:
+        user_id = require_authenticated_user(current_user)
+
+        if not request.text or not request.text.strip():
+            raise HTTPException(status_code=400, detail="Text is required")
+
+        logger.info(
+            f"[StoryWriter] Generating AI audio for scene {request.scene_number} "
+            f"({request.scene_title}) for user {user_id}"
+        )
+
+        result = audio_service.generate_ai_audio(
+            scene_number=request.scene_number,
+            scene_title=request.scene_title,
+            text=request.text.strip(),
+            user_id=user_id,
+            voice_id=request.voice_id or "Wise_Woman",
+            speed=request.speed or 1.0,
+            volume=request.volume or 1.0,
+            pitch=request.pitch or 0.0,
+            emotion=request.emotion or "happy",
+        )
+
+        return GenerateAIAudioResponse(
+            scene_number=result.get("scene_number", request.scene_number),
+            scene_title=result.get("scene_title", request.scene_title),
+            audio_filename=result.get("audio_filename", ""),
+            audio_url=result.get("audio_url", ""),
+            provider=result.get("provider", "wavespeed"),
+            model=result.get("model", "minimax/speech-02-hd"),
+            voice_id=result.get("voice_id", request.voice_id or "Wise_Woman"),
+            text_length=result.get("text_length", len(request.text)),
+            file_size=result.get("file_size", 0),
+            cost=result.get("cost", 0.0),
+            success=True,
+        )
+
+    except HTTPException:
+        raise
+    except Exception as exc:
+        logger.error(f"[StoryWriter] Failed to generate AI audio: {exc}")
+        return GenerateAIAudioResponse(
+            scene_number=request.scene_number,
+            scene_title=request.scene_title,
+            audio_filename="",
+            audio_url="",
+            provider="wavespeed",
+            model="minimax/speech-02-hd",
+            voice_id=request.voice_id or "Wise_Woman",
+            text_length=len(request.text) if request.text else 0,
+            file_size=0,
+            cost=0.0,
+            success=False,
+            error=str(exc),
+        )
+
+
+@router.get("/audio/{audio_filename}")
+async def serve_scene_audio(
+    audio_filename: str,
+    current_user: Dict[str, Any] = Depends(get_current_user),
+):
+    """Serve a generated story scene audio file."""
+    try:
+        require_authenticated_user(current_user)
+        audio_path = resolve_media_file(audio_service.output_dir, audio_filename)
+        return FileResponse(path=str(audio_path), media_type="audio/mpeg", filename=audio_filename)
+
+    except HTTPException:
+        raise
+    except Exception as exc:
+        logger.error(f"[StoryWriter] Failed to serve audio: {exc}")
+        raise HTTPException(status_code=500, detail=str(exc))
+
+

backend/api/story_writer/routes/story_content.py

@@ -0,0 +1,195 @@
+from typing import Any, Dict, List
+
+from fastapi import APIRouter, Depends, HTTPException
+from loguru import logger
+
+from middleware.auth_middleware import get_current_user
+from models.story_models import (
+    StoryStartRequest,
+    StoryContentResponse,
+    StoryScene,
+    StoryContinueRequest,
+    StoryContinueResponse,
+)
+from services.story_writer.story_service import StoryWriterService
+
+from ..utils.auth import require_authenticated_user
+
+
+router = APIRouter()
+story_service = StoryWriterService()
+
+
+@router.post("/generate-start", response_model=StoryContentResponse)
+async def generate_story_start(
+    request: StoryStartRequest,
+    current_user: Dict[str, Any] = Depends(get_current_user),
+) -> StoryContentResponse:
+    """Generate the starting section of a story."""
+    try:
+        user_id = require_authenticated_user(current_user)
+
+        if not request.premise or not request.premise.strip():
+            raise HTTPException(status_code=400, detail="Premise is required")
+        if not request.outline or (isinstance(request.outline, str) and not request.outline.strip()):
+            raise HTTPException(status_code=400, detail="Outline is required")
+
+        logger.info(f"[StoryWriter] Generating story start for user {user_id}")
+
+        outline_data: Any = request.outline
+        if isinstance(outline_data, list) and outline_data and isinstance(outline_data[0], StoryScene):
+            outline_data = [scene.dict() for scene in outline_data]
+
+        story_length = getattr(request, "story_length", "Medium")
+        story_start = story_service.generate_story_start(
+            premise=request.premise,
+            outline=outline_data,
+            persona=request.persona,
+            story_setting=request.story_setting,
+            character_input=request.character_input,
+            plot_elements=request.plot_elements,
+            writing_style=request.writing_style,
+            story_tone=request.story_tone,
+            narrative_pov=request.narrative_pov,
+            audience_age_group=request.audience_age_group,
+            content_rating=request.content_rating,
+            ending_preference=request.ending_preference,
+            story_length=story_length,
+            user_id=user_id,
+        )
+
+        story_length_lower = story_length.lower()
+        is_short_story = "short" in story_length_lower or "1000" in story_length_lower
+        is_complete = False
+        if is_short_story:
+            word_count = len(story_start.split()) if story_start else 0
+            if word_count >= 900:
+                is_complete = True
+                logger.info(
+                    f"[StoryWriter] Short story generated with {word_count} words. Marking as complete."
+                )
+            else:
+                logger.warning(
+                    f"[StoryWriter] Short story generated with only {word_count} words. May need continuation."
+                )
+
+        outline_response = outline_data
+        if isinstance(outline_response, list):
+            outline_response = "\n".join(
+                [
+                    f"Scene {scene.get('scene_number', i + 1)}: "
+                    f"{scene.get('title', 'Untitled')}\n  {scene.get('description', '')}"
+                    for i, scene in enumerate(outline_response)
+                ]
+            )
+
+        return StoryContentResponse(
+            story=story_start,
+            premise=request.premise,
+            outline=str(outline_response),
+            is_complete=is_complete,
+            success=True,
+        )
+
+    except HTTPException:
+        raise
+    except Exception as exc:
+        logger.error(f"[StoryWriter] Failed to generate story start: {exc}")
+        raise HTTPException(status_code=500, detail=str(exc))
+
+
+@router.post("/continue", response_model=StoryContinueResponse)
+async def continue_story(
+    request: StoryContinueRequest,
+    current_user: Dict[str, Any] = Depends(get_current_user),
+) -> StoryContinueResponse:
+    """Continue writing a story."""
+    try:
+        user_id = require_authenticated_user(current_user)
+
+        if not request.story_text or not request.story_text.strip():
+            raise HTTPException(status_code=400, detail="Story text is required")
+
+        logger.info(f"[StoryWriter] Continuing story for user {user_id}")
+
+        outline_data: Any = request.outline
+        if isinstance(outline_data, list) and outline_data and isinstance(outline_data[0], StoryScene):
+            outline_data = [scene.dict() for scene in outline_data]
+
+        story_length = getattr(request, "story_length", "Medium")
+        story_length_lower = story_length.lower()
+        is_short_story = "short" in story_length_lower or "1000" in story_length_lower
+        if is_short_story:
+            logger.warning(
+                "[StoryWriter] Attempted to continue a short story. Short stories should be complete in one call."
+            )
+            raise HTTPException(
+                status_code=400,
+                detail="Short stories are generated in a single call and should be complete. "
+                "If the story is incomplete, please regenerate it from the beginning.",
+            )
+
+        current_word_count = len(request.story_text.split()) if request.story_text else 0
+        if "long" in story_length_lower or "10000" in story_length_lower:
+            target_total_words = 10000
+        else:
+            target_total_words = 4500
+        buffer_target = int(target_total_words * 1.05)
+
+        if current_word_count >= buffer_target or (
+            current_word_count >= target_total_words
+            and (current_word_count - target_total_words) < 50
+        ):
+            logger.info(
+                f"[StoryWriter] Word count ({current_word_count}) already at or near target ({target_total_words})."
+            )
+            return StoryContinueResponse(continuation="IAMDONE", is_complete=True, success=True)
+
+        continuation = story_service.continue_story(
+            premise=request.premise,
+            outline=outline_data,
+            story_text=request.story_text,
+            persona=request.persona,
+            story_setting=request.story_setting,
+            character_input=request.character_input,
+            plot_elements=request.plot_elements,
+            writing_style=request.writing_style,
+            story_tone=request.story_tone,
+            narrative_pov=request.narrative_pov,
+            audience_age_group=request.audience_age_group,
+            content_rating=request.content_rating,
+            ending_preference=request.ending_preference,
+            story_length=story_length,
+            user_id=user_id,
+        )
+
+        is_complete = "IAMDONE" in continuation.upper()
+        if not is_complete and continuation:
+            new_story_text = request.story_text + "\n\n" + continuation
+            new_word_count = len(new_story_text.split())
+            if new_word_count >= buffer_target:
+                logger.info(
+                    f"[StoryWriter] Word count ({new_word_count}) now exceeds buffer target ({buffer_target})."
+                )
+                if "IAMDONE" not in continuation.upper():
+                    continuation = continuation.rstrip() + "\n\nIAMDONE"
+                is_complete = True
+            elif new_word_count >= target_total_words and (
+                new_word_count - target_total_words
+            ) < 100:
+                logger.info(
+                    f"[StoryWriter] Word count ({new_word_count}) is at or very close to target ({target_total_words})."
+                )
+                if "IAMDONE" not in continuation.upper():
+                    continuation = continuation.rstrip() + "\n\nIAMDONE"
+                is_complete = True
+
+        return StoryContinueResponse(continuation=continuation, is_complete=is_complete, success=True)
+
+    except HTTPException:
+        raise
+    except Exception as exc:
+        logger.error(f"[StoryWriter] Failed to continue story: {exc}")
+        raise HTTPException(status_code=500, detail=str(exc))
+
+

backend/api/story_writer/routes/story_setup.py

@@ -0,0 +1,141 @@
+from typing import Any, Dict, List
+
+from fastapi import APIRouter, Depends, HTTPException
+from loguru import logger
+
+from middleware.auth_middleware import get_current_user
+from models.story_models import (
+    StorySetupGenerationRequest,
+    StorySetupGenerationResponse,
+    StorySetupOption,
+    StoryGenerationRequest,
+    StoryOutlineResponse,
+    StoryScene,
+    StoryStartRequest,
+    StoryPremiseResponse,
+)
+from services.story_writer.story_service import StoryWriterService
+
+from ..utils.auth import require_authenticated_user
+
+
+router = APIRouter()
+story_service = StoryWriterService()
+
+
+@router.post("/generate-setup", response_model=StorySetupGenerationResponse)
+async def generate_story_setup(
+    request: StorySetupGenerationRequest,
+    current_user: Dict[str, Any] = Depends(get_current_user),
+) -> StorySetupGenerationResponse:
+    """Generate 3 story setup options from a user's story idea."""
+    try:
+        user_id = require_authenticated_user(current_user)
+
+        if not request.story_idea or not request.story_idea.strip():
+            raise HTTPException(status_code=400, detail="Story idea is required")
+
+        logger.info(f"[StoryWriter] Generating story setup options for user {user_id}")
+
+        options = story_service.generate_story_setup_options(
+            story_idea=request.story_idea,
+            user_id=user_id,
+        )
+
+        setup_options = [StorySetupOption(**option) for option in options]
+        return StorySetupGenerationResponse(options=setup_options, success=True)
+
+    except HTTPException:
+        raise
+    except Exception as exc:
+        logger.error(f"[StoryWriter] Failed to generate story setup options: {exc}")
+        raise HTTPException(status_code=500, detail=str(exc))
+
+
+@router.post("/generate-premise", response_model=StoryPremiseResponse)
+async def generate_premise(
+    request: StoryGenerationRequest,
+    current_user: Dict[str, Any] = Depends(get_current_user),
+) -> StoryPremiseResponse:
+    """Generate a story premise."""
+    try:
+        user_id = require_authenticated_user(current_user)
+        logger.info(f"[StoryWriter] Generating premise for user {user_id}")
+
+        premise = story_service.generate_premise(
+            persona=request.persona,
+            story_setting=request.story_setting,
+            character_input=request.character_input,
+            plot_elements=request.plot_elements,
+            writing_style=request.writing_style,
+            story_tone=request.story_tone,
+            narrative_pov=request.narrative_pov,
+            audience_age_group=request.audience_age_group,
+            content_rating=request.content_rating,
+            ending_preference=request.ending_preference,
+            user_id=user_id,
+        )
+
+        return StoryPremiseResponse(premise=premise, success=True)
+
+    except HTTPException:
+        raise
+    except Exception as exc:
+        logger.error(f"[StoryWriter] Failed to generate premise: {exc}")
+        raise HTTPException(status_code=500, detail=str(exc))
+
+
+@router.post("/generate-outline", response_model=StoryOutlineResponse)
+async def generate_outline(
+    request: StoryStartRequest,
+    current_user: Dict[str, Any] = Depends(get_current_user),
+    use_structured: bool = True,
+) -> StoryOutlineResponse:
+    """Generate a story outline from a premise."""
+    try:
+        user_id = require_authenticated_user(current_user)
+
+        if not request.premise or not request.premise.strip():
+            raise HTTPException(status_code=400, detail="Premise is required")
+
+        logger.info(
+            f"[StoryWriter] Generating outline for user {user_id} (structured={use_structured})"
+        )
+        logger.info(
+            "[StoryWriter] Outline params: audience_age_group=%s, writing_style=%s, story_tone=%s",
+            request.audience_age_group,
+            request.writing_style,
+            request.story_tone,
+        )
+
+        outline = story_service.generate_outline(
+            premise=request.premise,
+            persona=request.persona,
+            story_setting=request.story_setting,
+            character_input=request.character_input,
+            plot_elements=request.plot_elements,
+            writing_style=request.writing_style,
+            story_tone=request.story_tone,
+            narrative_pov=request.narrative_pov,
+            audience_age_group=request.audience_age_group,
+            content_rating=request.content_rating,
+            ending_preference=request.ending_preference,
+            user_id=user_id,
+            use_structured_output=use_structured,
+        )
+
+        if isinstance(outline, list):
+            scenes: List[StoryScene] = [
+                StoryScene(**scene) if isinstance(scene, dict) else scene for scene in outline
+            ]
+            return StoryOutlineResponse(outline=scenes, success=True, is_structured=True)
+
+        return StoryOutlineResponse(outline=str(outline), success=True, is_structured=False)
+
+    except HTTPException:
+        raise
+    except Exception as exc:
+        logger.error(f"[StoryWriter] Failed to generate outline: {exc}")
+        raise HTTPException(status_code=500, detail=str(exc))
+
+

backend/api/story_writer/routes/story_tasks.py

@@ -0,0 +1,130 @@
+from typing import Any, Dict
+
+from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException
+from loguru import logger
+
+from middleware.auth_middleware import get_current_user
+from models.story_models import (
+    StoryGenerationRequest,
+    TaskStatus,
+)
+from services.story_writer.story_service import StoryWriterService
+
+from ..cache_manager import cache_manager
+from ..task_manager import task_manager
+from ..utils.auth import require_authenticated_user
+
+
+router = APIRouter()
+story_service = StoryWriterService()
+
+
+@router.post("/generate-full", response_model=Dict[str, Any])
+async def generate_full_story(
+    request: StoryGenerationRequest,
+    background_tasks: BackgroundTasks,
+    current_user: Dict[str, Any] = Depends(get_current_user),
+    max_iterations: int = 10,
+) -> Dict[str, Any]:
+    """Generate a complete story asynchronously."""
+    try:
+        user_id = require_authenticated_user(current_user)
+
+        cache_key = cache_manager.get_cache_key(request.dict())
+        cached_result = cache_manager.get_cached_result(cache_key)
+        if cached_result:
+            logger.info(f"[StoryWriter] Returning cached result for user {user_id}")
+            task_id = task_manager.create_task("story_generation")
+            task_manager.update_task_status(
+                task_id,
+                "completed",
+                progress=100.0,
+                result=cached_result,
+                message="Returned cached result",
+            )
+            return {"task_id": task_id, "cached": True}
+
+        task_id = task_manager.create_task("story_generation")
+        request_data = request.dict()
+        request_data["max_iterations"] = max_iterations
+
+        background_tasks.add_task(
+            task_manager.execute_story_generation_task,
+            task_id=task_id,
+            request_data=request_data,
+            user_id=user_id,
+        )
+
+        logger.info(f"[StoryWriter] Created task {task_id} for full story generation (user {user_id})")
+        return {
+            "task_id": task_id,
+            "status": "pending",
+            "message": "Story generation started. Use /task/{task_id}/status to check progress.",
+        }
+
+    except HTTPException:
+        raise
+    except Exception as exc:
+        logger.error(f"[StoryWriter] Failed to start story generation: {exc}")
+        raise HTTPException(status_code=500, detail=str(exc))
+
+
+@router.get("/task/{task_id}/status", response_model=TaskStatus)
+async def get_task_status(
+    task_id: str,
+    current_user: Dict[str, Any] = Depends(get_current_user),
+) -> TaskStatus:
+    """Get the status of a story generation task."""
+    try:
+        require_authenticated_user(current_user)
+
+        task_status = task_manager.get_task_status(task_id)
+        if not task_status:
+            raise HTTPException(status_code=404, detail=f"Task {task_id} not found")
+
+        return TaskStatus(**task_status)
+
+    except HTTPException:
+        raise
+    except Exception as exc:
+        logger.error(f"[StoryWriter] Failed to get task status: {exc}")
+        raise HTTPException(status_code=500, detail=str(exc))
+
+
+@router.get("/task/{task_id}/result")
+async def get_task_result(
+    task_id: str,
+    current_user: Dict[str, Any] = Depends(get_current_user),
+) -> Dict[str, Any]:
+    """Get the result of a completed story generation task."""
+    try:
+        require_authenticated_user(current_user)
+
+        task_status = task_manager.get_task_status(task_id)
+        if not task_status:
+            raise HTTPException(status_code=404, detail=f"Task {task_id} not found")
+        if task_status["status"] != "completed":
+            raise HTTPException(
+                status_code=400,
+                detail=f"Task {task_id} is not completed. Status: {task_status['status']}",
+            )
+
+        result = task_status.get("result")
+        if not result:
+            raise HTTPException(status_code=404, detail=f"No result found for task {task_id}")
+
+        if isinstance(result, dict):
+            payload = {**result}
+            payload.setdefault("success", True)
+            payload["task_id"] = task_id
+            return payload
+
+        return {"result": result, "success": True, "task_id": task_id}
+
+    except HTTPException:
+        raise
+    except Exception as exc:
+        logger.error(f"[StoryWriter] Failed to get task result: {exc}")
+        raise HTTPException(status_code=500, detail=str(exc))
+
+

backend/api/story_writer/routes/video_generation.py

@@ -0,0 +1,511 @@
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from fastapi import APIRouter, BackgroundTasks, Depends, HTTPException
+from fastapi.responses import FileResponse
+from loguru import logger
+from pydantic import BaseModel
+
+from middleware.auth_middleware import get_current_user, get_current_user_with_query_token
+from models.story_models import (
+    StoryVideoGenerationRequest,
+    StoryVideoGenerationResponse,
+    StoryVideoResult,
+    StoryScene,
+    StoryGenerationRequest,
+)
+from services.story_writer.video_generation_service import StoryVideoGenerationService
+from services.story_writer.image_generation_service import StoryImageGenerationService
+from services.story_writer.audio_generation_service import StoryAudioGenerationService
+from services.story_writer.story_service import StoryWriterService
+
+from ..task_manager import task_manager
+from ..utils.auth import require_authenticated_user
+from ..utils.hd_video import (
+    generate_hd_video_payload,
+    generate_hd_video_scene_payload,
+)
+from ..utils.media_utils import resolve_media_file
+
+
+router = APIRouter()
+video_service = StoryVideoGenerationService()
+image_service = StoryImageGenerationService()
+audio_service = StoryAudioGenerationService()
+story_service = StoryWriterService()
+
+
+class HDVideoRequest(BaseModel):
+    prompt: str
+    provider: str = "huggingface"
+    model: str | None = None
+    num_frames: int | None = None
+    guidance_scale: float | None = None
+    num_inference_steps: int | None = None
+    negative_prompt: str | None = None
+    seed: int | None = None
+
+
+class HDVideoSceneRequest(BaseModel):
+    scene_number: int
+    scene_data: Dict[str, Any]
+    story_context: Dict[str, Any]
+    all_scenes: List[Dict[str, Any]]
+    provider: str = "huggingface"
+    model: str | None = None
+    num_frames: int | None = None
+    guidance_scale: float | None = None
+    num_inference_steps: int | None = None
+    negative_prompt: str | None = None
+    seed: int | None = None
+
+
+@router.post("/generate-video", response_model=StoryVideoGenerationResponse)
+async def generate_story_video(
+    request: StoryVideoGenerationRequest,
+    current_user: Dict[str, Any] = Depends(get_current_user),
+) -> StoryVideoGenerationResponse:
+    """Generate a video from story scenes, images, and audio."""
+    try:
+        user_id = require_authenticated_user(current_user)
+
+        if not request.scenes or len(request.scenes) == 0:
+            raise HTTPException(status_code=400, detail="At least one scene is required")
+
+        if len(request.scenes) != len(request.image_urls) or len(request.scenes) != len(request.audio_urls):
+            raise HTTPException(
+                status_code=400,
+                detail="Number of scenes, image URLs, and audio URLs must match",
+            )
+
+        logger.info(f"[StoryWriter] Generating video for {len(request.scenes)} scenes for user {user_id}")
+
+        scenes_data = [scene.dict() if isinstance(scene, StoryScene) else scene for scene in request.scenes]
+        video_paths: List[Optional[str]] = []  # Animated videos (preferred)
+        image_paths: List[Optional[str]] = []  # Static images (fallback)
+        audio_paths: List[str] = []
+        valid_scenes: List[Dict[str, Any]] = []
+
+        # Resolve video/audio directories
+        base_dir = Path(__file__).parent.parent.parent.parent
+        ai_video_dir = (base_dir / "story_videos" / "AI_Videos").resolve()
+
+        video_urls = request.video_urls or [None] * len(request.scenes)
+        ai_audio_urls = request.ai_audio_urls or [None] * len(request.scenes)
+
+        for idx, (scene, image_url, audio_url) in enumerate(zip(scenes_data, request.image_urls, request.audio_urls)):
+            # Prefer animated video if available
+            video_url = video_urls[idx] if idx < len(video_urls) else None
+            video_path = None
+            image_path = None
+
+            if video_url:
+                # Extract filename from animated video URL (e.g., /api/story/videos/ai/filename.mp4)
+                video_filename = video_url.split("/")[-1].split("?")[0]
+                video_path = ai_video_dir / video_filename
+                if video_path.exists():
+                    logger.info(f"[StoryWriter] Using animated video for scene {scene.get('scene_number', idx+1)}: {video_filename}")
+                    video_paths.append(str(video_path))
+                    image_paths.append(None)
+                else:
+                    logger.warning(f"[StoryWriter] Animated video not found: {video_path}, falling back to image")
+                    video_paths.append(None)
+                    video_path = None
+
+            # Fall back to image if no animated video
+            if not video_path:
+                image_filename = image_url.split("/")[-1].split("?")[0]
+                image_path = image_service.output_dir / image_filename
+                if image_path.exists():
+                    video_paths.append(None)
+                    image_paths.append(str(image_path))
+                else:
+                    logger.warning(f"[StoryWriter] Image not found: {image_path} (from URL: {image_url})")
+                    continue
+
+            # Prefer AI audio if available, otherwise use free audio
+            ai_audio_url = ai_audio_urls[idx] if idx < len(ai_audio_urls) else None
+            audio_filename = None
+            audio_path = None
+
+            if ai_audio_url:
+                audio_filename = ai_audio_url.split("/")[-1].split("?")[0]
+                audio_path = audio_service.output_dir / audio_filename
+                if audio_path.exists():
+                    logger.info(f"[StoryWriter] Using AI audio for scene {scene.get('scene_number', idx+1)}: {audio_filename}")
+                else:
+                    logger.warning(f"[StoryWriter] AI audio not found: {audio_path}, falling back to free audio")
+                    audio_path = None
+
+            # Fall back to free audio if no AI audio
+            if not audio_path:
+                audio_filename = audio_url.split("/")[-1].split("?")[0]
+                audio_path = audio_service.output_dir / audio_filename
+                if not audio_path.exists():
+                    logger.warning(f"[StoryWriter] Audio not found: {audio_path} (from URL: {audio_url})")
+                    continue
+
+            audio_paths.append(str(audio_path))
+            valid_scenes.append(scene)
+
+        if len(valid_scenes) == 0 or len(audio_paths) == 0:
+            raise HTTPException(status_code=400, detail="No valid video/image or audio files were found")
+        if len(valid_scenes) != len(audio_paths):
+            raise HTTPException(
+                status_code=400,
+                detail="Number of valid scenes and audio files must match",
+            )
+
+        video_result = video_service.generate_story_video(
+            scenes=valid_scenes,
+            image_paths=image_paths,  # Can contain None for scenes with animated videos
+            video_paths=video_paths,  # Can contain None for scenes with static images
+            audio_paths=audio_paths,
+            user_id=user_id,
+            story_title=request.story_title or "Story",
+            fps=request.fps or 24,
+            transition_duration=request.transition_duration or 0.5,
+        )
+
+        video_model = StoryVideoResult(
+            video_filename=video_result.get("video_filename", ""),
+            video_url=video_result.get("video_url", ""),
+            duration=video_result.get("duration", 0.0),
+            fps=video_result.get("fps", 24),
+            file_size=video_result.get("file_size", 0),
+            num_scenes=video_result.get("num_scenes", 0),
+            error=video_result.get("error"),
+        )
+
+        return StoryVideoGenerationResponse(video=video_model, success=True)
+
+    except HTTPException:
+        raise
+    except Exception as exc:
+        logger.error(f"[StoryWriter] Failed to generate video: {exc}")
+        raise HTTPException(status_code=500, detail=str(exc))
+
+
+@router.post("/generate-video-async", response_model=Dict[str, Any])
+async def generate_story_video_async(
+    request: StoryVideoGenerationRequest,
+    background_tasks: BackgroundTasks,
+    current_user: Dict[str, Any] = Depends(get_current_user),
+) -> Dict[str, Any]:
+    """
+    Generate a video asynchronously with progress updates via task manager.
+    Frontend can poll /api/story/task/{task_id}/status to show progress messages.
+    """
+    try:
+        user_id = require_authenticated_user(current_user)
+
+        if not request.scenes or len(request.scenes) == 0:
+            raise HTTPException(status_code=400, detail="At least one scene is required")
+        if len(request.scenes) != len(request.image_urls) or len(request.scenes) != len(request.audio_urls):
+            raise HTTPException(
+                status_code=400,
+                detail="Number of scenes, image URLs, and audio URLs must match",
+            )
+
+        task_id = task_manager.create_task("story_video_generation")
+        background_tasks.add_task(
+            _execute_video_generation_task,
+            task_id=task_id,
+            request=request,
+            user_id=user_id,
+        )
+        return {"task_id": task_id, "status": "pending", "message": "Video generation started"}
+    except HTTPException:
+        raise
+    except Exception as exc:
+        logger.error(f"[StoryWriter] Failed to start async video generation: {exc}")
+        raise HTTPException(status_code=500, detail=str(exc))
+
+
+def _execute_video_generation_task(task_id: str, request: StoryVideoGenerationRequest, user_id: str):
+    """Background task to generate story video with progress mapped to task manager."""
+    try:
+        task_manager.update_task_status(task_id, "processing", progress=2.0, message="Initializing video generation...")
+
+        scenes_data = [scene.dict() if isinstance(scene, StoryScene) else scene for scene in request.scenes]
+        image_paths: List[str] = []
+        audio_paths: List[str] = []
+        valid_scenes: List[Dict[str, Any]] = []
+
+        for scene, image_url, audio_url in zip(scenes_data, request.image_urls, request.audio_urls):
+            image_filename = image_url.split("/")[-1].split("?")[0]
+            audio_filename = audio_url.split("/")[-1].split("?")[0]
+            image_path = image_service.output_dir / image_filename
+            audio_path = audio_service.output_dir / audio_filename
+            if not image_path.exists():
+                logger.warning(f"[StoryWriter] Image not found: {image_path} (from URL: {image_url})")
+                continue
+            if not audio_path.exists():
+                logger.warning(f"[StoryWriter] Audio not found: {audio_path} (from URL: {audio_url})")
+                continue
+            image_paths.append(str(image_path))
+            audio_paths.append(str(audio_path))
+            valid_scenes.append(scene)
+
+        if not image_paths or not audio_paths or len(image_paths) != len(audio_paths):
+            raise RuntimeError("No valid or mismatched image/audio assets for video generation.")
+
+        def progress_callback(sub_progress: float, msg: str):
+            overall = 5.0 + max(0.0, min(100.0, sub_progress)) * 0.9
+            task_manager.update_task_status(task_id, "processing", progress=overall, message=msg)
+
+        result = video_service.generate_story_video(
+            scenes=valid_scenes,
+            image_paths=image_paths,
+            audio_paths=audio_paths,
+            user_id=user_id,
+            story_title=request.story_title or "Story",
+            fps=request.fps or 24,
+            transition_duration=request.transition_duration or 0.5,
+            progress_callback=progress_callback,
+        )
+
+        task_manager.update_task_status(
+            task_id,
+            "completed",
+            progress=100.0,
+            message="Video generation complete!",
+            result={"video": result, "success": True},
+        )
+    except Exception as exc:
+        logger.error(f"[StoryWriter] Async video generation failed: {exc}", exc_info=True)
+        task_manager.update_task_status(task_id, "failed", error=str(exc), message=f"Video generation failed: {exc}")
+
+
+@router.post("/hd-video")
+async def generate_hd_video(
+    request: HDVideoRequest,
+    current_user: Dict[str, Any] = Depends(get_current_user),
+) -> Dict[str, Any]:
+    try:
+        user_id = require_authenticated_user(current_user)
+        return generate_hd_video_payload(request, user_id)
+    except HTTPException:
+        raise
+    except Exception as exc:
+        logger.error(f"[StoryWriter] Failed to generate HD video: {exc}", exc_info=True)
+        raise HTTPException(status_code=500, detail=str(exc))
+
+
+@router.post("/hd-video-scene")
+async def generate_hd_video_scene(
+    request: HDVideoSceneRequest,
+    current_user: Dict[str, Any] = Depends(get_current_user),
+) -> Dict[str, Any]:
+    try:
+        user_id = require_authenticated_user(current_user)
+        return generate_hd_video_scene_payload(request, user_id)
+    except HTTPException:
+        raise
+    except Exception as exc:
+        logger.error(f"[StoryWriter] Failed to generate HD video for scene: {exc}", exc_info=True)
+        raise HTTPException(status_code=500, detail=str(exc))
+
+
+@router.post("/generate-complete-video", response_model=Dict[str, Any])
+async def generate_complete_story_video(
+    request: StoryGenerationRequest,
+    background_tasks: BackgroundTasks,
+    current_user: Dict[str, Any] = Depends(get_current_user),
+) -> Dict[str, Any]:
+    """Generate a complete story video workflow asynchronously."""
+    try:
+        user_id = require_authenticated_user(current_user)
+        logger.info(f"[StoryWriter] Starting complete video generation for user {user_id}")
+
+        task_id = task_manager.create_task("complete_video_generation")
+        background_tasks.add_task(
+            execute_complete_video_generation,
+            task_id=task_id,
+            request_data=request.dict(),
+            user_id=user_id,
+        )
+
+        return {
+            "task_id": task_id,
+            "status": "pending",
+            "message": "Complete video generation started",
+        }
+
+    except HTTPException:
+        raise
+    except Exception as exc:
+        logger.error(f"[StoryWriter] Failed to start complete video generation: {exc}")
+        raise HTTPException(status_code=500, detail=str(exc))
+
+
+def execute_complete_video_generation(
+    task_id: str,
+    request_data: Dict[str, Any],
+    user_id: str,
+):
+    """
+    Execute complete video generation workflow synchronously.
+    Runs in a background task and performs blocking operations.
+    """
+    try:
+        task_manager.update_task_status(task_id, "processing", progress=5.0, message="Starting complete video generation...")
+
+        task_manager.update_task_status(task_id, "processing", progress=10.0, message="Generating story premise...")
+        premise = story_service.generate_premise(
+            persona=request_data["persona"],
+            story_setting=request_data["story_setting"],
+            character_input=request_data["character_input"],
+            plot_elements=request_data["plot_elements"],
+            writing_style=request_data["writing_style"],
+            story_tone=request_data["story_tone"],
+            narrative_pov=request_data["narrative_pov"],
+            audience_age_group=request_data["audience_age_group"],
+            content_rating=request_data["content_rating"],
+            ending_preference=request_data["ending_preference"],
+            user_id=user_id,
+        )
+
+        task_manager.update_task_status(task_id, "processing", progress=20.0, message="Generating structured outline with scenes...")
+        outline_scenes = story_service.generate_outline(
+            premise=premise,
+            persona=request_data["persona"],
+            story_setting=request_data["story_setting"],
+            character_input=request_data["character_input"],
+            plot_elements=request_data["plot_elements"],
+            writing_style=request_data["writing_style"],
+            story_tone=request_data["story_tone"],
+            narrative_pov=request_data["narrative_pov"],
+            audience_age_group=request_data["audience_age_group"],
+            content_rating=request_data["content_rating"],
+            ending_preference=request_data["ending_preference"],
+            user_id=user_id,
+            use_structured_output=True,
+        )
+
+        if not isinstance(outline_scenes, list):
+            raise RuntimeError("Failed to generate structured outline")
+
+        task_manager.update_task_status(task_id, "processing", progress=30.0, message="Generating images for scenes...")
+
+        def image_progress_callback(sub_progress: float, message: str):
+            overall_progress = 30.0 + (sub_progress * 0.2)
+            task_manager.update_task_status(task_id, "processing", progress=overall_progress, message=message)
+
+        image_results = image_service.generate_scene_images(
+            scenes=outline_scenes,
+            user_id=user_id,
+            provider=request_data.get("image_provider"),
+            width=request_data.get("image_width", 1024),
+            height=request_data.get("image_height", 1024),
+            model=request_data.get("image_model"),
+            progress_callback=image_progress_callback,
+        )
+
+        task_manager.update_task_status(task_id, "processing", progress=50.0, message="Generating audio narration for scenes...")
+
+        def audio_progress_callback(sub_progress: float, message: str):
+            overall_progress = 50.0 + (sub_progress * 0.2)
+            task_manager.update_task_status(task_id, "processing", progress=overall_progress, message=message)
+
+        audio_results = audio_service.generate_scene_audio_list(
+            scenes=outline_scenes,
+            user_id=user_id,
+            provider=request_data.get("audio_provider", "gtts"),
+            lang=request_data.get("audio_lang", "en"),
+            slow=request_data.get("audio_slow", False),
+            rate=request_data.get("audio_rate", 150),
+            progress_callback=audio_progress_callback,
+        )
+
+        task_manager.update_task_status(task_id, "processing", progress=70.0, message="Preparing video assets...")
+        image_paths: List[str] = []
+        audio_paths: List[str] = []
+        valid_scenes: List[Dict[str, Any]] = []
+
+        for scene in outline_scenes:
+            scene_number = scene.get("scene_number", 0)
+            image_result = next((img for img in image_results if img.get("scene_number") == scene_number), None)
+            audio_result = next((aud for aud in audio_results if aud.get("scene_number") == scene_number), None)
+
+            if image_result and audio_result and not image_result.get("error") and not audio_result.get("error"):
+                image_path = image_result.get("image_path")
+                audio_path = audio_result.get("audio_path")
+                if image_path and audio_path:
+                    image_paths.append(image_path)
+                    audio_paths.append(audio_path)
+                    valid_scenes.append(scene)
+
+        if len(image_paths) == 0 or len(audio_paths) == 0:
+            raise RuntimeError(
+                f"No valid images or audio files were generated. Images: {len(image_paths)}, Audio: {len(audio_paths)}"
+            )
+        if len(image_paths) != len(audio_paths):
+            raise RuntimeError(
+                f"Mismatch between image and audio counts. Images: {len(image_paths)}, Audio: {len(audio_paths)}"
+            )
+
+        task_manager.update_task_status(task_id, "processing", progress=75.0, message="Composing video from scenes...")
+
+        def video_progress_callback(sub_progress: float, message: str):
+            overall_progress = 75.0 + (sub_progress * 0.2)
+            task_manager.update_task_status(task_id, "processing", progress=overall_progress, message=message)
+
+        video_result = video_service.generate_story_video(
+            scenes=valid_scenes,
+            image_paths=image_paths,
+            audio_paths=audio_paths,
+            user_id=user_id,
+            story_title=request_data.get("story_setting", "Story")[:50],
+            fps=request_data.get("video_fps", 24),
+            transition_duration=request_data.get("video_transition_duration", 0.5),
+            progress_callback=video_progress_callback,
+        )
+
+        result = {
+            "premise": premise,
+            "outline_scenes": outline_scenes,
+            "images": image_results,
+            "audio_files": audio_results,
+            "video": video_result,
+            "success": True,
+        }
+
+        task_manager.update_task_status(
+            task_id,
+            "completed",
+            progress=100.0,
+            message="Complete video generation finished!",
+            result=result,
+        )
+
+        logger.info(f"[StoryWriter] Complete video generation task {task_id} completed successfully")
+
+    except Exception as exc:
+        error_msg = str(exc)
+        logger.error(f"[StoryWriter] Complete video generation task {task_id} failed: {error_msg}", exc_info=True)
+        task_manager.update_task_status(
+            task_id,
+            "failed",
+            error=error_msg,
+            message=f"Complete video generation failed: {error_msg}",
+        )
+
+
+@router.get("/videos/{video_filename}")
+async def serve_story_video(
+    video_filename: str,
+    current_user: Dict[str, Any] = Depends(get_current_user),
+):
+    """Serve a generated story video file."""
+    try:
+        require_authenticated_user(current_user)
+        video_path = resolve_media_file(video_service.output_dir, video_filename)
+        return FileResponse(path=str(video_path), media_type="video/mp4", filename=video_filename)
+    except HTTPException:
+        raise
+    except Exception as exc:
+        logger.error(f"[StoryWriter] Failed to serve video: {exc}")
+        raise HTTPException(status_code=500, detail=str(exc))
+
+