API Overview

Pixelle-Video provides both Python SDK and HTTP REST API.

---

Python SDK

PixelleVideoCore

Main service class providing video generation functionality.

from pixelle_video.service import PixelleVideoCore

pixelle = PixelleVideoCore()
await pixelle.initialize()

generate_video()

Primary method for generating videos.

Parameters:

• text (str): Topic or complete script
• mode (str): Generation mode ("generate" or "fixed")
• n_scenes (int): Number of scenes
• title (str, optional): Video title
• tts_workflow (str): TTS workflow
• media_workflow (str): Media generation workflow (image or video)
• frame_template (str): Video template
• template_params (dict, optional): Custom template parameters
• bgm_path (str, optional): BGM file path
• bgm_volume (float): BGM volume (0.0-1.0)

Returns: VideoResult object

---

HTTP REST API

Start the API server:

uv run uvicorn api.app:app --host 0.0.0.0 --port 8000

Video Generation - Synchronous

POST /api/video/generate/sync

Generate video synchronously, waits until completion. Suitable for small videos (< 30 seconds).

Request Body:

{
  "text": "Why you should develop a reading habit",
  "mode": "generate",
  "n_scenes": 5,
  "frame_template": "1080x1920/image_default.html",
  "template_params": {
    "accent_color": "#3498db",
    "background": "https://example.com/custom-bg.jpg"
  },
  "title": "The Power of Reading"
}

Response:

{
  "success": true,
  "message": "Success",
  "video_url": "http://localhost:8000/api/files/xxx/final.mp4",
  "duration": 45.5,
  "file_size": 12345678
}

Video Generation - Asynchronous

POST /api/video/generate/async

Generate video asynchronously, returns task ID immediately. Suitable for large videos.

Response:

{
  "success": true,
  "message": "Task created successfully",
  "task_id": "abc123"
}

Query Task Status

GET /api/tasks/{task_id}

Response:

{
  "task_id": "abc123",
  "status": "completed",
  "result": {
    "video_url": "http://localhost:8000/api/files/xxx/final.mp4",
    "duration": 45.5,
    "file_size": 12345678
  }
}

---

Request Parameters

Parameter	Type	Required	Description
text	string	Yes	Topic or complete script
mode	string	No	"generate" (AI generates) or "fixed" (use text as-is)
n_scenes	int	No	Number of scenes (1-20), only used in generate mode
title	string	No	Video title (auto-generated if not provided)
frame_template	string	No	Template path, e.g., 1080x1920/image_default.html
template_params	object	No	Custom template parameters (colors, backgrounds, etc.)
media_workflow	string	No	Media workflow (image or video generation)
tts_workflow	string	No	TTS workflow
ref_audio	string	No	Reference audio path for voice cloning
prompt_prefix	string	No	Image style prefix
bgm_path	string	No	BGM file path
bgm_volume	float	No	BGM volume (0.0-1.0, default 0.3)

---

More Information

API documentation is also available via Swagger UI: http://localhost:8000/docs