egaki 0.5.0 → 0.6.0

package/src/model-catalog.ts

@@ -1,12 +1,28 @@
-// Single source of truth for all image generation models.
+// Single source of truth for all image and video generation models.
 // Every model's provider, pricing, features, and generation strategy lives here.
 // Other modules derive their data from this catalog — no separate registries.
 //
 // To add a model: add an entry to CATALOG with the right shared fragment spread.
 // To update pricing: change the cost field on the model entry.
 // To add a provider: create a new shared fragment and add models using it.
+//
+// Provider option schemas are sourced from the @ai-sdk/* packages and upstream API docs.
+// Each shared fragment has a URL comment pointing to the source of truth so options
+// are easy to verify and update when providers change their APIs.
+//
+// Sources:
+//   xAI image:  node_modules/@ai-sdk/xai/dist/index.d.ts → xaiImageModelOptions
+//               https://docs.x.ai/docs/api-reference#create-image
+//   xAI video:  node_modules/@ai-sdk/xai/dist/index.d.ts → XaiVideoModelOptions
+//               https://docs.x.ai/docs/api-reference#create-video
+//   OpenAI:     node_modules/@ai-sdk/openai/dist/index.d.ts → imageGeneration args
+//               https://platform.openai.com/docs/api-reference/images
+//   Fal image:  https://ai-sdk.dev/providers/ai-sdk-providers/fal
+//               node_modules/@ai-sdk/fal/dist/index.d.ts → FalImageModelOptions
+//   Fal video:  node_modules/@ai-sdk/fal/dist/index.d.ts → FalVideoModelOptions
+//               https://ai-sdk.dev/providers/ai-sdk-providers/fal
 
