---
title: "Upload Video"
method: POST
path: "/api/v1/upload"
---

# Upload Video

`POST /api/v1/upload`

## Request

- Base URL: `https://api.clipmaster.app` (the document declares no server; this is the origin it was published from)
- URL: `https://api.clipmaster.app/api/v1/upload`
- Auth: HTTP bearer

Upload video and start processing pipeline.
Now uses SQLite for storage and Celery for background processing.

New parameters:
- tags: Comma-separated tags for video context (e.g., "product demo,tutorial")
- query: Natural language query for scene matching (e.g., "customer explains features")
- min_duration: Minimum scene duration in seconds (default: 5.0)
- include_captions: Enable captions on exported clips (default: False)
- karaoke_captions: Enable word-by-word karaoke effect (default: False)
- karaoke_color: Hex color for karaoke highlight (e.g., "#cf2a8b", default: brand green "#9DC34F")
- orientation: Target clip aspect ratio for caption positioning: "vertical" (9:16), "horizontal" (16:9), "square" (1:1), or "original" (preserve source orientation)
- processing_mode: Processing mode: "automatic" (detect all scenes), "semantic" (query-based), or "full_video" (no clipping)
- smart_crop_enabled: Enable AI-powered smart crop with subject tracking for intelligent framing (default: False)
- gemini_analysis: Enable Gemini visual scene analysis; when False the pipeline runs Whisper-only and transcript scenes drive clip generation (default: True, still gated by plan entitlement)

## Response `200`

Successful Response

- VideoUploadResponse
  - `project_id` integer, required
  - `task_id` string, nullable
  - `message` string, required
  - `metadata` object, required
  - `progress_url` string, nullable
  - `video_url` string, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/clipmaster/apis/semantic-video-clip-ai-agent.md) · [All operations](https://skmtc.dev/clipmaster/apis/semantic-video-clip-ai-agent/llms.txt) · [OpenAPI document](https://skmtc.dev/clipmaster/apis/semantic-video-clip-ai-agent/revisions/c9b8333cd22b?raw)