Generation API: Shot Streams and Timeline Rendering

Authorization: Bearer <supabase-access-token>

POST /functions/v1/gen-shots
Authorization: Bearer <supabase-jwt>
Content-Type: application/json
Accept: text/event-stream

{
  "projectId": "a1b2c3d4-...",
  "sceneId": "scene-uuid",
  "existingShots": [
    { "id": "shot-uuid-1", "shot_number": 1 },
    { "id": "shot-uuid-2", "shot_number": 2 }
  ],
  "shotCount": 3
}

event: meta
data: {"requestId":"...","projectId":"...","sceneId":"...","latency":0}

event: shot
data: {"id":"shot-uuid","project_id":"...","scene_id":"...","shot_number":3,"status":"enriching","title":"Golden Hour Chase","description":"A motorcycle speeds through narrow alleyways as the sun dips below the horizon.","visual_prompt":"A motorcycle speeds through narrow alleyways...Cinematic lighting, professional framing, filmic detail.","thumbnail":null}

event: done
data: {"completed":true,"total":3,"requestId":"..."}

event: error
data: {"error":"Streaming failed","requestId":"..."}

POST /functions/v1/project-auto-generate
Authorization: Bearer <supabase-jwt>
Content-Type: application/json

{
  "project_id": "a1b2c3d4-...",
  "phase": "images"
}

POST /functions/v1/compute-execute
Authorization: Bearer <supabase-jwt>
Content-Type: application/json
Accept: text/event-stream

POST /functions/v1/director-cut
Authorization: Bearer <supabase-jwt>
Content-Type: application/json

GET /functions/v1/model-catalog
Authorization: Bearer <supabase-jwt>

[
  {
    "id": "fal-ai/flux/schnell",
    "name": "FLUX Schnell",
    "provider": "fal-ai",
    "credits": 3,
    "mediaType": "image",
    "workflowType": "text-to-image"
  },
  {
    "id": "fal-ai/kling-video/o3/standard/text-to-video",
    "name": "Kling O3 Standard T2V",
    "provider": "fal-ai",
    "credits": 20,
    "mediaType": "video",
    "workflowType": "text-to-video"
  }
]

interface GenerationInput {
  /** Model ID from the catalog or a provider-specific ID */
  model: string;
  /** Primary prompt / instruction text */
  prompt: string;
  /** Additional model-specific parameters */
  parameters?: Record<string, unknown>;
  /** Reference assets (input images, videos, audio for conditioning) */
  referenceAssets?: ReferenceAsset[];
  /** Output configuration */
  outputConfig?: OutputConfig;
  /** Metadata for tracking / context */
  metadata?: GenerationMetadata;
}

interface ReferenceAsset {
  url: string;
  type: 'image' | 'video' | 'audio' | 'text' | 'model';
  role?: string;  // e.g. 'input_image', 'style_reference'
}

interface OutputConfig {
  format?: string;            // 'png', 'mp4', 'mp3', etc.
  count?: number;             // Number of outputs
  storageBucket?: string;     // Supabase Storage bucket
  storagePathPrefix?: string;
  autoStore?: boolean;        // Auto-upload to Supabase Storage (default: true)
}

interface GenerationMetadata {
  source?: 'project-setup' | 'studio' | 'editor' | 'storyboard' | 'timeline';
  projectId?: string;
  entityId?: string;   // Node / shot / clip ID
  custom?: Record<string, unknown>;
}

interface GenerationResult {
  url: string;
  metadata: GenerationResultMetadata;
  status: 'pending' | 'running' | 'completed' | 'failed';
}

interface GenerationResultMetadata {
  generationId: string;
  resolvedModel: string;    // Actual model used (may differ due to fallback)
  requestedModel: string;   // Originally requested model
  fallbackUsed: boolean;
  fallbackReason?: string;
  mediaType: 'image' | 'video' | 'audio' | 'text' | 'unknown';
  credits?: number;
  durationSeconds?: number;
  raw?: unknown;            // Raw provider response
  storageUrl?: string;      // Supabase Storage URL if auto-stored
  width?: number;
  height?: number;
}

import { unifiedGenerationService } from '@/services/unifiedGenerationService';

// Generate an image
const image = await unifiedGenerationService.generateImage(
  'A cinematic wide shot of a futuristic city at sunset',
  {
    model: 'fal-ai/flux/schnell',
    parameters: { image_size: 'landscape_16_9' },
    projectId: 'my-project-id',
    autoStore: true,
  }
);
console.log(image.url); // Supabase Storage URL

// Generate a video with progress tracking
const video = await unifiedGenerationService.generateVideo(
  'A drone flyover of a tropical island, golden hour',
  {
    model: 'fal-ai/kling-video/o3/standard/text-to-video',
    parameters: { duration: '5', aspect_ratio: '16:9', generate_audio: true },
    projectId: 'my-project-id',
  },
  (progress) => console.log(`${progress.percent}% — ${progress.message}`)
);

// Generate text
const result = await unifiedGenerationService.generateText(
  'Write a 3-sentence storyline for a sci-fi short film.',
  { model: 'google/gemini-2.5-flash' }
);
const text = (result.metadata.raw as { text: string }).text;

import { GenerationError, InsufficientCreditsError } from '@/services/unifiedGenerationService';

try {
  const result = await unifiedGenerationService.generate(input);
} catch (error) {
  if (error instanceof InsufficientCreditsError) {
    console.log(`Need ${error.required} credits, have ${error.available}`);
    // Service automatically routes to the billing top-up page
  } else if (error instanceof GenerationError) {
    console.error(`[${error.code}] ${error.message}`);
  }
}