# How to Use the MoneyPrinterTurbo API: A Complete Guide to Automated Video Generation

> Learn to use the MoneyPrinterTurbo API for automated video generation. This guide covers programmatic video, subtitle, and audio track creation via HTTP requests.

- Repository: [Harry/MoneyPrinterTurbo](https://github.com/harry0703/MoneyPrinterTurbo)
- Tags: how-to-guide
- Published: 2026-03-23

---

**The MoneyPrinterTurbo API is a FastAPI-based service that lets you programmatically generate short videos, subtitles, and audio tracks by sending HTTP requests to endpoints like `POST /api/v1/videos` and polling `GET /api/v1/tasks/{task_id}` for results.**

MoneyPrinterTurbo is an open-source project that exposes a RESTful API for automated video creation. The service runs on FastAPI and organizes all endpoints under the `/api/v1` prefix, handling everything from video generation to asset management. This guide explains how to interact with the MoneyPrinterTurbo API using practical examples derived directly from the source code.

## API Architecture and Endpoint Overview

The MoneyPrinterTurbo API splits functionality into logical groups mounted on a root `APIRouter` defined in [`app/router.py`](https://github.com/harry0703/MoneyPrinterTurbo/blob/main/app/router.py) (lines 14-18). The router includes two version-1 sub-routers: one for video operations and one for LLM helpers.

### Core Video Generation Endpoints

These endpoints initiate asynchronous media creation tasks:

- **`POST /api/v1/videos`** – Creates a full video generation task using parameters defined in the `TaskVideoRequest` model.
- **`POST /api/v1/subtitle`** – Generates subtitle files only, using the `SubtitleRequest` model.
- **`POST /api/v1/audio`** – Synthesizes audio tracks only, using the `AudioRequest` model.

### Task Management and Asset Handling

After creating a task, use these endpoints to monitor progress and manage resources:

- **`GET /api/v1/tasks`** – Lists all tasks with their current status.
- **`GET /api/v1/tasks/{task_id}`** – Retrieves detailed status, progress percentage, and URLs for generated files.
- **`DELETE /api/v1/tasks/{task_id}`** – Removes a task and its associated files.
- **`GET /api/v1/musics`** / **`POST /api/v1/musics`** – Lists or uploads local BGM files.
- **`GET /api/v1/video_materials`** / **`POST /api/v1/video_materials`** – Lists or uploads video material files.
- **`GET /api/v1/stream/{file_path}`** – HTTP range streaming for playback.
- **`GET /api/v1/download/{file_path}`** – Direct file download.

## Request and Response Models

All request bodies are Pydantic models defined in [`app/models/schema.py`](https://github.com/harry0703/MoneyPrinterTurbo/blob/main/app/models/schema.py). Understanding these schemas is essential for constructing valid API calls.

Key models include:

- **`TaskVideoRequest`** (inherits `VideoParams`) – Used for `POST /videos`. Important fields: `video_subject`, `video_aspect`, `voice_name`, `bgm_type`, `font_name`, `paragraph_number`.
- **`SubtitleRequest`** – Used for `POST /subtitle`. Fields: `video_script`, `voice_name`, `bgm_type`, `subtitle_position`, `font_name`.
- **`AudioRequest`** – Used for `POST /audio`. Same fields as `SubtitleRequest` but produces audio-only output.
- **`VideoScriptRequest`** – Used for `POST /scripts`. Fields: `video_subject`, `video_language`, `paragraph_number`.
- **`VideoTermsRequest`** – Used for `POST /terms`. Fields: `video_subject`, `video_script`, `amount`.
- **`TaskResponse`** – Returned by creation endpoints. Contains the generated `task_id`.
- **`TaskQueryResponse`** – Returned by `GET /tasks/{task_id}`. Contains `state`, `progress`, `videos`, and `combined_videos` URLs.

## How the API Processes Requests

Understanding the internal flow helps debug failed requests and optimize usage. The request lifecycle follows this path:

1. **Router Dispatch** – FastAPI routes the HTTP request to the appropriate function in [`app/controllers/v1/video.py`](https://github.com/harry0703/MoneyPrinterTurbo/blob/main/app/controllers/v1/video.py) (for media tasks) or [`app/controllers/v1/llm.py`](https://github.com/harry0703/MoneyPrinterTurbo/blob/main/app/controllers/v1/llm.py) (for script generation).

2. **Task Creation** – The `create_task()` function (line 77 in [`video.py`](https://github.com/harry0703/MoneyPrinterTurbo/blob/main/video.py)) generates a UUID, stores a placeholder in the state manager ([`app/services/state.py`](https://github.com/harry0703/MoneyPrinterTurbo/blob/main/app/services/state.py)), and enqueues the work via a TaskManager.

3. **Task Management** – Depending on the `enable_redis` setting in [`app/config/config.py`](https://github.com/harry0703/MoneyPrinterTurbo/blob/main/app/config/config.py), the system uses either:
   - **InMemoryTaskManager** ([`app/controllers/manager/memory_manager.py`](https://github.com/harry0703/MoneyPrinterTurbo/blob/main/app/controllers/manager/memory_manager.py)) for single-node deployments.
   - **RedisTaskManager** ([`app/controllers/manager/redis_manager.py`](https://github.com/harry0703/MoneyPrinterTurbo/blob/main/app/controllers/manager/redis_manager.py)) for distributed processing.

4. **Background Processing** – The task runs the coroutine `app/services/task.py::start`, which orchestrates LLM calls ([`app/services/llm.py`](https://github.com/harry0703/MoneyPrinterTurbo/blob/main/app/services/llm.py)), voice synthesis, video clipping, and final composition. Intermediate files are stored in `utils.task_dir()` ([`app/utils/utils.py`](https://github.com/harry0703/MoneyPrinterTurbo/blob/main/app/utils/utils.py)).

5. **State Updates** – The `State` object tracks progress and file paths. When complete, `get_task()` (line 30 in [`video.py`](https://github.com/harry0703/MoneyPrinterTurbo/blob/main/video.py)) transforms these into public URLs.

6. **Client Response** – The API immediately returns a `TaskResponse` with the `task_id`. Clients must poll `GET /api/v1/tasks/{task_id}` to retrieve final download URLs.

## Practical Code Examples

These Python snippets demonstrate typical client interactions using `httpx`. You can substitute any HTTP client (requests, aiohttp, curl).

### Creating a Video Generation Task

Submit a request to `POST /api/v1/videos` with a JSON payload matching the `TaskVideoRequest` schema:

```python
import httpx

BASE = "http://localhost:8080/api/v1"
task_payload = {
    "video_subject": "A sunny beach sunrise",
    "video_aspect": "landscape",
    "voice_name": "en-US-Standard-A",
    "bgm_type": "random",
    "font_name": "STHeitiMedium.ttc",
    "paragraph_number": 2,
}

resp = httpx.post(f"{BASE}/videos", json=task_payload)
result = resp.json()
print(result)  # → {"status":200,"message":"success","data":{"task_id":"..."}}

task_id = result["data"]["task_id"]

```

### Polling for Task Completion

Query the task status using `GET /api/v1/tasks/{task_id}` until the `state` indicates completion:

```python
import time
import httpx

while True:
    r = httpx.get(f"{BASE}/tasks/{task_id}")
    data = r.json()["data"]
    
    print(f"State: {data.get('state')} – Progress: {data.get('progress')}%")
    
    if data.get("videos"):
        print("Video URLs:", data["videos"])
        break
        
    time.sleep(2)

```

### Generating Scripts via LLM Helpers

Use `POST /api/v1/scripts` to generate video scripts without creating a full task:

```python
script_req = {
    "video_subject": "Spring cherry blossoms",
    "video_language": "en",
    "paragraph_number": 1,
}

r = httpx.post(f"{BASE}/scripts", json=script_req)
print(r.json()["data"]["video_script"])

```

### Uploading Custom BGM Files

Add background music to the local library using `POST /api/v1/musics` with multipart form data:

```python
files = {"file": ("mytrack.mp3", open("mytrack.mp3", "rb"), "audio/mpeg")}
r = httpx.post(f"{BASE}/musics", files=files)
print(r.json()["data"]["file"])  # Returns absolute path on server

```

### Streaming Generated Videos

Play videos before full download using `GET /api/v1/stream/{file_path}` with HTTP range headers:

```python
video_url = f"{BASE}/stream/6c85c8cc-a77a-42b9-bc30-947815aa0558/final-1.mp4"

with httpx.stream("GET", video_url, headers={"Range": "bytes=0-1023"}) as resp:
    for chunk in resp.iter_bytes():
        # Feed chunk to media player or write to file

        pass

```

## Key Source Files and Their Roles

Understanding the codebase structure helps when debugging or extending the MoneyPrinterTurbo API:

| File | Role |
|------|------|
| **[`app/router.py`](https://github.com/harry0703/MoneyPrinterTurbo/blob/main/app/router.py)** | Root `APIRouter` that mounts all version-1 routers. |
| **[`app/controllers/v1/video.py`](https://github.com/harry0703/MoneyPrinterTurbo/blob/main/app/controllers/v1/video.py)** | Implements media generation endpoints (`create_task`, `get_task`) and asset management. |
| **[`app/controllers/v1/llm.py`](https://github.com/harry0703/MoneyPrinterTurbo/blob/main/app/controllers/v1/llm.py)** | Helper endpoints for script and keyword generation via LLM. |
| **[`app/models/schema.py`](https://github.com/harry0703/MoneyPrinterTurbo/blob/main/app/models/schema.py)** | Pydantic schemas for all request/response models (`TaskVideoRequest`, `TaskResponse`, etc.). |
| **[`app/services/state.py`](https://github.com/harry0703/MoneyPrinterTurbo/blob/main/app/services/state.py)** | In-memory state management for task progress and file paths. |
| **[`app/controllers/manager/base_manager.py`](https://github.com/harry0703/MoneyPrinterTurbo/blob/main/app/controllers/manager/base_manager.py)** | Abstract `TaskManager` interface. |
| **[`app/controllers/manager/memory_manager.py`](https://github.com/harry0703/MoneyPrinterTurbo/blob/main/app/controllers/manager/memory_manager.py)** | In-memory task queue implementation using Python threads. |
| **[`app/controllers/manager/redis_manager.py`](https://github.com/harry0703/MoneyPrinterTurbo/blob/main/app/controllers/manager/redis_manager.py)** | Redis-backed distributed task queue. |
| **[`app/services/task.py`](https://github.com/harry0703/MoneyPrinterTurbo/blob/main/app/services/task.py)** | Core pipeline orchestrating LLM calls, voice synthesis, and video composition. |
| **[`app/utils/utils.py`](https://github.com/harry0703/MoneyPrinterTurbo/blob/main/app/utils/utils.py)** | Utility functions including `task_dir()` for file path generation. |
| **[`app/config/config.py`](https://github.com/harry0703/MoneyPrinterTurbo/blob/main/app/config/config.py)** | Configuration settings including `enable_redis` and `max_concurrent_tasks`. |
| **[`app/asgi.py`](https://github.com/harry0703/MoneyPrinterTurbo/blob/main/app/asgi.py)** | FastAPI application entry point. |

## Running the Service Locally

To start the MoneyPrinterTurbo API server locally, instantiate the FastAPI app from [`app/asgi.py`](https://github.com/harry0703/MoneyPrinterTurbo/blob/main/app/asgi.py) using an ASGI server like Uvicorn:

```bash
uvicorn app.asgi:app --host 0.0.0.0 --port 8080

```

By default, the service stores generated files under `storage/tasks/` and static assets under `resource/`. Once running, interactive API documentation is available at `http://localhost:8080/docs`, generated automatically from the FastAPI router definitions in [`app/router.py`](https://github.com/harry0703/MoneyPrinterTurbo/blob/main/app/router.py).

## Summary

- The **MoneyPrinterTurbo API** is a FastAPI service exposing REST endpoints under `/api/v1` for automated video generation.
- **Core endpoints** include `POST /videos` for creating tasks, `GET /tasks/{task_id}` for polling status, and `POST /scripts` for LLM-powered script generation.
- **Request models** like `TaskVideoRequest` and `TaskResponse` are defined in [`app/models/schema.py`](https://github.com/harry0703/MoneyPrinterTurbo/blob/main/app/models/schema.py) and enforce type safety via Pydantic.
- **Background processing** uses a TaskManager abstraction (`app/controllers/manager/`) that supports both in-memory and Redis-backed queues depending on the `enable_redis` configuration.
- **File handling** stores intermediate assets in `storage/tasks/` and serves completed videos via `/stream` and `/download` endpoints with HTTP range support.

## Frequently Asked Questions

### What is the base URL for the MoneyPrinterTurbo API?

The base URL follows the pattern `http://localhost:8080/api/v1` when running locally. All endpoints are prefixed with `/api/v1`, such as `/api/v1/videos` for creating tasks and `/api/v1/tasks/{task_id}` for querying status.

### How do I check the status of a video generation task?

Send a GET request to `/api/v1/tasks/{task_id}` where `task_id` is the UUID returned by the initial POST request. The response includes a `state` field (pending, processing, completed), a `progress` percentage, and `videos` array containing download URLs when finished.

### Can I use Redis for distributed task processing?

Yes. Set `enable_redis: true` in [`app/config/config.py`](https://github.com/harry0703/MoneyPrinterTurbo/blob/main/app/config/config.py) to switch from the default `InMemoryTaskManager` to `RedisTaskManager` defined in [`app/controllers/manager/redis_manager.py`](https://github.com/harry0703/MoneyPrinterTurbo/blob/main/app/controllers/manager/redis_manager.py). This allows multiple worker instances to process tasks from a shared Redis queue.

### Where are generated video files stored?

Generated files are stored in the `storage/tasks/` directory by default, organized by task ID subdirectories. The `utils.task_dir()` function in [`app/utils/utils.py`](https://github.com/harry0703/MoneyPrinterTurbo/blob/main/app/utils/utils.py) handles path generation. Completed videos are served via the `/api/v1/stream/{file_path}` and `/api/v1/download/{file_path}` endpoints.