egaki 0.4.1 → 0.6.0

package/src/cli.ts

@@ -11,10 +11,19 @@ import { goke } from 'goke'
 import { z } from 'zod'
 import dedent from 'string-dedent'
 import {
+  APICallError,
   generateImage as aiGenerateImage,
   generateText,
   experimental_generateVideo as aiGenerateVideo,
+  NoImageGeneratedError,
+  NoVideoGeneratedError,
+  RetryError,
 } from 'ai'
+import type { XaiImageModelOptions, XaiVideoModelOptions } from '@ai-sdk/xai'
+import type { GoogleImageModelOptions, GoogleLanguageModelOptions, GoogleVideoModelOptions } from '@ai-sdk/google'
+import type { GoogleVertexImageModelOptions, GoogleVertexVideoModelOptions } from '@ai-sdk/google-vertex'
+import type { FalImageModelOptions, FalVideoModelOptions } from '@ai-sdk/fal'
+import { select, isCancel, cancel } from '@clack/prompts'
 import fs from 'node:fs'
 import path from 'node:path'
 import pc from 'picocolors'
@@ -38,7 +47,11 @@ import {
   createVideoModel,
   shouldUseResponsesApi,
 } from './models.js'
-import { VIDEO_CATALOG } from './video-model-catalog.js'
+import {
+  CATALOG,
+  VIDEO_CATALOG,
+  describeProviderValues,
+} from './model-catalog.js'
 import {
   loginInteractive,
   loginNonInteractive,
@@ -54,23 +67,31 @@ import {
 } from './subscription.js'
 import { getValidChatGptAuth } from './chatgpt-auth.js'
 
+// OpenAI doesn't export a providerOptions type for image models yet (vercel/ai#12437).
+// These fields are what providerOptions.openai accepts, derived from
+// node_modules/@ai-sdk/openai/src/image/openai-image-model-options.ts.
+// NOTE: The SDK uses camelCase keys in providerOptions, then internally maps to
+// snake_case for the OpenAI API. Always use camelCase here.
+type OpenAIImageProviderOptions = {
+  quality?: 'standard' | 'low' | 'medium' | 'high' | 'auto'
+  outputFormat?: 'png' | 'jpeg' | 'webp'
+  outputCompression?: number
+  size?: `${number}x${number}`
+  partialImages?: number | null
+  background?: 'auto' | 'opaque' | 'transparent'
+}
+
 const cli = goke('egaki')
 
 process.title = 'egaki'
 
-// Print clean error output for unhandled rejections (e.g. AI SDK APICallError).
-// The AI SDK errors include request bodies, response headers, and other noisy
-// properties that get dumped by Node's default handler. We strip those and just
-// print the message + stack trace.
 process.on('uncaughtException', (err) => {
-  console.error(pc.red(err.message))
-  if (err.stack) {
-    const lines = err.stack.split('\n')
-    const stackOnly = lines.filter((l) => l.trimStart().startsWith('at '))
-    if (stackOnly.length > 0) {
-      console.error(pc.dim(stackOnly.join('\n')))
-    }
-  }
+  printErrorDetails(err)
+  process.exit(1)
+})
+
+process.on('unhandledRejection', (reason) => {
+  printErrorDetails(reason)
   process.exit(1)
 })
 
@@ -127,8 +148,8 @@ cli
 
     // Non-interactive: --provider + --key or stdin
     if (options.provider) {
-      // ChatGPT uses browser OAuth — skip key reading
-      if (options.provider === 'chatgpt') {
+      // OAuth providers use browser flow — skip key reading
+      if (options.provider === 'chatgpt' || options.provider === 'xai-oauth') {
         await loginNonInteractive({ provider: options.provider, key: '' })
         return
       }
@@ -225,7 +246,7 @@ cli
   )
   .option(
     '-m, --model [model]',
-    z.enum(IMAGE_MODELS).default(DEFAULT_MODEL).describe('Model ID for generation'),
+    z.string().describe('Model ID for generation. If omitted, shows an interactive picker (or uses default in non-TTY mode)'),
   )
   .option(
     '-o, --output [path]',
@@ -274,6 +295,38 @@ cli
         'Mask image for inpainting. Accepts a local file path or URL (http/https). White areas in the mask are replaced with generated content. Used together with --input',
       ),
   )
+  .option(
+    '--quality [level]',
+    z
+      .string()
+      .describe(
+        `Image quality level. ${describeProviderValues('quality', [CATALOG])}`,
+      ),
+  )
+  .option(
+    '--resolution [res]',
+    z
+      .string()
+      .describe(
+        `Output resolution. ${describeProviderValues('resolution', [CATALOG])}`,
+      ),
+  )
+  .option(
+    '--output-format [format]',
+    z
+      .string()
+      .describe(
+        `Output image format. ${describeProviderValues('output-format', [CATALOG])}`,
+      ),
+  )
+  .option(
+    '--negative-prompt [text]',
+    z
+      .string()
+      .describe(
+        'Describe what to avoid in the generated image (Fal models)',
+      ),
+  )
   .option(
     '--allow-people',
     'Allow generating images of people (Imagen blocks people by default)',
@@ -308,10 +361,7 @@ cli
     // Inject stored API keys as env vars before calling the AI SDK.
     injectCredentialsToEnv()
 
-    // goke infers schema .default() values via Zod's input type, which leaves
-    // options.model / options.output / options.count as `T | undefined` even
-    // though the runtime always resolves them. Apply the same defaults here.
-    const model = options.model ?? DEFAULT_MODEL
+    const model = options.model ?? await resolveImageModel()
     const outputPath = options.output ?? 'egaki-output.png'
     const count = options.count ?? 1
     const config = getModelConfig(model)
@@ -359,6 +409,10 @@ cli
         inputImages,
         maskImage,
         allowPeople: options.allowPeople || false,
+        quality: options.quality,
+        resolution: options.resolution,
+        outputFormat: options.outputFormat,
+        negativePrompt: options.negativePrompt,
         json: options.json || false,
         stdout: options.stdout || false,
       })
