Self-Hosted API Specification

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx

{
  "jobType": "video-generation",        // required, 1-100 chars
  "userId": "user_123",                 // required, 1-255 chars
  "title": "Creating your video...",    // required, 1-200 chars
  "metadata": { "prompt": "..." },      // optional, max 10KB
  "queue": {                            // optional
    "position": 5,
    "total": 20,
    "queueName": "priority"
  },
  "stage": {                            // optional
    "name": "initializing",
    "current": 1,
    "total": 3,
    "description": "Setting up..."
  },
  "estimatedCompletionAt": "2026-01-22T15:00:00Z",  // optional, ISO 8601
  "ttlSeconds": 2592000,                // optional, 60-2592000 (30 days)

  // Parent-child fields (optional)
  "totalChildren": 5,                   // for parent jobs, 1-1000
  "childProgressMode": "average",       // 'average' | 'sequential' | 'weighted'
  "parentJobId": "01HXYZ...",           // for child jobs
  "childIndex": 0                       // for child jobs, 0-9999
}

{
  "id": "01HXYZ123456789ABCDEFGHIJ",
  "appId": "app_xxx",
  "userId": "user_123",
  "jobType": "video-generation",
  "title": "Creating your video...",
  "status": "pending",
  "progress": 0,
  "metadata": { "prompt": "..." },
  "createdAt": "2026-01-22T14:30:00Z",
  "updatedAt": "2026-01-22T14:30:00Z",

  // For parent jobs
  "children": {
    "total": 5,
    "completed": 0,
    "failed": 0,
    "running": 0,
    "pending": 5
  },
  "childProgressMode": "average",

  // For child jobs
  "parent": {
    "parentJobId": "01HXYZ...",
    "childIndex": 0
  }
}

{
  "jobs": [
    {
      "id": "01HXYZ...",
      "userId": "user_123",
      "jobType": "video-generation",
      "title": "My Video",
      "status": "completed",
      "progress": 100,
      "createdAt": "2026-01-22T14:30:00Z",
      "updatedAt": "2026-01-22T14:35:00Z"
    }
  ],
  "nextCursor": "eyJsYXN0S2V5Ijo..."
}

{
  "parent": {
    "id": "01HXYZ...",
    "title": "Christmas Pack",
    "status": "running",
    "progress": 60,
    "children": {
      "total": 5,
      "completed": 3,
      "failed": 0,
      "running": 1,
      "pending": 1
    },
    "childProgressMode": "average"
  },
  "children": [
    {
      "id": "01HABC...",
      "childIndex": 0,
      "title": "Snowflake",
      "status": "completed",
      "progress": 100,
      "createdAt": "2026-01-22T14:30:00Z",
      "updatedAt": "2026-01-22T14:32:00Z",
      "completedAt": "2026-01-22T14:32:00Z"
    },
    {
      "id": "01HDEF...",
      "childIndex": 1,
      "title": "Christmas Tree",
      "status": "running",
      "progress": 50,
      "createdAt": "2026-01-22T14:30:00Z",
      "updatedAt": "2026-01-22T14:33:00Z"
    }
  ]
}

{
  "progress": 50,                       // required, 0-100
  "message": "Processing frames...",    // optional
  "queue": { ... },                     // optional
  "stage": { ... },                     // optional
  "estimatedCompletionAt": "...",       // optional
  "metadata": { ... }                   // optional, merged with existing
}

{
  "result": {                           // optional
    "type": "video",
    "url": "https://cdn.example.com/output.mp4",
    "data": { ... }
  },
  "message": "Video ready!"             // optional
}

{
  "error": {                            // required
    "code": "PROCESSING_ERROR",
    "message": "Failed to generate video",
    "details": { "reason": "..." }
  },
  "retryable": true                     // optional
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Job job_123 not found"
  }
}

GET /v1/sse?userId=user_123
Authorization: Bearer pk_live_xxx

Accept: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

event: job.progress
id: 1705932600000
data: {"id":"01HXYZ...","status":"running","progress":50,...}

event: job.completed
id: 1705932660000
data: {"id":"01HXYZ...","status":"completed","progress":100,...}

event: heartbeat
id: 1705932615000
data: {}

CREATE TABLE jobs (
  id VARCHAR(26) PRIMARY KEY,           -- ULID
  app_id VARCHAR(100) NOT NULL,
  user_id VARCHAR(255) NOT NULL,
  job_type VARCHAR(100) NOT NULL,
  title VARCHAR(200) NOT NULL,
  status ENUM('pending','running','completed','failed'),
  progress INT DEFAULT 0,
  message TEXT,
  metadata JSON,
  queue JSON,
  stage JSON,
  result JSON,
  error JSON,
  estimated_completion_at TIMESTAMP,

  -- Parent-child
  parent_job_id VARCHAR(26),
  child_index INT,
  total_children INT,
  completed_children INT DEFAULT 0,
  failed_children INT DEFAULT 0,
  running_children INT DEFAULT 0,
  pending_children INT DEFAULT 0,
  child_progress_mode VARCHAR(20),

  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW(),
  completed_at TIMESTAMP,
  ttl TIMESTAMP,

  INDEX idx_user (app_id, user_id),
  INDEX idx_parent (parent_job_id)
);

// When a child job updates, recalculate parent
function updateParentStats(parentId) {
  const children = getChildrenByParentId(parentId);
  const parent = getJob(parentId);

  let completed = 0, failed = 0, running = 0, pending = 0;
  let totalProgress = 0;

  for (const child of children) {
    switch (child.status) {
      case 'completed': completed++; totalProgress += 100; break;
      case 'failed': failed++; totalProgress += child.progress; break;
      case 'running': running++; totalProgress += child.progress; break;
      case 'pending': pending++; break;
    }
  }

  // Calculate progress based on mode
  let parentProgress;
  switch (parent.childProgressMode) {
    case 'average':
      parentProgress = Math.round(totalProgress / parent.totalChildren);
      break;
    case 'sequential':
      parentProgress = Math.round((completed / parent.totalChildren) * 100);
      break;
  }

  // Determine parent status
  let parentStatus = parent.status;
  if (running > 0 || (completed > 0 && completed < parent.totalChildren)) {
    parentStatus = 'running';
  } else if (completed === parent.totalChildren) {
    parentStatus = 'completed';
  } else if (failed > 0 && (completed + failed) === parent.totalChildren && completed === 0) {
    parentStatus = 'failed';
  }

  updateJob(parentId, {
    completedChildren: completed,
    failedChildren: failed,
    runningChildren: running,
    pendingChildren: pending,
    progress: parentProgress,
    status: parentStatus
  });
}