Video API 🟡 BETA

API for video project management, editing, scene composition, AI-powered enhancement, and export.

Base URL

/api/video

Authentication

All endpoints require a valid session token via Authorization: Bearer <token> header.

Endpoints

List Projects

GET /api/video/projects

Returns a list of all video projects.

Response:

{
  "projects": [
    {
      "id": "uuid-string",
      "name": "Product Demo v2",
      "duration_seconds": 120,
      "resolution": "1920x1080",
      "clip_count": 8,
      "status": "draft",
      "created_at": "2026-01-15T10:30:00Z",
      "updated_at": "2026-01-20T14:45:00Z",
      "thumbnail_url": "/api/video/projects/uuid/thumbnail"
    }
  ],
  "total": 12
}

Create Project

POST /api/video/projects

Creates a new video project.

Request Body:

{
  "name": "Product Demo v2",
  "resolution": "1920x1080",
  "fps": 30
}

Response:

{
  "id": "uuid-string",
  "name": "Product Demo v2",
  "resolution": "1920x1080",
  "fps": 30,
  "created_at": "2026-01-20T15:00:00Z"
}

Update Clip

PUT /api/video/clips/:id

Updates a clip’s properties within a project.

Request Body:

{
  "start_time": 10.5,
  "end_time": 25.0,
  "volume": 0.8,
  "opacity": 1.0
}

Response:

{
  "id": "clip-uuid",
  "updated": true,
  "duration_seconds": 14.5
}

Delete Clip

DELETE /api/video/clips/:id

Removes a clip from the project.

Response:

{
  "deleted": true,
  "id": "clip-uuid"
}

Split Clip

POST /api/video/clips/:id/split

Splits a clip at a specified timestamp into two separate clips.

Request Body:

{
  "at_time": 15.3
}

Response:

{
  "original_clip_id": "clip-uuid-1",
  "new_clip_id": "clip-uuid-2",
  "split_at": 15.3,
  "first_duration": 15.3,
  "second_duration": 9.7
}

Delete Audio Track

DELETE /api/video/audio/:id

Removes an audio track from a project.

Response:

{
  "deleted": true,
  "id": "audio-track-uuid"
}

Upload to Project

POST /api/video/projects/:id/upload

Uploads a video file to an existing project.

Response:

{
  "clip_id": "clip-uuid",
  "filename": "intro-sequence.mp4",
  "duration_seconds": 30.5,
  "resolution": "1920x1080",
  "format": "mp4",
  "size_bytes": 15728640,
  "processing": true
}

Generate Preview

GET /api/video/projects/:id/preview

Generates or retrieves a preview of the project timeline.

Response:

{
  "preview_url": "/api/video/preview/uuid-string.mp4",
  "duration_seconds": 120,
  "quality": "medium",
  "generated_at": "2026-01-20T15:10:00Z",
  "size_bytes": 5242880
}

Text-to-Speech

POST /api/video/projects/:id/tts

Generates a voiceover using text-to-speech for the project.

Request Body:

{
  "text": "Bem-vindos ao nosso produto. Vamos mostrar os principais recursos.",
  "voice": "pt-br-female-1",
  "speed": 1.0,
  "language": "pt-BR"
}

Response:

{
  "audio_id": "tts-uuid",
  "duration_seconds": 8.5,
  "audio_url": "/api/video/audio/tts-uuid",
  "processing": true
}

Generate Scenes

POST /api/video/projects/:id/scenes

Uses AI to generate scene compositions from a script or description.

Request Body:

{
  "script": "Opening with product close-up, transition to team working, end with logo reveal",
  "scene_count": 3,
  "style": "cinematic"
}

Response:

{
  "scenes": [
    {
      "id": "scene-uuid-1",
      "name": "Product Close-up",
      "duration_seconds": 10,
      "clips": ["clip-uuid-1"],
      "transitions": ["fade-in"]
    },
    {
      "id": "scene-uuid-2",
      "name": "Team Working",
      "duration_seconds": 15,
      "clips": ["clip-uuid-2", "clip-uuid-3"],
      "transitions": ["crossfade"]
    }
  ],
  "total_duration": 35
}

Reframe Video

POST /api/video/projects/:id/reframe

AI-powered reframing to adapt video for different aspect ratios (e.g., 16:9 to 9:16 for mobile).

Request Body:

{
  "target_ratio": "9:16",
  "focus_mode": "smart"
}

