# Start dev server (serves both API and frontend at http://localhost:8000)

> This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

- Skill: `tools-only/start-dev-server-serves-both-api-and-frontend-at-http` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/start-dev-server-serves-both-api-and-frontend-at-http`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/start-dev-server-serves-both-api-and-frontend-at-http/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-29
- Page: https://skillmd.com/skills/tools-only/start-dev-server-serves-both-api-and-frontend-at-http

---

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Commands

```bash
# Start dev server (serves both API and frontend at http://localhost:8000)
python -m backend.main

# Install dependencies
pip install -r backend/requirements.txt

# Test MiniMax API connectivity
python backend/test_minimax.py

# Required system dependency
# ffmpeg must be installed (brew install ffmpeg)
```

No build step, no linting, no test suite. Frontend is a single HTML file served via FastAPI StaticFiles.

## Architecture

Multi-agent video production pipeline. User prompt goes through 6 sequential agents, producing a final MP4.

```
POST /api/create  -->  background thread runs pipeline  -->  SSE via GET /api/stream/{job_id}

Pipeline stages (sequential):
  Director (MiniMax M1 LLM)    -> shot outline JSON
  Script   (MiniMax M1 LLM)    -> production script with video_prompt, narration, subtitle per shot
  Visual   (Hailuo 2.3 video)  -> parallel video clips (ThreadPoolExecutor, max_workers=3)
  Voice    (Speech-2.6-HD TTS) -> sequential narration audio per shot
  Music    (Music-2.0)         -> single background track (optional)
  Editor   (ffmpeg)            -> concat videos, mix audio, burn subtitles -> final.mp4
```

**Key data flow:** Each agent's `run()` returns structured data consumed by the next agent. Director outputs `{title, style, total_duration, shots[]}`. Script enriches each shot with `video_prompt` (optimized for Hailuo), polished `narration`, and `subtitle`. Visual/Voice/Music produce file paths. Editor composites everything via ffmpeg subprocess calls.

**Job lifecycle:** `main.py` stores jobs in an in-memory dict. Pipeline runs in `run_in_executor` (background thread). Progress events accumulate in `jobs[job_id]["events"]` list, polled by SSE endpoint every 1s.

**Frontend-backend coupling:** Frontend JS references stages by name (`director`, `script`, `visual`, `voice`, `music`, `editor`) in `stageMap` to highlight corresponding UI cards. These stage names must match `pipeline.py` emit calls.

## Key Conventions

- Every agent module in `backend/agents/` exposes a `run()` function as its sole public interface
- All MiniMax API calls must check `data["base_resp"]["status_code"] != 0` before accessing response payload -- API returns HTTP 200 even on business errors (insufficient balance, rate limit, etc.)
- LLM agents (director, script) strip markdown code fences from responses before JSON parsing
- Frontend uses relative API paths (`/api/...`). FastAPI `app.mount("/", StaticFiles(...))` must be registered after all API routes
- Generated media files go to `backend/output/` (gitignored). Config auto-creates this directory on import.
- Environment: single `.env` file at project root with `MINIMAX_API_KEY`

## Mistakes Log

| Mistake | Fix |
|---------|-----|
| MiniMax API 余额不足时 `choices` 为空，取值抛 NoneType | 先检查 `base_resp.status_code != 0` 再取 `choices` |
| `app.mount("/", StaticFiles(...))` 拦截 API 路由 | 必须放在所有 `@app` 路由注册之后 |
| Hailuo video generation 是异步的，直接取结果会失败 | 必须 POST 创建任务 -> 轮询 query 接口 -> 下载文件，三步走 |