# Kling 4 vs Seedance 2.5 — AI Video Model Router API

## PURPOSE
This FastAPI service routes a text-to-video (or image-to-video) request to the
cheapest AI video model that still meets the shot's requirements. The video this
is based on compares Kling 4.0 and Seedance 2.5 directly: Kling 4 is roughly 70%
cheaper, supports up to 10 key frames and 30-second clips, while Seedance 2.5
wins on physics realism (glass shatter, droplet variety) and remains the host's
preferred pick for specific sequences. A third, cheaper tier (LTX 2.5) is used
for "pedestrian" shots. The router encodes those trade-offs as code so a team
does not overpay for simple shots or underspend on complex action.

## WHY THIS MATTERS
The transcript's central economics lesson: a 5-second 1080p clip costs about
$0.80 on Kling 4 versus roughly $2.85 through Seedance 2.5's official API — yet
realism and censorship behaviour differ. That is a classic routing problem: given
a prompt profile, pick the model that maximises value. Students learn to model
capability (max duration, key-frame count, aspect ratio, languages) as data and
turn a subjective "which model is better" debate into a deterministic policy.

## HOW TO BUILD
1. `pip install fastapi uvicorn pydantic`
2. Define a `ShotRequest` (prompt, duration_seconds, needs_physics, keyframes,
   languages) and a `ModelSpec` catalog.
3. Implement `select_model()` — score each candidate by capability fit, then
   break ties on cost.
4. Expose `POST /route` and `GET /models`. Stub the actual generation call.

```python
def select_model(req: ShotRequest, catalog: list[ModelSpec]) -> RoutingDecision:
    fits = [m for m in catalog if m.max_seconds >= req.duration_seconds
            and m.max_keyframes >= req.keyframes]
    if req.needs_high_physics:
        fits.sort(key=lambda m: (not m.strong_physics, m.cost_5s_1080p))
    else:
        fits.sort(key=lambda m: m.cost_5s_1080p)
    return RoutingDecision(chosen=fits[0], rationale="cheapest viable tier")
```

## WHEN TO USE IN PRODUCTION
Use it as the front door of an internal content pipeline so editors submit a
shot description and the platform bills the right tier, or to enforce a per-shot
budget cap. Do NOT use it when a single premium model is mandated by contract,
when latency of the routing call itself matters more than cost, or for shots
requiring creative judgement a human should make.

## HOW IT HELPS STUDENTS
Learners practise Pydantic validation, dependency-light service design, and
translating a qualitative model comparison into a testable decision function —
exactly the reasoning a platform team needs when aggregating multiple vendors.

## STARTER CODE
See `starter/main.py` for a runnable FastAPI skeleton with a deterministic
`fake_generate()` stub and `# TODO` markers for real vendor SDK integration.