Response:

{
  "reframed_project_id": "new-project-uuid",
  "target_ratio": "9:16",
  "clips_reframed": 8,
  "processing": true
}

Enhance Video

POST /api/video/projects/:id/enhance

Applies AI-powered video enhancement (color correction, stabilization, noise reduction).

Enhancement types: color_correction, stabilization, noise_reduction, sharpness, brightness, contrast

Request Body:

{
  "enhancements": ["color_correction", "stabilization", "noise_reduction"],
  "intensity": 0.7
}

Response:

{
  "enhanced_project_id": "new-project-uuid",
  "enhancements_applied": ["color_correction", "stabilization", "noise_reduction"],
  "processing": true,
  "estimated_time_seconds": 45
}

Delete Keyframe

DELETE /api/video/keyframes/:id

Removes a keyframe animation from a clip.

Response:

{
  "deleted": true,
  "id": "keyframe-uuid"
}

Get Templates

GET /api/video/templates

Returns available video project templates.

Response:

{
  "templates": [
    {
      "id": "template-uuid",
      "name": "Product Demo",
      "description": "Template for product demonstration videos",
      "duration_seconds": 60,
      "resolution": "1920x1080",
      "category": "marketing",
      "thumbnail_url": "/api/video/templates/template-uuid/thumbnail"
    },
    {
      "id": "template-uuid-2",
      "name": "Social Media Story",
      "description": "Vertical format for Instagram/TikTok stories",
      "duration_seconds": 15,
      "resolution": "1080x1920",
      "category": "social",
      "thumbnail_url": "/api/video/templates/template-uuid-2/thumbnail"
    }
  ]
}

Chat with Project

POST /api/video/projects/:id/chat

AI assistant for project — ask questions about the video, get suggestions, or request edits via natural language.

Request Body:

{
  "message": "Can you make the intro shorter and add a fade transition between scene 2 and 3?"
}

Response:

{
  "response": "I've shortened the intro from 10s to 5s and added a crossfade transition between scenes 2 and 3. The total project duration is now 115 seconds.",
  "actions_taken": [
    {"type": "trim", "clip_id": "clip-uuid-1", "new_duration": 5},
    {"type": "add_transition", "between": ["scene-2", "scene-3"], "transition": "crossfade"}
  ],
  "suggestions": [
    "Add background music to match the new pacing",
    "Consider adding text overlays for key points"
  ]
}

Export Project

POST /api/video/projects/:id/export

Initiates video export/rendering.

Request Body:

{
  "format": "mp4",
  "quality": "high",
  "codec": "h264"
}

Response:

{
  "export_id": "export-uuid",
  "status": "queued",
  "estimated_time_seconds": 120,
  "websocket_url": "ws://localhost:8080/api/video/ws/export/export-uuid"
}

Get Export Status

GET /api/video/exports/:id/status

Checks the status of a video export job.

Response:

{
  "export_id": "export-uuid",
  "status": "processing",
  "progress_percent": 65,
  "current_frame": 1950,
  "total_frames": 3000,
  "eta_seconds": 42,
  "output_url": null
}

Status values: queued, processing, completed, failed

Track Analytics View

POST /api/video/analytics/view

Records an analytics event when a video is viewed.

Request Body:

{
  "project_id": "uuid-string",
  "duration_watched": 45.2,
  "source": "web"
}

Response:

{
  "recorded": true,
  "total_views": 142,
  "avg_watch_percent": 78.5
}

Export WebSocket Stream

GET /api/video/ws/export/:id (WebSocket)

Real-time export progress stream via WebSocket.

Connection:

ws://localhost:8080/api/video/ws/export/{export_id}

Messages received:

{
  "type": "progress",
  "export_id": "export-uuid",
  "progress_percent": 65,
  "current_frame": 1950,
  "total_frames": 3000,
  "eta_seconds": 42
}

{
  "type": "completed",
  "export_id": "export-uuid",
  "output_url": "/api/video/exports/export-uuid/download",
  "format": "mp4",
  "size_bytes": 52428800,
  "duration_seconds": 120
}

{
  "type": "error",
  "export_id": "export-uuid",
  "error": "Encoding failed at frame 2100",
  "code": "ENCODING_ERROR"
}

Video Formats

See Also

• Slides API - Presentation creation
• Docs API - Word processor documents
• Research API - Research collections