@@ -391,7 +445,7 @@ cli
   )
   .option(
     '-m, --model [model]',
-    z.enum(VIDEO_MODELS).default(DEFAULT_VIDEO_MODEL).describe('Video model ID for generation'),
+    z.string().describe('Video model ID for generation. If omitted, shows an interactive picker (or uses default in non-TTY mode)'),
   )
   .option(
     '-o, --output [path]',
@@ -412,11 +466,11 @@ cli
     '--resolution [resolution]',
     z
       .string()
-      .describe('Video resolution in WIDTHxHEIGHT or provider format (e.g. 1280x720, 720p)'),
+      .describe(`Video resolution. ${describeProviderValues('resolution', [VIDEO_CATALOG])}. Google: 720p, 1080p, 4k`),
   )
   .option(
     '--duration [seconds]',
-    z.number().describe('Video duration in seconds (provider/model-specific limits apply)'),
+    z.number().describe('Video duration in seconds. Veo: 4-8s. xAI Grok: 1-15s. Kling: 5-10s. Wan: 2-15s'),
   )
   .option(
     '--fps [fps]',
@@ -431,7 +485,31 @@ cli
     z
       .string()
       .describe(
-        'Optional reference image for image-to-video. Accepts local file path or URL (http/https)',
+        'Input file for video generation. For i2v: a reference image. For edit-video/extend-video: a source video. Accepts local file paths or URLs',
+      ),
+  )
+  .option(
+    '--mode [mode]',
+    z
+      .enum(['edit-video', 'extend-video', 'reference-to-video'])
+      .describe(
+        `Video operation mode. ${describeProviderValues('mode', [VIDEO_CATALOG])}`,
+      ),
+  )
+  .option(
+    '--reference-images [path]',
+    z
+      .array(z.string())
+      .describe(
+        'Reference images for R2V generation, repeatable, 1-7 files or URLs (xAI)',
+      ),
+  )
+  .option(
+    '--negative-prompt [text]',
+    z
+      .string()
+      .describe(
+        'Describe what to avoid in the generated video (Fal models)',
       ),
   )
   .option(
@@ -455,8 +533,7 @@ cli
   .action(async (prompt, options) => {
     injectCredentialsToEnv()
 
-    // Apply the same .default(...) values goke's input-type inference drops.
-    const model = options.model ?? DEFAULT_VIDEO_MODEL
+    const model = options.model ?? await resolveVideoModel()
     const outputPath = options.output ?? 'egaki-output.mp4'
     const count = options.count ?? 1
     const config = getModelConfig(model)
@@ -472,9 +549,39 @@ cli
       console.error(pc.dim('Mode: Video API (experimental_generateVideo)'))
     }
 
-    const inputImage = options.input
-      ? await readInputSource(options.input)
-      : undefined
+    // Determine how --input is used based on --mode:
+    // - edit-video / extend-video: input is a source video, passed as videoUrl (needs URL)
+    // - everything else (i2v, t2v): input is a reference image, passed as bytes
+    const isVideoInputMode = options.mode === 'edit-video' || options.mode === 'extend-video'
+
+    // Validate mode-specific required inputs
+    if (isVideoInputMode && !options.input) {
+      console.error(pc.red(`--input is required with --mode ${options.mode}. Pass a local video file or URL.`))
+      process.exit(1)
+    }
+    if (options.mode === 'reference-to-video' && (!options.referenceImages || options.referenceImages.length === 0)) {
+      console.error(pc.red('--reference-images is required with --mode reference-to-video. Pass 1-7 image files or URLs.'))
+      process.exit(1)
+    }
+
+    let inputImage: Uint8Array | undefined
+    let videoUrl: string | undefined
+
+    if (options.input && isVideoInputMode) {
+      // Upload local file or use URL directly for video editing/extension
+      videoUrl = await resolveToUrl(options.input)
+    } else if (options.input) {
+      // Read as bytes for image-to-video
+      inputImage = await readInputSource(options.input)
+    }
+
+    // Resolve --reference-images: upload local files to get URLs
+    let resolvedReferenceImages = options.referenceImages
+    if (resolvedReferenceImages) {
+      resolvedReferenceImages = await Promise.all(
+        resolvedReferenceImages.map((ref: string) => resolveToUrl(ref)),
+      )
+    }
 
     await generateWithVideoModel({
       prompt,
@@ -487,6 +594,10 @@ cli
       fps: options.fps,
       seed: options.seed,
       inputImage,
+      mode: options.mode,
+      videoUrl,
+      referenceImages: resolvedReferenceImages,
+      negativePrompt: options.negativePrompt,
       json: options.json || false,
       stdout: options.stdout || false,
     })
@@ -515,17 +626,17 @@ cli
   )
   .option('--json', 'Output as JSON instead of YAML')
   .action(async (options) => {
-    const { CATALOG } = await import('./model-catalog.js')
     const yaml = await import('js-yaml')
     const providerStatuses = Object.fromEntries(
       Object.keys(PROVIDERS).map((provider) => [provider, getKeyStatus(provider)]),
     )
 
-    let models = options.type === 'video'
-      ? VIDEO_CATALOG
-      : options.type === 'image'
-        ? CATALOG
-        : [...CATALOG, ...VIDEO_CATALOG]
+    let models: Array<typeof CATALOG[number] | typeof VIDEO_CATALOG[number]> =
+      options.type === 'video'
+        ? [...VIDEO_CATALOG]
+        : options.type === 'image'
+          ? [...CATALOG]
+          : [...CATALOG, ...VIDEO_CATALOG]
 
     if (options.provider) {
       models = models.filter((m) => m.provider === options.provider)
@@ -575,14 +686,300 @@ cli
     }
   })
 
+/** Upload gateway base URL for temporary file uploads. */
+const UPLOAD_GATEWAY_BASE = 'https://egaki.org'
+/** Max upload size in bytes (must match gateway limit). */
+const MAX_UPLOAD_SIZE = 100 * 1024 * 1024
+
 cli.help()
 cli.version(pkg.version)
-cli.parse()
+await cli.parse()
+
+// ─── error output helpers ────────────────────────────────────────────────────
+
+type PrintableValue = unknown
+type ErrorDetailsInput = Parameters<typeof APICallError.isInstance>[0]
+
+async function runProviderCall<T>(operation: string, call: () => Promise<T>): Promise<T> {
+  const result = await call().catch((error) => {
+    printErrorDetails(error, operation)
+    process.exit(1)
+  })
+  return result
+}
+
+function printErrorDetails(error: ErrorDetailsInput, operation?: string): void {
+  const prefix = operation ? `${operation} failed` : 'Command failed'
+  console.error(pc.red(pc.bold(prefix)))
+
+  if (APICallError.isInstance(error)) {
+    printKeyValue('name', error.name)
+    printKeyValue('message', error.message)
+    printKeyValue('statusCode', error.statusCode)
+    printKeyValue('url', error.url)
+    printKeyValue('isRetryable', error.isRetryable)
+    printJsonBlock('responseBody', parseJsonLike(error.responseBody))
+    printJsonBlock('responseHeaders', error.responseHeaders)
+    printJsonBlock('requestBodyValues', error.requestBodyValues)
+    printJsonBlock('data', error.data)
+    printCause(error.cause)
+    printStack(error)
+    return
+  }
+
+  if (NoImageGeneratedError.isInstance(error) || NoVideoGeneratedError.isInstance(error)) {
+    printKeyValue('name', error.name)
+    printKeyValue('message', error.message)
+    printJsonBlock('responses', error.responses)
+    printCause(error.cause)
+    printStack(error)
+    return
+  }
+
+  if (RetryError.isInstance(error)) {
+    printKeyValue('name', error.name)
+    printKeyValue('message', error.message)
+    printKeyValue('reason', error.reason)
+    printJsonBlock('errors', error.errors.map((e) => serializeUnknown(e)))
+    printCause(error.cause)
+    printStack(error)
+    return
+  }
+
+  if (error instanceof Error) {
+    printKeyValue('name', error.name)
+    printKeyValue('message', error.message)
+    printJsonBlock('details', serializeOwnProperties(error))
+    printCause(error.cause)
+    printStack(error)
+    return
+  }
+
+  printJsonBlock('error', serializeUnknown(error))
+}
+
+function printKeyValue(key: string, value: PrintableValue): void {
+  if (value === undefined) return
+  console.error(`${pc.dim(`${key}:`)} ${String(value)}`)
+}
+
+function printJsonBlock(label: string, value: PrintableValue): void {
+  if (value === undefined) return
+  const serialized = stableStringify(value)
+  if (!serialized || serialized === '{}') return
+  console.error(pc.dim(`${label}:`))
+  console.error(serialized)
+}
+
+function printCause(cause: Error['cause']): void {
+  if (cause === undefined) return
+  console.error(pc.dim('cause:'))
+  console.error(stableStringify(serializeUnknown(cause)))
+}
+
+function printStack(error: Error): void {
+  if (!error.stack) return
+  console.error(pc.dim('stack:'))
+  console.error(pc.dim(error.stack))
+}
+
+function parseJsonLike(value?: string): PrintableValue {
+  if (typeof value !== 'string') return value
+  try {
+    return JSON.parse(value)
+  } catch {
+    return value
+  }
+}
+
+function serializeUnknown(value: ErrorDetailsInput): PrintableValue {
+  if (value instanceof Error) {
+    return {
+      name: value.name,
+      message: value.message,
+      ...serializeOwnProperties(value),
+      ...(value.cause === undefined ? {} : { cause: serializeUnknown(value.cause) }),
+      ...(value.stack ? { stack: value.stack } : {}),
+    }
+  }
+  return value
+}
+
+function serializeOwnProperties(error: Error): Record<string, PrintableValue> {
+  return Object.fromEntries(
+    Object.entries(error).map(([key, value]) => [key, serializeUnknown(value)]),
+  )
+}
+
+function stableStringify(value: PrintableValue): string | undefined {
+  const seen = new WeakSet<object>()
+  return JSON.stringify(value, (_key, item) => {
+    if (typeof item === 'bigint') return item.toString()
+    if (item instanceof Date) return item.toISOString()
+    if (typeof item !== 'object' || item === null) return item
+    if (seen.has(item)) return '[Circular]'
+    seen.add(item)
+    return item
+  }, 2)
+}
+
+// ─── interactive model pickers ──────────────────────────────────────────────
+
+/** Curated image models shown in the interactive picker, ordered by recommendation. */
+const FEATURED_IMAGE_MODELS = [
+  'imagen-4.0-generate-001',
+  'imagen-4.0-ultra-generate-001',
+  'imagen-4.0-fast-generate-001',
+  'gemini-2.5-flash-image',
+  'gemini-3.1-flash-image-preview',
+  'nano-banana-pro-preview',
+  'gpt-image-2',
+  'gpt-image-1.5',
+  'chatgpt-image-latest',
+  'flux-kontext-pro',
+  'flux-kontext-max',
+  'flux-pro-1.1-ultra',
+  'recraft-v4',
+  'dall-e-3',
+  'grok-imagine-image-pro',
+]
+
+/**
+ * Resolve the image model: show interactive picker in TTY, use default otherwise.
+ */
+async function resolveImageModel(): Promise<string> {
+  const isTTY = process.stdin.isTTY && process.stderr.isTTY
+  if (!isTTY) return DEFAULT_MODEL
+
+  const options = FEATURED_IMAGE_MODELS
+    .map((id) => CATALOG.find((m) => m.id === id))
+    .filter(Boolean)
+    .map((m) => {
+      const cost = m!.cost.type === 'per-image'
+        ? pc.dim(`$${m!.cost.perImage}/img`)
+        : m!.cost.type === 'per-token'
+          ? pc.dim(`$${m!.cost.outputPerM}/M out`)
+          : ''
+      return {
+        value: m!.id,
+        label: `${m!.name} ${cost}`,
+        hint: m!.id,
+      }
+    })
+
+  const selected = await select({
+    message: 'Select an image model',
+    options,
+  })
+
+  if (isCancel(selected)) {
+    cancel('Cancelled.')
+    process.exit(0)
+  }
+
+  return selected
+}
+
+/**
+ * Resolve the video model: show interactive picker in TTY, use default otherwise.
+ */
+async function resolveVideoModel(): Promise<string> {
+  const isTTY = process.stdin.isTTY && process.stderr.isTTY
+  if (!isTTY) return DEFAULT_VIDEO_MODEL
+
+  const options = VIDEO_CATALOG.map((m) => {
+    const dur = m.features.durationRangeSec
+      ? pc.dim(`${m.features.durationRangeSec.min}-${m.features.durationRangeSec.max}s`)
+      : ''
+    return {
+      value: m.id,
+      label: `${m.name} ${dur}`,
+      hint: m.id,
+    }
+  })
+
+  const selected = await select({
+    message: 'Select a video model',
+    options,
+  })
+
+  if (isCancel(selected)) {
+    cancel('Cancelled.')
+    process.exit(0)
+  }
+
+  return selected
+}
 
 function isUrl(input: string): boolean {
   return /^https?:\/\//i.test(input)
 }
 
+function mimeTypeFromExtension(ext: string): string {
+  const map: Record<string, string> = {
+    '.mp4': 'video/mp4',
+    '.webm': 'video/webm',
+    '.mov': 'video/quicktime',
+    '.avi': 'video/x-msvideo',
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.webp': 'image/webp',
+    '.gif': 'image/gif',
+  }
+  return map[ext.toLowerCase()] || 'application/octet-stream'
+}
+
+/**
+ * Upload a local file to the egaki gateway and return the public URL.
+ * Used when a flag that expects a URL receives a local file path instead.
+ */
+async function uploadFileToGateway(filePath: string): Promise<string> {
+  const resolved = path.resolve(filePath)
+  if (!fs.existsSync(resolved)) {
+    console.error(pc.red(`File not found: ${resolved}`))
+    process.exit(1)
+  }
+
+  const stat = fs.statSync(resolved)
+  if (stat.size > MAX_UPLOAD_SIZE) {
+    console.error(pc.red(`File too large: ${resolved} (${Math.round(stat.size / 1024 / 1024)}MB). Maximum is ${MAX_UPLOAD_SIZE / 1024 / 1024}MB`))
+    process.exit(1)
+  }
+
+  const ext = path.extname(resolved)
+  const contentType = mimeTypeFromExtension(ext)
+  const fileBytes = fs.readFileSync(resolved)
+
+  console.error(pc.dim(`Uploading ${filePath}...`))
+
+  const response = await fetch(`${UPLOAD_GATEWAY_BASE}/upload`, {
+    method: 'POST',
+    headers: { 'Content-Type': contentType },
+    body: fileBytes,
+  })
+
+  if (!response.ok) {
+    const body = await response.text().catch(() => '')
+    console.error(pc.red(`Upload failed: ${response.status} ${response.statusText}`))
+    if (body) console.error(pc.dim(body))
+    process.exit(1)
+  }
+
+  const result = await response.json() as { url: string }
+  console.error(pc.dim(`Uploaded: ${result.url}`))
+  return result.url
+}
+
+/**
+ * Resolve a value that should be a URL: if it's already a URL, return as-is.
+ * If it's a local file path, upload it to the gateway and return the public URL.
+ */
+async function resolveToUrl(input: string): Promise<string> {
+  if (isUrl(input)) return input
+  return uploadFileToGateway(input)
+}
+
 async function readInputSource(input: string): Promise<Uint8Array> {
   if (isUrl(input)) {
     console.error(pc.dim(`Fetching ${input}...`))
@@ -610,6 +1007,137 @@ async function readInputImages(
   return Promise.all(inputs.map((f) => readInputSource(f)))
 }
 
+// ─── type-safe provider option builders ──────────────────────────────────────
+// Each builder switches on provider name and constructs a typed object using
+// `satisfies` with the SDK's exported type. This catches typos in keys and
+// invalid enum values at compile time instead of runtime.
+
+type ImageOptionInputs = {
+  aspectRatio?: `${number}:${number}`
+  allowPeople: boolean
+  quality?: string
+  resolution?: string
+  outputFormat?: string
+  negativePrompt?: string
+}
+
+// Return type uses a mapped type that preserves the typed structure while
+// remaining compatible with the AI SDK's ProviderOptions (Record<string, JSONObject>).
+// The satisfies checks catch key typos and invalid enum values at compile time,
+// then we widen to the SDK's expected shape at the boundary.
+type ProviderOptionsResult = Record<string, Record<string, string | number | boolean | string[] | null | undefined | Record<string, string | number | boolean | null | undefined>>>
+
+function buildImageProviderOptions(
+  provider: string,
+  opts: ImageOptionInputs,
+): ProviderOptionsResult {
+  switch (provider) {
+    case 'google': {
+      const googleOpts = {
+        ...(opts.allowPeople ? { personGeneration: 'allow_all' as const } : {}),
+        ...(opts.aspectRatio ? { aspectRatio: opts.aspectRatio as GoogleImageModelOptions['aspectRatio'] } : {}),
+      } satisfies GoogleImageModelOptions
+      return { google: googleOpts }
+    }
+    case 'vertex': {
+      const vertexOpts = {
+        ...(opts.allowPeople ? { personGeneration: 'allow_all' as const } : {}),
+        ...(opts.negativePrompt ? { negativePrompt: opts.negativePrompt } : {}),
+      } satisfies GoogleVertexImageModelOptions
+      return { vertex: vertexOpts }
+    }
+    case 'xai': {
+      const xaiOpts = {
+        ...(opts.quality ? { quality: opts.quality as XaiImageModelOptions['quality'] } : {}),
+        ...(opts.resolution ? { resolution: opts.resolution as XaiImageModelOptions['resolution'] } : {}),
+        ...(opts.outputFormat ? { output_format: opts.outputFormat } : {}),
+      } satisfies XaiImageModelOptions
+      return { xai: xaiOpts }
+    }
+    case 'openai': {
+      const openaiOpts = {
+        ...(opts.quality ? { quality: opts.quality as OpenAIImageProviderOptions['quality'] } : {}),
+        ...(opts.outputFormat ? { outputFormat: opts.outputFormat as OpenAIImageProviderOptions['outputFormat'] } : {}),
+      } satisfies OpenAIImageProviderOptions
+      return { openai: openaiOpts }
+    }
+    case 'fal': {
+      const falOpts = {
+        ...(opts.outputFormat ? { outputFormat: opts.outputFormat } : {}),
+        ...(opts.negativePrompt ? { negativePrompt: opts.negativePrompt } : {}),
+      } satisfies FalImageModelOptions
+      return { fal: falOpts }
+    }
+    default:
+      // Providers routed through the gateway (bfl, recraft, etc.) pass options
+      // as-is since they don't have local SDK types.
+      return {}
+  }
+}
+
+type VideoOptionInputs = {
+  resolution?: string
+  mode?: string
+  videoUrl?: string
+  referenceImages?: string[]
+  negativePrompt?: string
+  model: string
+}
+
+function buildVideoProviderOptions(
+  provider: string,
+  opts: VideoOptionInputs,
+): ProviderOptionsResult | undefined {
+  switch (provider) {
+    case 'xai': {
+      // xAI video modes are a discriminated union; build the correct variant.
+      const base = {
+        ...(opts.resolution ? { resolution: opts.resolution as '480p' | '720p' } : {}),
+      }
+      if (opts.mode === 'edit-video' && opts.videoUrl) {
+        const xaiOpts = { ...base, mode: 'edit-video' as const, videoUrl: opts.videoUrl } satisfies XaiVideoModelOptions
+        return { xai: xaiOpts }
+      }
+      if (opts.mode === 'extend-video' && opts.videoUrl) {
+        const xaiOpts = { ...base, mode: 'extend-video' as const, videoUrl: opts.videoUrl } satisfies XaiVideoModelOptions
+        return { xai: xaiOpts }
+      }
+      if (opts.mode === 'reference-to-video' && opts.referenceImages) {
+        const xaiOpts = { ...base, mode: 'reference-to-video' as const, referenceImageUrls: opts.referenceImages } satisfies XaiVideoModelOptions
+        return { xai: xaiOpts }
+      }
+      // Default: text-to-video or image-to-video (no mode)
+      if (Object.keys(base).length === 0) return undefined
+      const xaiOpts = { ...base } satisfies XaiVideoModelOptions
+      return { xai: xaiOpts }
+    }
+    case 'fal': {
+      const falOpts = {
+        ...(opts.resolution ? { resolution: opts.resolution } : {}),
+        ...(opts.negativePrompt ? { negativePrompt: opts.negativePrompt } : {}),
+      } satisfies FalVideoModelOptions
+      if (Object.keys(falOpts).length === 0) return undefined
+      return { fal: falOpts }
+    }
+    case 'google': {
+      const googleOpts = {
+        ...(opts.negativePrompt ? { negativePrompt: opts.negativePrompt } : {}),
+      } satisfies GoogleVideoModelOptions
+      if (Object.keys(googleOpts).length === 0) return undefined
+      return { google: googleOpts }
+    }
+    case 'vertex': {
+      const vertexOpts = {
+        ...(opts.negativePrompt ? { negativePrompt: opts.negativePrompt } : {}),
+      } satisfies GoogleVertexVideoModelOptions
+      if (Object.keys(vertexOpts).length === 0) return undefined
+      return { vertex: vertexOpts }
+    }
+    default:
+      return undefined
+  }
+}
+
 // Generate using the dedicated generateImage API (Imagen models)
 async function generateWithImageModel({
   prompt,
@@ -621,6 +1149,10 @@ async function generateWithImageModel({
   inputImages,
   maskImage,
   allowPeople,
+  quality,
+  resolution,
+  outputFormat,
+  negativePrompt,
   json,
   stdout,
 }: {
@@ -633,6 +1165,10 @@ async function generateWithImageModel({
   inputImages: Uint8Array[]
   maskImage?: Uint8Array
   allowPeople: boolean
+  quality?: string
+  resolution?: string
+  outputFormat?: string
+  negativePrompt?: string
   json: boolean
   stdout: boolean
 }) {
@@ -644,65 +1180,53 @@ async function generateWithImageModel({
   const config = getModelConfig(model)
   const imageModel = await createImageModel(model)
 
-  // Use the correct providerOptions key based on provider (google vs vertex)
-  const providerOptionsKey = config.provider === 'vertex' ? 'vertex' : 'google'
+  // Build type-safe provider options using the SDK types with `satisfies`.
+  // Each provider has its own shape; we switch on provider to get compile-time safety.
+  const providerOptions = buildImageProviderOptions(config.provider, {
+    aspectRatio,
+    allowPeople,
+    quality,
+    resolution,
+    outputFormat,
+    negativePrompt,
+  })
 
   if (!stdout) {
     console.error(pc.cyan('Generating...'))
   }
 
-  const result = await aiGenerateImage({
+  const result = await runProviderCall('Image generation', () => aiGenerateImage({
     model: imageModel,
     prompt: imagePrompt,
     n: count,
     ...(aspectRatio ? { aspectRatio } : {}),
     ...(seed !== undefined ? { seed } : {}),
-    providerOptions: {
-      [providerOptionsKey]: {
-        ...(allowPeople ? { personGeneration: 'allow_all' } : {}),
-        ...(aspectRatio ? { aspectRatio } : {}),
-      },
-    },
-  })
+    providerOptions,
+  }))
+
+  const files = result.images.map((img) => ({
+    uint8Array: img.uint8Array,
+    mediaType: img.mediaType,
+  }))
 
   if (stdout) {
-    // Write first image to stdout for piping
-    const image = result.images[0]
-    if (image) {
-      process.stdout.write(Buffer.from(image.uint8Array))
-    }
+    writeFirstToStdout(files)
     return
   }
 
-  const savedFiles: string[] = []
-  for (let i = 0; i < result.images.length; i++) {
-    const image = result.images[i]!
-    const ext = extensionFromMediaType(image.mediaType)
-    const filePath =
-      result.images.length === 1
-        ? ensureExtension(outputPath, ext)
-        : insertIndex(outputPath, i, ext)
-
-    fs.writeFileSync(filePath, image.uint8Array)
-    console.error(pc.green(`Saved: ${filePath}`))
-    savedFiles.push(filePath)
-  }
-
+  const savedFiles = saveGeneratedFiles(files, outputPath)
   const cost = calculateCost(config.cost, result.usage, result.images.length)
-  if (cost != null) {
-    console.error(pc.dim(`Cost: ${formatCost(cost)}`))
-  }
+  printCost(cost)
 
   if (json) {
-    const output = {
+    console.log(JSON.stringify({
       model,
       files: savedFiles,
       count: result.images.length,
       cost,
       usage: result.usage,
       warnings: result.warnings,
-    }
-    console.log(JSON.stringify(output, null, 2))
+    }, null, 2))
   }
 }
 
@@ -728,7 +1252,6 @@ async function generateWithTextModel({
 }) {
   const textModel = await createTextModel(model)
   const config = getModelConfig(model)
-  const providerOptionsKey = config.provider === 'vertex' ? 'vertex' : 'google'
 
   if (!stdout) {
     console.error(pc.cyan('Generating...'))
@@ -750,27 +1273,32 @@ async function generateWithTextModel({
       ]
     : undefined
 
-  const result = await generateText({
+  // Type-safe Google/Vertex language model options with image generation config.
+  // aspectRatio is cast to the Google SDK's enum type since CLI input is a free string.
+  type GoogleAspectRatio = NonNullable<NonNullable<GoogleLanguageModelOptions['imageConfig']>['aspectRatio']>
+  const googleOpts = {
+    responseModalities: ['TEXT', 'IMAGE'],
+    ...(imageSize || aspectRatio
+      ? {
+          imageConfig: {
+            ...(imageSize ? { imageSize } : {}),
+            ...(aspectRatio ? { aspectRatio: aspectRatio as GoogleAspectRatio } : {}),
+          },
+        }
+      : {}),
+  } satisfies GoogleLanguageModelOptions
+
+  const providerOptionsKey = config.provider === 'vertex' ? 'vertex' : 'google'
+
+  const result = await runProviderCall('Text/image generation', () => generateText({
     model: textModel,
     ...(messages ? { messages } : { prompt }),
     providerOptions: {
-      [providerOptionsKey]: {
-        responseModalities: ['TEXT', 'IMAGE'],
-        ...(imageSize || aspectRatio
-          ? {
-              imageConfig: {
-                ...(imageSize ? { imageSize } : {}),
-                ...(aspectRatio ? { aspectRatio } : {}),
-              },
-            }
-          : {}),
-      },
+      [providerOptionsKey]: googleOpts,
     },
-  })
+  }))
 
-  const imageFiles = result.files.filter((f) => {
-    return f.mediaType.startsWith('image/')
-  })
+  const imageFiles = result.files.filter((f) => f.mediaType.startsWith('image/'))
 
   if (imageFiles.length === 0) {
     console.error(pc.red('No images generated.'))
@@ -778,46 +1306,27 @@ async function generateWithTextModel({
   }
 
   if (stdout) {
-    const file = imageFiles[0]
-    if (file) {
-      process.stdout.write(Buffer.from(file.uint8Array))
-    }
+    writeFirstToStdout(imageFiles)
     return
   }
 
-  const savedFiles: string[] = []
-  for (let i = 0; i < imageFiles.length; i++) {
-    const file = imageFiles[i]!
-    const ext = extensionFromMediaType(file.mediaType)
-    const filePath =
-      imageFiles.length === 1
-        ? ensureExtension(outputPath, ext)
-        : insertIndex(outputPath, i, ext)
-
-    fs.writeFileSync(filePath, file.uint8Array)
-    console.error(pc.green(`Saved: ${filePath}`))
-    savedFiles.push(filePath)
-  }
-
+  const savedFiles = saveGeneratedFiles(imageFiles, outputPath)
   const cost = calculateCost(config.cost, result.usage, imageFiles.length)
-  if (cost != null) {
-    console.error(pc.dim(`Cost: ${formatCost(cost)}`))
-  }
+  printCost(cost)
 
   if (result.text && !json) {
     console.error(pc.dim(result.text))
   }
 
   if (json) {
-    const output = {
+    console.log(JSON.stringify({
       model,
       files: savedFiles,
       count: imageFiles.length,
       text: result.text || null,
       cost,
       usage: result.usage,
-    }
-    console.log(JSON.stringify(output, null, 2))
+    }, null, 2))
   }
 }
 
@@ -1026,6 +1535,10 @@ async function generateWithVideoModel({
   fps,
   seed,
   inputImage,
+  mode,
+  videoUrl,
+  referenceImages,
+  negativePrompt,
   json,
   stdout,
 }: {
@@ -1039,16 +1552,38 @@ async function generateWithVideoModel({
   fps?: number
   seed?: number
   inputImage?: Uint8Array
+  mode?: string
+  videoUrl?: string
+  referenceImages?: string[]
+  negativePrompt?: string
   json: boolean
   stdout: boolean
 }) {
   const videoModel = await createVideoModel(model)
+  const config = getModelConfig(model)
+
+  // Validate that the model supports video-url input before building options.
+  // Only models with a 'video-url' providerOption (currently xAI) accept edit/extend mode.
+  if (videoUrl && !config.providerOptions?.some((opt) => opt.flag === 'video-url')) {
+    console.error(pc.red(`Model ${model} does not support video URL input for editing/extension`))
+    process.exit(1)
+  }
+
+  // Build type-safe provider options for video generation.
+  const providerOptions = buildVideoProviderOptions(config.provider, {
+    resolution,
+    mode,
+    videoUrl,
+    referenceImages,
+    negativePrompt,
+    model,
+  })
 
   if (!stdout) {
     console.error(pc.cyan('Generating...'))
   }
 
-  const result = await aiGenerateVideo({
+  const result = await runProviderCall('Video generation', () => aiGenerateVideo({
     model: videoModel,
     prompt: inputImage
       ? { image: inputImage, text: prompt }
@@ -1059,50 +1594,88 @@ async function generateWithVideoModel({
     ...(duration != null ? { duration } : {}),
     ...(fps != null ? { fps } : {}),
     ...(seed != null ? { seed } : {}),
-  })
+    ...(providerOptions ? { providerOptions } : {}),
+  }))
+
+  const files = result.videos.map((v: { uint8Array: Uint8Array; mediaType: string }) => ({
+    uint8Array: v.uint8Array,
+    mediaType: v.mediaType,
+  }))
 
   if (stdout) {
-    const video = result.videos[0]
-    if (video) {
-      process.stdout.write(Buffer.from(video.uint8Array))
-    }
+    writeFirstToStdout(files)
     return
   }
 
-  const savedFiles: string[] = []
-  for (let i = 0; i < result.videos.length; i++) {
-    const video = result.videos[i]!
-    const ext = extensionFromMediaType(video.mediaType)
-    const filePath =
-      result.videos.length === 1
-        ? ensureExtension(outputPath, ext)
-        : insertIndex(outputPath, i, ext)
-
-    fs.writeFileSync(filePath, video.uint8Array)
-    console.error(pc.green(`Saved: ${filePath}`))
-    savedFiles.push(filePath)
-  }
-
-  const config = getModelConfig(model)
+  const savedFiles = saveGeneratedFiles(files, outputPath)
   const cost = calculateCost(config.cost, {
     videosGenerated: result.videos.length,
     durationSeconds: duration,
     resolution,
   }, result.videos.length)
-  if (cost != null) {
-    console.error(pc.dim(`Cost: ${formatCost(cost)}`))
-  }
+  printCost(cost)
 
   if (json) {
-    const output = {
+    console.log(JSON.stringify({
       model,
       files: savedFiles,
       count: result.videos.length,
       cost,
       warnings: result.warnings,
       responses: result.responses,
-    }
-    console.log(JSON.stringify(output, null, 2))
+    }, null, 2))
+  }
+}
+
+// ─── shared output helpers ───────────────────────────────────────────────────
+// Common logic for saving generated files, calculating cost, and printing JSON
+// metadata. Used by all generation paths to avoid repeating boilerplate.
+
+type GeneratedFile = {
+  uint8Array: Uint8Array
+  mediaType: string
+}
+
+/**
+ * Save generated files to disk. Returns the list of saved file paths.
+ * Handles single vs multi-file naming with index suffixes.
+ */
+function saveGeneratedFiles(
+  files: GeneratedFile[],
+  outputPath: string,
+): string[] {
+  const savedFiles: string[] = []
+  for (let i = 0; i < files.length; i++) {
+    const file = files[i]!
+    const ext = extensionFromMediaType(file.mediaType)
+    const filePath =
+      files.length === 1
+        ? ensureExtension(outputPath, ext)
+        : insertIndex(outputPath, i, ext)
+
+    fs.writeFileSync(filePath, file.uint8Array)
+    console.error(pc.green(`Saved: ${filePath}`))
+    savedFiles.push(filePath)
+  }
+  return savedFiles
+}
+
+/**
+ * Print estimated cost to stderr if calculable.
+ */
+function printCost(cost: number | null): void {
+  if (cost != null) {
+    console.error(pc.dim(`Cost: ${formatCost(cost)}`))
+  }
+}
+
+/**
+ * Write the first file's raw bytes to stdout (for piping to other tools).
+ */
+function writeFirstToStdout(files: GeneratedFile[]): void {
+  const file = files[0]
+  if (file) {
+    process.stdout.write(Buffer.from(file.uint8Array))
   }
 }