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

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 (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. 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 (for media tasks) or app/controllers/v1/llm.py (for script generation).

2. Task Creation – The create_task() function (line 77 in video.py) generates a UUID, stores a placeholder in the state manager (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, the system uses either:

   • InMemoryTaskManager (app/controllers/manager/memory_manager.py) for single-node deployments.
   • RedisTaskManager (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), voice synthesis, video clipping, and final composition. Intermediate files are stored in utils.task_dir() (app/utils/utils.py).

5. State Updates – The State object tracks progress and file paths. When complete, get_task() (line 30 in 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:

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:

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:

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:

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:

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	Root APIRouter that mounts all version-1 routers.
app/controllers/v1/video.py	Implements media generation endpoints (create_task, get_task) and asset management.
app/controllers/v1/llm.py	Helper endpoints for script and keyword generation via LLM.
app/models/schema.py	Pydantic schemas for all request/response models (TaskVideoRequest, TaskResponse, etc.).
app/services/state.py	In-memory state management for task progress and file paths.
app/controllers/manager/base_manager.py	Abstract TaskManager interface.
app/controllers/manager/memory_manager.py	In-memory task queue implementation using Python threads.
app/controllers/manager/redis_manager.py	Redis-backed distributed task queue.
app/services/task.py	Core pipeline orchestrating LLM calls, voice synthesis, and video composition.
app/utils/utils.py	Utility functions including task_dir() for file path generation.
app/config/config.py	Configuration settings including enable_redis and max_concurrent_tasks.
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 using an ASGI server like Uvicorn:

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.

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 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 to switch from the default InMemoryTaskManager to RedisTaskManager defined in 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 handles path generation. Completed videos are served via the /api/v1/stream/{file_path} and /api/v1/download/{file_path} endpoints.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}