API Documentation

Integrate AI video generation directly into your application.

Introduction

Welcome to the video.pizza API. Our REST API allows you to programmatically access the full power of our AI video generation engine. You can integrate video creation, management, and scheduling directly into your own applications, workflows, or services. The base URL for all API endpoints is `https://video.pizza/api`.

Getting Started

To get started, you'll need to register an account, obtain an access token, and then you can start making requests to the generation endpoints. Below is a complete Python example demonstrating the entire flow from authentication to polling for a finished video.

Python Example:
import requests
import time
import os

# --- Configuration ---
API_BASE_URL = "https://video.pizza/api"
# It's recommended to use environment variables for credentials
USER_IDENTIFIER = os.environ.get("VIDEOPizza_USER", "your_username_or_email")
USER_PASSWORD = os.environ.get("VIDEOPizza_PASSWORD", "your_password")

def get_auth_token():
    """Authenticates to get a JWT access token."""
    print("Authenticating...")
    response = requests.post(f"{API_BASE_URL}/auth/login", json={
        "identifier": USER_IDENTIFIER,
        "password": USER_PASSWORD
    })
    response.raise_for_status()
    return response.json()['access_token']

def start_video_generation(token):
    """Starts a video generation task."""
    print("Starting video generation...")
    headers = {'Authorization': f'Bearer {token}'}
    form_data = {
        'prompt': 'A short documentary on the Roman Empire.',
        'video_source': 'ai_scenery',
        'ai_scenery_prompt': 'Cinematic, photorealistic, 4k, epic lighting.',
        'video_format': '16:9',
        'add_music': 'true',
        'burn_captions': 'true',
    }
    response = requests.post(f"{API_BASE_URL}/generate", headers=headers, data=form_data)
    response.raise_for_status()
    return response.json()['task_id']

def poll_task_status(task_id, token):
    """Polls the status of the generation task."""
    print(f"Polling status for task {task_id}...")
    headers = {'Authorization': f'Bearer {token}'}
    while True:
        response = requests.get(f"{API_BASE_URL}/status/{task_id}", headers=headers)
        response.raise_for_status()
        data = response.json()
        status = data.get('status')
        print(f"Current status: {status}")
        if status in ['completed', 'failed']:
            print(f"Final video details: {data}")
            break
        time.sleep(15)

if __name__ == "__main__":
    try:
        access_token = get_auth_token()
        task_id = start_video_generation(access_token)
        poll_task_status(task_id, access_token)
    except requests.exceptions.RequestException as e:
        print(f"An API error occurred: {e}")
        if e.response:
            print(f"Response Body: {e.response.text}")

Endpoints

Authentication

The video.pizza API uses JWT (JSON Web Tokens) for authentication. All protected API requests must include an `Authorization` header with a Bearer token: Authorization: Bearer <YOUR_ACCESS_TOKEN>.

Register User

POST/api/auth/register

Creates a new user account.

Request Body (JSON):
{
    "email": "[email protected]",
    "username": "newuser",
    "password": "strong_password_123"
}
Success Response (201 Created):
{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Login with Credentials

POST/api/auth/login

Authenticates with email/username and password to get a JWT.

Request Body (JSON):
{
    "identifier": "your_username_or_email",
    "password": "your_password"
}

Login with API Key

POST/api/auth/login_with_key

Authenticates with a pre-generated API key to receive a JWT access token. You can generate a key in your dashboard settings.

Request Body (JSON):
{
    "api_key": "your_generated_api_key_here"
}

User & API Keys

Generate API Key

POST/api/user/api-key

Generates a new, persistent API key for the authenticated user. This is the only time the key will be shown.

Success Response (200 OK):
{
    "msg": "API key generated successfully. This is the only time you will see it.",
    "api_key": "c2b5e2a8a1c4b3f8d7e6..."
}

Video Generation

Generate a Video

POST/api/generate

Starts a video generation task. This endpoint accepts `multipart/form-data` for file uploads. All parameters are strings unless specified.

Form Data Parameters:
  • `audio_source_type` (required): `generate` or `upload`.
  • `prompt` (required if `audio_source_type` is `generate`): The text prompt for the video script.
  • `mp3_file` (required if `audio_source_type` is `upload`): The audio file (file part).
  • `video_format` (optional, default: `9:16`): `16:9`, `9:16`, `1:1`, `4:5`.
  • `video_source` (optional, default: `stock`):
    • `stock`: AI-selected stock videos.
    • `ai_scenery`: AI-generated images for each scene.
    • `background_youtube`, `background_minecraft`, `background_subway`: Static gameplay backgrounds.
  • `ai_scenery_prompt` (required if `video_source` is `ai_scenery`): A detailed prompt describing the desired visual style (e.g., `cinematic, photorealistic, 4k`).
  • `burn_captions` (optional, default: `false`): `true` or `false`.
  • `caption_style` (optional, default: `default`): `classic`, `clonevest`, `segnals`.
  • `text_transform` (optional, default: `standard`): `standard`, `uppercase`.
  • `add_music` (optional, default: `false`): `true` or `false`.
  • `add_sound_effects` (optional, default: `false`): `true` or `false`.
Success Response (202 Accepted):
{
    "task_id": "a1b2c3d4-e5f6-...",
    "msg": "Video generation started."
}

Get Task Status

GET/api/status/<task_id>

Poll this endpoint to check the status of a generation task. Returns `processing`, `completed`, or `failed`.

Success Response (200 OK) - Completed:
{
    "status": "completed",
    "task_id": "a1b2c3d4-e5f6-...",
    "video_url": "https://video.pizza/static/videos/.../final_video.mp4",
    "details": {
        "id": 123,
        "prompt": "A short, inspiring documentary...",
        "created_at": "2025-10-15T19:55:00.123Z",
        "youtube_title": "The Future of Space Exploration",
        "youtube_description": "A deep dive into what comes next...",
        "instagram_caption": null
    }
}

Video Management

List All Videos

GET/api/videos

Returns a paginated list of all completed videos for the authenticated user.

Success Response (200 OK):
{
    "videos": [
        {
            "id": 123,
            "prompt": "A short, inspiring documentary...",
            "video_url": "https://video.pizza/static/videos/.../final.mp4",
            "status": "completed",
            "created_at": "2025-10-15T19:55:00.123Z"
        }
    ]
}

Delete a Video

DELETE/api/videos/<video_id>

Permanently deletes a video record. Note: file cleanup is handled by a separate scheduled task.