-// ─── types ───────────────────────────────────────────────────────────────────
+// ─── cost types ──────────────────────────────────────────────────────────────
 
 export type PerImageCost = {
   type: 'per-image'
@@ -22,7 +38,55 @@ export type PerTokenCost = {
   outputPerM: number
 }
 
+export type VideoDurationPricingTier = {
+  /** USD per second for this variant */
+  costPerSecond: number
+  /** Optional resolution discriminator (e.g. 720p, 1080p, 4k) */
+  resolution?: string
+  /** Optional mode discriminator (e.g. std, pro) */
+  mode?: string
+  /** Optional audio discriminator */
+  audio?: boolean
+}
+
+export type PerVideoSecondCost = {
+  type: 'per-video-second'
+  /** Fallback duration when request does not specify one (seconds) */
+  defaultDurationSec: number
+  tiers: VideoDurationPricingTier[]
+}
+
+export type UnknownCost = {
+  type: 'unknown'
+}
+
 export type ModelCost = PerImageCost | PerTokenCost
+export type VideoModelCost = PerVideoSecondCost | UnknownCost
+export type AnyCost = ModelCost | VideoModelCost
+
+// ─── provider option types ───────────────────────────────────────────────────
+// Declares provider-specific options that can be passed via providerOptions.
+// Lives in the catalog so CLI flag descriptions and validation are derived
+// from a single source of truth.
+
+export type ProviderOption = {
+  /** CLI flag name, e.g. 'quality', 'output-format' */
+  flag: string
+  /** The key sent to providerOptions.{provider}.{key} */
+  providerKey: string
+  /** Human description for --help */
+  description: string
+  /** Enum values if constrained, shown in flag description */
+  values?: string[]
+  /** Server-side default when not specified */
+  defaultValue?: string
+  /** Value type */
+  type: 'string' | 'number' | 'boolean'
+  /** Whether this flag accepts multiple values (array) */
+  array?: boolean
+}
+
+// ─── feature types ───────────────────────────────────────────────────────────
 
 export type ModelFeatures = {
   /** supports input images for editing */
@@ -39,10 +103,28 @@ export type ModelFeatures = {
   multipleImages: boolean
 }
 
-export type ModelEntry = {
+export type VideoModelFeatures = {
+  /** Supports text prompt to video generation */
+  textToVideo: boolean
+  /** Supports image-to-video prompt object ({ image, text }) */
+  imageToVideo: boolean
+  /** Optional capabilities exposed by provider */
+  capabilities: Array<'t2v' | 'i2v' | 'r2v' | 'motion-control' | 'editing' | 'extension'>
+  /** Optional supported aspect ratios */
+  aspectRatios?: string[]
+  /** Optional supported resolutions */
+  resolutions?: string[]
+  /** Optional duration range in seconds */
+  durationRangeSec?: { min: number; max: number }
+  seed: boolean
+  multipleVideos: boolean
+}
+
+// ─── entry types (discriminated union by strategy) ───────────────────────────
+
+export type ImageModelEntry = {
   id: string
   name: string
-  /** Optional longer description shown in `egaki models` output */
   description?: string
   provider: string
   strategy: 'image' | 'text'
@@ -50,8 +132,28 @@ export type ModelEntry = {
   released: string
   cost: ModelCost
   features: ModelFeatures
+  /** Provider-specific options passable via providerOptions.{provider} */
+  providerOptions?: ProviderOption[]
 }
 
+export type VideoModelEntry = {
+  id: string
+  name: string
+  description?: string
+  provider: string
+  strategy: 'video'
+  released: string
+  cost: VideoModelCost
+  features: VideoModelFeatures
+  /** Provider-specific options passable via providerOptions.{provider} */
+  providerOptions?: ProviderOption[]
+}
+
+/** @deprecated Use ImageModelEntry instead */
+export type ModelEntry = ImageModelEntry
+
+export type AnyModelEntry = ImageModelEntry | VideoModelEntry
+
 // ─── shared fragments ────────────────────────────────────────────────────────
 // Spread these into model entries to avoid repeating common fields.
 
@@ -79,9 +181,17 @@ const googleText = {
   },
 }
 
+// Source: node_modules/@ai-sdk/openai/dist/index.d.ts → imageGeneration args
+// Docs:   https://platform.openai.com/docs/api-reference/images/create
+const openaiImageProviderOptions: ProviderOption[] = [
+  { flag: 'quality', providerKey: 'quality', description: 'Image quality', values: ['auto', 'low', 'medium', 'high'], defaultValue: 'auto', type: 'string' },
+  { flag: 'output-format', providerKey: 'outputFormat', description: 'Output format', values: ['png', 'jpeg', 'webp'], defaultValue: 'png', type: 'string' },
+]
+
 const openaiImage = {
   provider: 'openai',
   strategy: 'image' as const,
+  providerOptions: openaiImageProviderOptions,
 }
 
 const replicateImage = {
@@ -89,9 +199,17 @@ const replicateImage = {
   strategy: 'image' as const,
 }
 
+// Source: node_modules/@ai-sdk/fal/dist/index.d.ts → FalImageModelOptions (lazy passthrough)
+// Docs:   https://ai-sdk.dev/providers/ai-sdk-providers/fal#provider-options
+const falImageProviderOptions: ProviderOption[] = [
+  { flag: 'output-format', providerKey: 'outputFormat', description: 'Output format', values: ['png', 'jpeg'], type: 'string' },
+  { flag: 'negative-prompt', providerKey: 'negativePrompt', description: 'What to avoid in the image', type: 'string' },
+]
+
 const falImage = {
   provider: 'fal',
   strategy: 'image' as const,
+  providerOptions: falImageProviderOptions,
 }
 
 const bflImage = {
@@ -104,11 +222,37 @@ const recraftImage = {
   strategy: 'image' as const,
 }
 
+// Source: node_modules/@ai-sdk/xai/dist/index.d.ts → xaiImageModelOptions
+// Docs:   https://docs.x.ai/docs/api-reference#create-image
+const xaiImageProviderOptions: ProviderOption[] = [
+  { flag: 'quality', providerKey: 'quality', description: 'Image quality', values: ['low', 'medium', 'high'], defaultValue: 'medium', type: 'string' },
+  { flag: 'resolution', providerKey: 'resolution', description: 'Output resolution', values: ['1k', '2k'], defaultValue: '1k', type: 'string' },
+  { flag: 'output-format', providerKey: 'output_format', description: 'Output format', values: ['png', 'jpeg'], defaultValue: 'png', type: 'string' },
+]
+
 const xaiImage = {
   provider: 'xai',
   strategy: 'image' as const,
+  providerOptions: xaiImageProviderOptions,
 }
 
+// Source: node_modules/@ai-sdk/xai/dist/index.d.ts → XaiVideoModelOptions
+// Docs:   https://docs.x.ai/docs/api-reference#create-video
+const xaiVideoProviderOptions: ProviderOption[] = [
+  { flag: 'resolution', providerKey: 'resolution', description: 'Output resolution', values: ['480p', '720p'], defaultValue: '720p', type: 'string' },
+  { flag: 'mode', providerKey: 'mode', description: 'Video operation mode', values: ['edit-video', 'extend-video', 'reference-to-video'], type: 'string' },
+  // video-url is not a CLI flag; it's set internally from --input in edit/extend modes.
+  // Kept here so findProviderOption() can verify the model supports it and resolve the correct providerKey.
+  { flag: 'video-url', providerKey: 'videoUrl', description: 'Source video URL for editing or extension (internal)', type: 'string' },
+  { flag: 'reference-images', providerKey: 'referenceImageUrls', description: 'Reference images for R2V (1-7 files or URLs)', type: 'string', array: true },
+]
+
+// Source: node_modules/@ai-sdk/fal/dist/index.d.ts → FalVideoModelOptions
+// Docs:   https://ai-sdk.dev/providers/ai-sdk-providers/fal
+const falVideoProviderOptions: ProviderOption[] = [
+  { flag: 'negative-prompt', providerKey: 'negativePrompt', description: 'What to avoid in the video', type: 'string' },
+]
+
 const vertexImagen = {
   provider: 'vertex',
   strategy: 'image' as const,
@@ -1068,10 +1212,396 @@ export const CATALOG: ModelEntry[] = [
   },
 ]
 
+// ─── video catalog ───────────────────────────────────────────────────────────
+
+const commonVideoRatios = ['16:9', '9:16', '1:1', '4:3', '3:4']
+
+export const VIDEO_CATALOG: VideoModelEntry[] = [
+  {
+    id: 'veo-3.1-generate-001',
+    name: 'Veo 3.1',
+    provider: 'google',
+    strategy: 'video',
+    released: '2026-01',
+    cost: {
+      type: 'per-video-second',
+      defaultDurationSec: 8,
+      tiers: [
+        { resolution: '720p', audio: false, costPerSecond: 0.2 },
+        { resolution: '720p', audio: true, costPerSecond: 0.4 },
+        { resolution: '1080p', audio: false, costPerSecond: 0.2 },
+        { resolution: '1080p', audio: true, costPerSecond: 0.4 },
+        { resolution: '4k', audio: false, costPerSecond: 0.4 },
+        { resolution: '4k', audio: true, costPerSecond: 0.6 },
+      ],
+    },
+    features: {
+      textToVideo: true,
+      imageToVideo: false,
+      capabilities: ['t2v'],
+      aspectRatios: ['16:9', '9:16'],
+      resolutions: ['720p', '1080p', '4k'],
+      durationRangeSec: { min: 4, max: 8 },
+      seed: true,
+      multipleVideos: true,
+    },
+  },
+  {
+    id: 'veo-3.1-fast-generate-001',
+    name: 'Veo 3.1 Fast',
+    provider: 'google',
+    strategy: 'video',
+    released: '2026-01',
+    cost: {
+      type: 'per-video-second',
+      defaultDurationSec: 8,
+      tiers: [
+        { resolution: '720p', audio: false, costPerSecond: 0.1 },
+        { resolution: '720p', audio: true, costPerSecond: 0.15 },
+        { resolution: '1080p', audio: false, costPerSecond: 0.1 },
+        { resolution: '1080p', audio: true, costPerSecond: 0.15 },
+        { resolution: '4k', audio: false, costPerSecond: 0.3 },
+        { resolution: '4k', audio: true, costPerSecond: 0.35 },
+      ],
+    },
+    features: {
+      textToVideo: true,
+      imageToVideo: false,
+      capabilities: ['t2v'],
+      aspectRatios: ['16:9', '9:16'],
+      resolutions: ['720p', '1080p', '4k'],
+      durationRangeSec: { min: 4, max: 8 },
+      seed: true,
+      multipleVideos: true,
+    },
+  },
+  {
+    id: 'veo-3.0-generate-001',
+    name: 'Veo 3.0',
+    provider: 'google',
+    strategy: 'video',
+    released: '2025-12',
+    cost: {
+      type: 'per-video-second',
+      defaultDurationSec: 8,
+      tiers: [
+        { resolution: '720p', audio: false, costPerSecond: 0.2 },
+        { resolution: '720p', audio: true, costPerSecond: 0.4 },
+        { resolution: '1080p', audio: false, costPerSecond: 0.2 },
+        { resolution: '1080p', audio: true, costPerSecond: 0.4 },
+      ],
+    },
+    features: {
+      textToVideo: true,
+      imageToVideo: false,
+      capabilities: ['t2v'],
+      aspectRatios: ['16:9', '9:16'],
+      resolutions: ['720p', '1080p'],
+      durationRangeSec: { min: 4, max: 8 },
+      seed: true,
+      multipleVideos: true,
+    },
+  },
+  {
+    id: 'veo-3.0-fast-generate-001',
+    name: 'Veo 3.0 Fast',
+    provider: 'google',
+    strategy: 'video',
+    released: '2025-12',
+    cost: {
+      type: 'per-video-second',
+      defaultDurationSec: 8,
+      tiers: [
+        { resolution: '720p', audio: false, costPerSecond: 0.1 },
+        { resolution: '720p', audio: true, costPerSecond: 0.15 },
+        { resolution: '1080p', audio: false, costPerSecond: 0.1 },
+        { resolution: '1080p', audio: true, costPerSecond: 0.15 },
+      ],
+    },
+    features: {
+      textToVideo: true,
+      imageToVideo: false,
+      capabilities: ['t2v'],
+      aspectRatios: ['16:9', '9:16'],
+      resolutions: ['720p', '1080p'],
+      durationRangeSec: { min: 4, max: 8 },
+      seed: true,
+      multipleVideos: true,
+    },
+  },
+  // ── Vertex: Veo ──────────────────────────────────────────────────────
+  {
+    id: 'vertex/veo-3.1-generate-001',
+    name: 'Veo 3.1 (Vertex)',
+    provider: 'vertex',
+    strategy: 'video',
+    released: '2026-01',
+    cost: {
+      type: 'per-video-second',
+      defaultDurationSec: 8,
+      tiers: [
+        { resolution: '720p', audio: false, costPerSecond: 0.2 },
+        { resolution: '720p', audio: true, costPerSecond: 0.4 },
+        { resolution: '1080p', audio: false, costPerSecond: 0.2 },
+        { resolution: '1080p', audio: true, costPerSecond: 0.4 },
+        { resolution: '4k', audio: false, costPerSecond: 0.4 },
+        { resolution: '4k', audio: true, costPerSecond: 0.6 },
+      ],
+    },
+    features: {
+      textToVideo: true,
+      imageToVideo: false,
+      capabilities: ['t2v'],
+      aspectRatios: ['16:9', '9:16'],
+      resolutions: ['720p', '1080p', '4k'],
+      durationRangeSec: { min: 4, max: 8 },
+      seed: true,
+      multipleVideos: true,
+    },
+  },
+  {
+    id: 'vertex/veo-3.1-fast-generate-001',
+    name: 'Veo 3.1 Fast (Vertex)',
+    provider: 'vertex',
+    strategy: 'video',
+    released: '2026-01',
+    cost: {
+      type: 'per-video-second',
+      defaultDurationSec: 8,
+      tiers: [
+        { resolution: '720p', audio: false, costPerSecond: 0.1 },
+        { resolution: '720p', audio: true, costPerSecond: 0.15 },
+        { resolution: '1080p', audio: false, costPerSecond: 0.1 },
+        { resolution: '1080p', audio: true, costPerSecond: 0.15 },
+        { resolution: '4k', audio: false, costPerSecond: 0.3 },
+        { resolution: '4k', audio: true, costPerSecond: 0.35 },
+      ],
+    },
+    features: {
+      textToVideo: true,
+      imageToVideo: false,
+      capabilities: ['t2v'],
+      aspectRatios: ['16:9', '9:16'],
+      resolutions: ['720p', '1080p', '4k'],
+      durationRangeSec: { min: 4, max: 8 },
+      seed: true,
+      multipleVideos: true,
+    },
+  },
+  {
+    id: 'grok-imagine-video',
+    name: 'Grok Imagine Video',
+    provider: 'xai',
+    strategy: 'video',
+    released: '2026-03',
+    cost: {
+      type: 'per-video-second',
+      defaultDurationSec: 5,
+      tiers: [
+        { resolution: '480p', costPerSecond: 0.05 },
+        { resolution: '720p', costPerSecond: 0.07 },
+      ],
+    },
+    features: {
+      textToVideo: true,
+      imageToVideo: true,
+      capabilities: ['t2v', 'i2v', 'editing', 'extension', 'r2v'],
+      aspectRatios: ['1:1', '16:9', '9:16', '4:3', '3:4', '3:2', '2:3'],
+      resolutions: ['480p', '720p'],
+      durationRangeSec: { min: 1, max: 15 },
+      seed: false,
+      multipleVideos: false,
+    },
+    providerOptions: xaiVideoProviderOptions,
+  },
+  {
+    id: 'kling-v2.6-t2v',
+    name: 'Kling v2.6 T2V',
+    provider: 'klingai',
+    strategy: 'video',
+    released: '2025-12',
+    cost: {
+      type: 'per-video-second',
+      defaultDurationSec: 5,
+      tiers: [
+        { mode: 'std', costPerSecond: 0.042 },
+        { mode: 'pro', audio: false, costPerSecond: 0.07 },
+        { mode: 'pro', audio: true, costPerSecond: 0.14 },
+      ],
+    },
+    features: {
+      textToVideo: true,
+      imageToVideo: false,
+      capabilities: ['t2v'],
+      aspectRatios: commonVideoRatios,
+      durationRangeSec: { min: 5, max: 10 },
+      seed: false,
+      multipleVideos: false,
+    },
+  },
+  {
+    id: 'wan-v2.6-t2v',
+    name: 'Wan v2.6 T2V',
+    provider: 'alibaba',
+    strategy: 'video',
+    released: '2026-01',
+    cost: {
+      type: 'per-video-second',
+      defaultDurationSec: 5,
+      tiers: [
+        { resolution: '720p', costPerSecond: 0.1 },
+        { resolution: '1080p', costPerSecond: 0.15 },
+      ],
+    },
+    features: {
+      textToVideo: true,
+      imageToVideo: false,
+      capabilities: ['t2v'],
+      resolutions: ['720p', '1080p'],
+      durationRangeSec: { min: 2, max: 15 },
+      seed: false,
+      multipleVideos: false,
+    },
+  },
+  // ── Fal video models ─────────────────────────────────────────────────
+  {
+    id: 'luma-ray-2',
+    name: 'Luma Ray 2 (Fal)',
+    provider: 'fal',
+    strategy: 'video',
+    released: '2025-11',
+    cost: { type: 'unknown' },
+    features: {
+      textToVideo: true,
+      imageToVideo: true,
+      capabilities: ['t2v', 'i2v'],
+      aspectRatios: commonVideoRatios,
+      seed: true,
+      multipleVideos: false,
+    },
+    providerOptions: falVideoProviderOptions,
+  },
+  {
+    id: 'minimax-video',
+    name: 'MiniMax Video (Fal)',
+    provider: 'fal',
+    strategy: 'video',
+    released: '2025-10',
+    cost: { type: 'unknown' },
+    features: {
+      textToVideo: true,
+      imageToVideo: false,
+      capabilities: ['t2v'],
+      aspectRatios: commonVideoRatios,
+      seed: false,
+      multipleVideos: false,
+    },
+    providerOptions: falVideoProviderOptions,
+  },
+  {
+    id: 'hunyuan-video',
+    name: 'Hunyuan Video (Fal)',
+    provider: 'fal',
+    strategy: 'video',
+    released: '2025-09',
+    cost: { type: 'unknown' },
+    features: {
+      textToVideo: true,
+      imageToVideo: true,
+      capabilities: ['t2v', 'i2v'],
+      aspectRatios: commonVideoRatios,
+      seed: true,
+      multipleVideos: false,
+    },
+    providerOptions: falVideoProviderOptions,
+  },
+]
+
+// ─── provider option helpers ─────────────────────────────────────────────────
+
+/**
+ * Collect the valid values for a CLI flag across all providers in the catalog.
+ * Returns a map of provider name → enum values array. Only includes providers
+ * that declare values for the given flag. Used by cli.ts to auto-generate
+ * flag descriptions like "xAI: low, medium, high. OpenAI: auto, low, medium, high".
+ */
+export function getProviderValuesForFlag(
+  flag: string,
+  catalogs: AnyModelEntry[][] = [CATALOG, VIDEO_CATALOG],
+): Map<string, string[]> {
+  const result = new Map<string, string[]>()
+  for (const catalog of catalogs) {
+    for (const entry of catalog) {
+      if (!entry.providerOptions) continue
+      for (const opt of entry.providerOptions) {
+        if (opt.flag === flag && opt.values?.length && !result.has(entry.provider)) {
+          result.set(entry.provider, opt.values)
+        }
+      }
+    }
+  }
+  return result
+}
+
+/**
+ * Build a human-readable description suffix listing provider-specific values
+ * for a flag. Includes default values when available.
+ * Example: "xai: low, medium, high (default: medium). openai: auto, low, medium, high (default: auto)"
+ */
+export function describeProviderValues(
+  flag: string,
+  catalogs?: AnyModelEntry[][],
+): string {
+  const allCatalogs = catalogs ?? [CATALOG, VIDEO_CATALOG]
+  // collect {provider → {values, defaultValue}} for this flag
+  const providerInfo = new Map<string, { values: string[]; defaultValue?: string }>()
+  for (const catalog of allCatalogs) {
+    for (const entry of catalog) {
+      if (!entry.providerOptions) continue
+      for (const opt of entry.providerOptions) {
+        if (opt.flag === flag && opt.values?.length && !providerInfo.has(entry.provider)) {
+          providerInfo.set(entry.provider, {
+            values: opt.values,
+            defaultValue: opt.defaultValue,
+          })
+        }
+      }
+    }
+  }
+  if (providerInfo.size === 0) return ''
+  return [...providerInfo.entries()]
+    .map(([provider, info]) => {
+      const vals = info.values.join(', ')
+      const def = info.defaultValue ? ` (default: ${info.defaultValue})` : ''
+      return `${provider}: ${vals}${def}`
+    })
+    .join('. ')
+}
+
+/**
+ * Find the ProviderOption definition for a given flag and provider from a model entry.
+ * Returns undefined if the model doesn't support this flag.
+ */
+export function findProviderOption(
+  entry: AnyModelEntry,
+  flag: string,
+): ProviderOption | undefined {
+  return entry.providerOptions?.find((opt) => opt.flag === flag)
+}
+
 // ─── lookup helpers ──────────────────────────────────────────────────────────
 
-const catalogIndex = new Map(CATALOG.map((m) => [m.id, m]))
+const imageCatalogIndex = new Map(CATALOG.map((m) => [m.id, m]))
+const videoCatalogIndex = new Map(VIDEO_CATALOG.map((m) => [m.id, m]))
+
+export function findModel(id: string): ImageModelEntry | undefined {
+  return imageCatalogIndex.get(id)
+}
+
+export function findVideoModel(id: string): VideoModelEntry | undefined {
+  return videoCatalogIndex.get(id)
+}
 
-export function findModel(id: string): ModelEntry | undefined {
-  return catalogIndex.get(id)
+export function findAnyModel(id: string): AnyModelEntry | undefined {
+  return imageCatalogIndex.get(id) ?? videoCatalogIndex.get(id)
 }