Skip to main content

​
Backend API

This page is a practical route reference, not a formal OpenAPI spec. All routes are prefixed with /api.

​
Health and status

​
GET /api/health

Returns server liveness status.

​
GET /api/me

Returns the currently authenticated user profile.

​
GET /api/ai/health

Returns AI provider reachability and configuration status.

​
GET /api/ai/timeline

Returns a timeline of recent AI operations.

​
Projects and media

​
GET /api/project

Returns a list of all projects for the current user.

​
POST /api/project

Creates a new project. Request Body: 
{
  "name": "string",
  "description": "string",
  "video_url": "string"
}

​
GET /api/project/{project_id}

Returns details for a specific project.

​
DELETE /api/project/{project_id}

Deletes a project.

​
POST /api/project/{project_id}/upload

Uploads a new video asset to the project. Request Body: 
{
  "file_name": "string",
  "content_type": "string"
}
Response: 
{
  "upload_url": "string",
  "asset_id": "string"
}

​
POST /api/project/{project_id}/preview/frame

Extracts and publishes a single preview frame from the project timeline at a specific timestamp. Request Body: 
{
  "ts": 0.0
}
Response: 
{
  "frame_url": "string",
  "timestamp": 0.0
}

​
POST /api/project/{project_id}/preview/strip

Extracts a strip of preview frames across a specified range from the project timeline. Request Body: 
{
  "start": 0.0,
  "end": 0.0,
  "fps": 1.0
}
Response: 
{
  "frames": [
    {
      "frame_url": "string",
      "timestamp": 0.0
    }
  ]
}

​
Editing operations

​
POST /api/segment/{segment_id}/split

Splits an existing segment into two new segments at a specified timestamp. The original segment is deactivated. Request Body: 
{
  "split_ts": 0.0
}
Response: 
{
  "left": {
    "id": "string",
    "project_id": "string",
    "start_ts": 0.0,
    "end_ts": 0.0,
    "source": "string",
    "url": "string",
    "variant_id": "string",
    "order_index": 0,
    "active": true
  },
  "right": {
    "id": "string",
    "project_id": "string",
    "start_ts": 0.0,
    "end_ts": 0.0,
    "source": "string",
    "url": "string",
    "variant_id": "string",
    "order_index": 0,
    "active": true
  }
}

​
POST /api/segment/{segment_id}/trim

Trims an existing segment to new start and end timestamps within its original bounds. Request Body: 
{
  "new_start_ts": 0.0,
  "new_end_ts": 0.0
}
Response: 
{
  "id": "string",
  "project_id": "string",
  "start_ts": 0.0,
  "end_ts": 0.0,
  "source": "string",
  "url": "string",
  "variant_id": "string",
  "order_index": 0,
  "active": true
}

​
DELETE /api/segment/{segment_id}

Soft-deletes a segment by setting its active status to false. Response: 
{
  "deleted": true
}

​
POST /api/segment/{segment_id}/color-grade

Applies color grade adjustments to a segment and creates a new generated replacement segment. Request Body: 
{
  "brightness": 0.0,
  "contrast": 0.0,
  "saturation": 0.0,
  "temperature": 0.0,
  "gamma": 0.0,
  "hue_shift": 0.0
}
Response: 
{
  "segment_id": "string",
  "graded_url": "string"
}

​
POST /api/segment/{segment_id}/grade-preview

Renders a graded preview frame for a segment with specified color adjustments. Request Body: 
{
  "brightness": 0.0,
  "contrast": 0.0,
  "saturation": 0.0,
  "temperature": 0.0,
  "gamma": 0.0,
  "hue_shift": 0.0
}
Response: 
{
  "preview_frame_url": "string"
}

​
AI and generation

​
POST /api/ai/generate

Initiates an AI-powered video generation job. Request Body: 
{
  "project_id": "string",
  "prompt": "string",
  "start_ts": 0.0,
  "end_ts": 0.0,
  "bounding_box": {
    "x": 0.0,
    "y": 0.0,
    "width": 0.0,
    "height": 0.0
  }
}

​
GET /api/job/{job_id}

Check the status of a generation, entity, or other non-export job and get any variant results. Response: 
{
  "id": "string",
  "project_id": "string",
  "status": "pending" | "running" | "completed" | "failed",
  "error": "string",
  "variants": [
    {
      "id": "string",
      "url": "string",
      "preview_url": "string"
    }
  ]
}

​
POST /api/variant/{variant_id}/accept

Accepts a generated variant, applying it to the project timeline.

​
GET /api/variant/{variant_id}/score

Retrieves detailed Gemini-based scoring for a variant, comparing it to the original prompt or the original video segment. Query Parameters:
  • compare_to: prompt (default) or original. Specifies what the variant should be compared against for scoring.
Response: 
{
  "variant_id": "string",
  "score": {
    "overall_rating": "string",
    "details": "string",
    "fidelity_to_prompt": "string",
    "visual_quality": "string"
  }
}

​
Exports

​
POST /api/export

Initiates a video export job for a project. Request Body: 
{
  "project_id": "string",
  "format": "mp4"
}
Response: 
{
  "export_job_id": "string",
  "status": "pending",
  "message": "Export job created — check status with get_export_status"
}

​
GET /api/export/{export_job_id}

Check the status of an export job and retrieve the output URLs when it is done. Response: 
{
  "export_job_id": "string",
  "status": "pending" | "running" | "completed" | "failed",
  "export_url": "string",
  "download_url": "string",
  "error": "string"
}