egaki 0.6.0 → 0.7.0

package/src/{cli.ts → cli/cli.ts}

@@ -12,40 +12,24 @@ 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'
-import { createParser, type EventSourceMessage } from 'eventsource-parser'
-import pkg from '../package.json' with { type: 'json' }
+import pkg from '../../package.json' with { type: 'json' }
 import {
   injectCredentialsToEnv,
   PROVIDERS,
-  getChatGptAuth,
-  saveChatGptAuth,
   getKeyStatus,
 } from './credentials.js'
 import {
-  IMAGE_MODELS,
-  VIDEO_MODELS,
   DEFAULT_MODEL,
   DEFAULT_VIDEO_MODEL,
   getModelConfig,
-  createImageModel,
-  createTextModel,
-  createVideoModel,
-  shouldUseResponsesApi,
 } from './models.js'
 import {
   CATALOG,
@@ -65,21 +49,44 @@ import {
   unsubscribe,
   showUsage,
 } 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'
-}
+import {
+  generateImageUncached as generateImage,
+  generateVideoUncached as generateVideo,
+  calculateCost,
+  ValidationError,
+  type GeneratedFile,
+} from './generate.js'
+import {
+  generateSpeechUncached as generateSpeech,
+} from './speech-generate.js'
+import {
+  transcribeAudioUncached as transcribeAudio,
+  segmentsToWordTimestamps,
+} from './transcription-generate.js'
+import {
+  SPEECH_CATALOG,
+  type SpeechModelEntry,
+} from './speech-catalog.js'
+import {
+  TRANSCRIPTION_CATALOG,
+  type TranscriptionModelEntry,
+} from './transcription-catalog.js'
+import {
+  DEFAULT_SPEECH_MODEL,
+} from './speech-models.js'
+import {
+  DEFAULT_TRANSCRIPTION_MODEL,
+} from './transcription-models.js'
+import {
+  separateAudioUncached as separateAudio,
+  downloadStem,
+  type StemName,
+  type DemucsModel,
+} from './separation-generate.js'
+import {
+  cloneVoiceUncached as cloneVoice,
+  type CloneProvider,
+} from './clone-generate.js'
 
 const cli = goke('egaki')
 
@@ -358,18 +365,13 @@ cli
   .example('# Pipe to another tool')
   .example('egaki image "logo design" --stdout | convert - -resize 512x512 logo.png')
   .action(async (prompt, options) => {
-    // Inject stored API keys as env vars before calling the AI SDK.
-    injectCredentialsToEnv()
-
     const model = options.model ?? await resolveImageModel()
     const outputPath = options.output ?? 'egaki-output.png'
-    const count = options.count ?? 1
-    const config = getModelConfig(model)
-    const parsedAspectRatio = parseAspectRatioOption(options.aspectRatio)
 
     if (!options.stdout) {
       console.error(pc.dim(`Model: ${model}`))
       console.error(pc.dim(`Prompt: ${prompt}`))
+      console.error(pc.cyan('Generating...'))
     }
 
     const inputImages = await readInputImages(options.input)
@@ -377,56 +379,49 @@ cli
       ? await readInputSource(options.mask)
       : undefined
 
-    // When using ChatGPT OAuth with OpenAI image models, route through the
-    // Responses API + imageGeneration tool instead of the Image API.
-    // The Codex OAuth client lacks the `api.model.images.request` scope.
-    const useResponsesApi = config.strategy === 'image' && shouldUseResponsesApi(model)
+    const result = await runProviderCall('Image generation', () => generateImage({
+      prompt,
+      model,
+      count: options.count ?? 1,
+      aspectRatio: options.aspectRatio,
+      seed: options.seed,
+      inputImages,
+      maskImage,
+      allowPeople: options.allowPeople || false,
+      quality: options.quality,
+      resolution: options.resolution,
+      outputFormat: options.outputFormat,
+      negativePrompt: options.negativePrompt,
+      imageSize: options.imageSize,
+    }))
+
+    if (options.stdout) {
+      writeFirstToStdout(result.images)
+      return
+    }
 
-    if (useResponsesApi) {
-      if (!options.stdout) {
-        console.error(pc.dim('Mode: Responses API (ChatGPT OAuth)'))
-      }
-      await generateWithResponsesApi({
-        prompt,
-        model,
-        outputPath,
-        count,
-        aspectRatio: parsedAspectRatio,
-        seed: options.seed,
-        inputImages,
-        maskImage,
-        json: options.json || false,
-        stdout: options.stdout || false,
-      })
-    } else if (config.strategy === 'image') {
-      await generateWithImageModel({
-        prompt,
-        model,
-        outputPath,
-        count,
-        aspectRatio: parsedAspectRatio,
-        seed: options.seed,
-        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,
-      })
-    } else {
-      await generateWithTextModel({
-        prompt,
+    const savedFiles = saveGeneratedFiles(result.images, outputPath)
+    printCost(result.cost)
+
+    if (result.revisedPrompt && !options.json) {
+      console.error(pc.dim(`Revised prompt: ${result.revisedPrompt}`))
+    }
+
+    if (result.text && !options.json) {
+      console.error(pc.dim(result.text))
+    }
+
+    if (options.json) {
+      console.log(JSON.stringify({
         model,
-        outputPath,
-        inputImages,
-        imageSize: options.imageSize,
-        aspectRatio: options.aspectRatio,
-        json: options.json || false,
-        stdout: options.stdout || false,
-      })
+        files: savedFiles,
+        count: result.images.length,
+        cost: result.cost,
+        usage: result.usage,
+        warnings: result.warnings,
+        ...(result.text ? { text: result.text } : {}),
+        ...(result.revisedPrompt !== undefined ? { revisedPrompt: result.revisedPrompt } : {}),
+      }, null, 2))
     }
   })
 
@@ -501,7 +496,7 @@ cli
     z
       .array(z.string())
       .describe(
-        'Reference images for R2V generation, repeatable, 1-7 files or URLs (xAI)',
+        'Reference images for R2V generation, repeatable. xAI: 1-7 images. Seedance: 1-9 images (use @Image1 etc. in prompt)',
       ),
   )
   .option(
@@ -535,18 +530,17 @@ cli
 
     const model = options.model ?? await resolveVideoModel()
     const outputPath = options.output ?? 'egaki-output.mp4'
-    const count = options.count ?? 1
     const config = getModelConfig(model)
 
-    if (config.strategy !== 'video') {
-      console.error(pc.red(`Model ${model} is not a video model`))
+    if (config instanceof Error) {
+      console.error(pc.red(config.message))
       process.exit(1)
     }
 
     if (!options.stdout) {
       console.error(pc.dim(`Model: ${model}`))
       console.error(pc.dim(`Prompt: ${prompt}`))
-      console.error(pc.dim('Mode: Video API (experimental_generateVideo)'))
+      console.error(pc.cyan('Generating...'))
     }
 
     // Determine how --input is used based on --mode:
@@ -554,28 +548,21 @@ cli
     // - 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)
+    // Auto-set --mode reference-to-video for providers that require it (xAI) when
+    // --reference-images is provided without an explicit --mode.
+    if (options.referenceImages?.length && !options.mode && config.provider === 'xai') {
+      options.mode = 'reference-to-video'
     }
 
     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(
@@ -583,24 +570,587 @@ cli
       )
     }
 
-    await generateWithVideoModel({
-      prompt,
-      model,
-      outputPath,
-      count,
-      aspectRatio: options.aspectRatio,
-      resolution: options.resolution,
-      duration: options.duration,
-      fps: options.fps,
-      seed: options.seed,
-      inputImage,
-      mode: options.mode,
-      videoUrl,
-      referenceImages: resolvedReferenceImages,
-      negativePrompt: options.negativePrompt,
-      json: options.json || false,
-      stdout: options.stdout || false,
-    })
+    const result = await runProviderCall('Video generation', () => generateVideo({
+      prompt,
+      model,
+      count: options.count ?? 1,
+      aspectRatio: options.aspectRatio,
+      resolution: options.resolution,
+      duration: options.duration,
+      fps: options.fps,
+      seed: options.seed,
+      inputImage,
+      mode: options.mode,
+      videoUrl,
+      referenceImages: resolvedReferenceImages,
+      negativePrompt: options.negativePrompt,
+    }))
+
+    if (options.stdout) {
+      writeFirstToStdout(result.videos)
+      return
+    }
+
+    const savedFiles = saveGeneratedFiles(result.videos, outputPath)
+    printCost(result.cost)
+
+    if (options.json) {
+      console.log(JSON.stringify({
+        model,
+        files: savedFiles,
+        count: result.videos.length,
+        cost: result.cost,
+        warnings: result.warnings,
+        responses: result.responses,
+      }, null, 2))
+    }
+  })
+
+// ─── speech command ──────────────────────────────────────────────────────────
+
+cli
+  .command(
+    'speech [text]',
+    dedent`
+      Generate speech audio from text using AI text-to-speech models.
+      Supports OpenAI (tts-1, tts-1-hd, gpt-4o-mini-tts), ElevenLabs
+      (eleven_v3, eleven_multilingual_v2, eleven_flash_v2_5), and Cartesia
+      (sonic-3.5, sonic-3). Uses your provider API key directly (egaki
+      subscription does not cover speech yet).
+    `,
+  )
+  .option(
+    '-m, --model [model]',
+    z.string().describe('Speech model ID. If omitted, shows an interactive picker (or uses default in non-TTY mode)'),
+  )
+  .option(
+    '-o, --output [path]',
+    z
+      .string()
+      .default('egaki-output')
+      .describe('Output file path (extension added from audio format if omitted)'),
+  )
+  .option(
+    '--voice [voice]',
+    z
+      .string()
+      .describe('Voice ID or name (provider-specific). OpenAI: alloy, echo, nova, etc. ElevenLabs/Cartesia: voice ID from their library'),
+  )
+  .option(
+    '--output-format [format]',
+    z
+      .string()
+      .describe('Audio output format: mp3, wav, pcm, opus, aac, flac (provider support varies)'),
+  )
+  .option(
+    '--speed [speed]',
+    z
+      .number()
+      .describe('Playback speed multiplier (OpenAI: 0.25-4.0, Cartesia: 0.6-1.5)'),
+  )
+  .option(
+    '--instructions [text]',
+    z
+      .string()
+      .describe('Style instructions for speech (only gpt-4o-mini-tts and ElevenLabs). E.g. "Speak in a calm, soothing tone"'),
+  )
+  .option(
+    '--language [lang]',
+    z
+      .string()
+      .describe('ISO 639-1 language code (e.g. en, es, fr). ElevenLabs and Cartesia'),
+  )
+  .option(
+    '--stdin',
+    'Read text from stdin instead of the positional argument',
+  )
+  .option(
+    '--json',
+    'Output result metadata as JSON to stdout (model, file path, cost)',
+  )
+  .option(
+    '--stdout',
+    'Write raw audio bytes to stdout instead of saving to a file. Useful for piping',
+  )
+  .example('# Generate speech with default model')
+  .example('egaki speech "Hello, welcome to egaki!"')
+  .example('# Use a specific model and voice')
+  .example('egaki speech "Good morning" -m tts-1-hd --voice nova')
+  .example('# Use GPT-4o Mini TTS with style instructions')
+  .example('egaki speech "Breaking news today" -m gpt-4o-mini-tts --instructions "Speak like a news anchor"')
+  .example('# ElevenLabs with a voice ID')
+  .example('egaki speech "Hello world" -m eleven_v3 --voice 21m00Tcm4TlvDq8ikWAM')
+  .example('# Read text from stdin')
+  .example('cat script.txt | egaki speech --stdin -o narration.mp3')
+  .example('# Cartesia Sonic 3.5 with a voice ID')
+  .example('egaki speech "Hello world" -m sonic-3.5 --voice f786b574-daa5-4673-aa0c-cbe3e8534c02')
+  .example('# Pipe audio to another tool')
+  .example('egaki speech "test" --stdout | ffplay -nodisp -autoexit -')
+  .action(async (text = '', options) => {
+    let inputText = text
+    if (options.stdin) {
+      inputText = await readTextFromStdin()
+    }
+
+    if (!inputText || inputText.trim().length === 0) {
+      console.error(pc.red('No text provided. Pass text as an argument or use --stdin.'))
+      process.exit(1)
+    }
+
+    const model = options.model ?? await resolveSpeechModel()
+    const outputPath = options.output ?? 'egaki-output'
+
+    if (!options.stdout) {
+      console.error(pc.dim(`Model: ${model}`))
+      console.error(pc.dim(`Text: ${inputText.length > 80 ? inputText.slice(0, 80) + '...' : inputText}`))
+      console.error(pc.cyan('Generating speech...'))
+    }
+
+    const result = await runProviderCall('Speech generation', () => generateSpeech({
+      text: inputText,
+      model,
+      voice: options.voice,
+      outputFormat: options.outputFormat,
+      instructions: options.instructions,
+      speed: options.speed,
+      language: options.language,
+    }))
+
+    if (options.stdout) {
+      process.stdout.write(Buffer.from(result.audio.uint8Array))
+      return
+    }
+
+    const ext = extensionFromMediaType(result.audio.mediaType)
+    const finalPath = ensureExtension(outputPath, ext)
+    fs.writeFileSync(finalPath, result.audio.uint8Array)
+    console.error(pc.green(`Saved: ${finalPath}`))
+    printCost(result.cost)
+
+    if (options.json) {
+      console.log(JSON.stringify({
+        model,
+        file: finalPath,
+        cost: result.cost,
+        textLength: inputText.length,
+        timestamps: result.timestamps ? result.timestamps.length : 0,
+      }, null, 2))
+    }
+  })
+
+// ─── transcribe command ──────────────────────────────────────────────────────
+
+cli
+  .command(
+    'transcribe [audio]',
+    dedent`
+      Transcribe audio to text using AI speech-to-text models.
+      Supports OpenAI (whisper-1, gpt-4o-transcribe, gpt-4o-mini-transcribe),
+      ElevenLabs (scribe_v1), Deepgram (nova-3), Groq (whisper-large-v3,
+      whisper-large-v3-turbo, distil-whisper-large-v3-en), and Cartesia
+      (ink-whisper). Outputs JSON with text, timestamps, language, and duration.
+    `,
+  )
+  .option(
+    '-m, --model [model]',
+    z.string().describe('Transcription model ID. If omitted, shows an interactive picker (or uses default in non-TTY mode)'),
+  )
+  .option(
+    '-o, --output [path]',
+    z
+      .string()
+      .describe('Output file path for the JSON result'),
+  )
+  .option(
+    '--language [lang]',
+    z
+      .string()
+      .describe('ISO 639-1 language hint (e.g. en, es, fr). Helps accuracy for known languages'),
+  )
+  .option(
+    '--stdin',
+    'Read audio from stdin instead of a file path',
+  )
+  .option(
+    '--stdout',
+    'Write only the plain text transcript to stdout (no JSON metadata)',
+  )
+  .example('# Transcribe an audio file with default model')
+  .example('egaki transcribe recording.mp3')
+  .example('# Use a specific model')
+  .example('egaki transcribe interview.wav -m gpt-4o-transcribe')
+  .example('# Groq for fast, cheap transcription')
+  .example('egaki transcribe podcast.mp3 -m whisper-large-v3')
+  .example('# Get plain text only')
+  .example('egaki transcribe recording.mp3 --stdout')
+  .example('# Save JSON result to file')
+  .example('egaki transcribe recording.mp3 -o transcript.json')
+  .example('# Pipe audio from another command')
+  .example('ffmpeg -i video.mp4 -f mp3 - | egaki transcribe --stdin -m whisper-1')
+  .action(async (audioPath = '', options) => {
+    if (!options.stdin && !audioPath) {
+      console.error(pc.red('No audio provided. Pass an audio file path or use --stdin.'))
+      process.exit(1)
+    }
+
+    let audioData: Uint8Array
+
+    if (options.stdin) {
+      const chunks: Buffer[] = []
+      for await (const chunk of process.stdin) {
+        chunks.push(chunk)
+      }
+      audioData = new Uint8Array(Buffer.concat(chunks))
+    } else {
+      const resolved = path.resolve(audioPath)
+      if (!fs.existsSync(resolved)) {
+        console.error(pc.red(`File not found: ${resolved}`))
+        process.exit(1)
+      }
+      audioData = new Uint8Array(fs.readFileSync(resolved))
+    }
+
+    if (audioData.length === 0) {
+      console.error(pc.red('No audio data provided. Pass an audio file path or use --stdin.'))
+      process.exit(1)
+    }
+
+    const model = options.model ?? await resolveTranscriptionModel()
+
+    if (!options.stdout) {
+      console.error(pc.dim(`Model: ${model}`))
+      console.error(pc.dim(`Audio: ${options.stdin ? 'stdin' : audioPath} (${(audioData.length / 1024).toFixed(1)} KB)`))
+      console.error(pc.cyan('Transcribing...'))
+    }
+
+    const result = await runProviderCall('Transcription', () => transcribeAudio({
+      audio: audioData,
+      model,
+      language: options.language,
+    }))
+
+    if (options.stdout) {
+      process.stdout.write(result.text)
+      return
+    }
+
+    const output = {
+      text: result.text,
+      segments: result.segments,
+      wordTimestamps: segmentsToWordTimestamps(result.segments),
+      language: result.language,
+      durationInSeconds: result.durationInSeconds,
+      model: result.model,
+      cost: result.cost,
+    }
+
+    if (options.output) {
+      const outputPath = path.resolve(options.output)
+      fs.writeFileSync(outputPath, JSON.stringify(output, null, 2))
+      console.error(pc.green(`Saved: ${outputPath}`))
+    } else {
+      console.log(JSON.stringify(output, null, 2))
+    }
+
+    printCost(result.cost)
+  })
+
+// ─── demucs command ──────────────────────────────────────────────────────────
+
+cli
+  .command(
+    'demucs [audio]',
+    dedent`
+      Separate audio into stems (vocals, background, drums, bass, etc.)
+      using fal.ai's Demucs model. Requires a fal.ai API key.
+      By default extracts vocals and background (other) stems.
+    `,
+  )
+  .option(
+    '--stems [list]',
+    z
+      .string()
+      .describe('Comma-separated stems to extract: vocals, drums, bass, other, guitar, piano. Default: vocals,other'),
+  )
+  .option(
+    '--model [model]',
+    z
+      .string()
+      .describe('Demucs model variant. Default: htdemucs_6s. Options: htdemucs, htdemucs_ft, htdemucs_6s, hdemucs_mmi, mdx, mdx_extra, mdx_q, mdx_extra_q'),
+  )
+  .option(
+    '--output-format [format]',
+    z
+      .enum(['mp3', 'wav'])
+      .default('mp3')
+      .describe('Output audio format: mp3 or wav'),
+  )
+  .option(
+    '-o, --output [dir]',
+    z
+      .string()
+      .describe('Output directory for separated stems. Default: current directory'),
+  )
+  .option(
+    '--shifts [n]',
+    z
+      .number()
+      .describe('Number of random shifts for quality (higher = better but slower). Default: 1'),
+  )
+  .option(
+    '--overlap [n]',
+    z
+      .number()
+      .describe('Segment overlap 0.0-1.0 (higher = better quality). Default: 0.25'),
+  )
+  .option(
+    '--stdin',
+    'Read audio from stdin instead of a file path',
+  )
+  .option(
+    '--json',
+    'Output result metadata as JSON to stdout',
+  )
+  .example('# Separate vocals and background from an audio file')
+  .example('egaki demucs song.mp3')
+  .example('# Extract all stems (vocals, drums, bass, guitar, piano, other)')
+  .example('egaki demucs song.mp3 --stems vocals,drums,bass,other,guitar,piano')
+  .example('# Extract only vocals as WAV')
+  .example('egaki demucs song.mp3 --stems vocals --output-format wav')
+  .example('# Save to a specific directory')
+  .example('egaki demucs song.mp3 -o stems/')
+  .example('# Higher quality (slower)')
+  .example('egaki demucs song.mp3 --shifts 5')
+  .action(async (audioPath = '', options) => {
+    if (!options.stdin && !audioPath) {
+      console.error(pc.red('No audio provided. Pass an audio file path or use --stdin.'))
+      process.exit(1)
+    }
+
+    let audioData: Uint8Array
+    let filename: string | undefined
+
+    if (options.stdin) {
+      const chunks: Buffer[] = []
+      for await (const chunk of process.stdin) {
+        chunks.push(chunk)
+      }
+      audioData = new Uint8Array(Buffer.concat(chunks))
+    } else {
+      const resolved = path.resolve(audioPath)
+      if (!fs.existsSync(resolved)) {
+        console.error(pc.red(`File not found: ${resolved}`))
+        process.exit(1)
+      }
+      audioData = new Uint8Array(fs.readFileSync(resolved))
+      filename = path.basename(resolved)
+    }
+
+    if (audioData.length === 0) {
+      console.error(pc.red('No audio data provided.'))
+      process.exit(1)
+    }
+
+    const stems: StemName[] = options.stems
+      ? (options.stems as string).split(',').map((s: string) => s.trim() as StemName)
+      : ['vocals', 'other']
+    const model = (options.model ?? 'htdemucs_6s') as DemucsModel
+    const outputFormat = options.outputFormat ?? 'mp3'
+    const outputDir = options.output ? path.resolve(options.output) : process.cwd()
+
+    console.error(pc.dim(`Model: ${model}`))
+    console.error(pc.dim(`Stems: ${stems.join(', ')}`))
+    console.error(pc.dim(`Audio: ${options.stdin ? 'stdin' : audioPath} (${(audioData.length / 1024 / 1024).toFixed(1)} MB)`))
+    console.error(pc.cyan('Separating audio...'))
+
+    const result = await runProviderCall('Audio separation', () => separateAudio({
+      audio: audioData,
+      stems,
+      model,
+      outputFormat,
+      shifts: options.shifts,
+      overlap: options.overlap,
+      filename,
+      onProgress: (msg) => console.error(pc.dim(msg)),
+    }))
+
+    // Create output directory if needed
+    if (!fs.existsSync(outputDir)) {
+      fs.mkdirSync(outputDir, { recursive: true })
+    }
+
+    // Download and save each stem
+    const baseName = filename
+      ? path.basename(filename, path.extname(filename))
+      : 'audio'
+    const savedFiles: Array<{ stem: string; path: string; size: number }> = []
+
+    for (const stem of result.stems) {
+      console.error(pc.dim(`Downloading ${stem.name}...`))
+      const bytes = await downloadStem(stem.url)
+      if (bytes instanceof Error) {
+        console.error(pc.red(`Failed to download ${stem.name}: ${bytes.message}`))
+        continue
+      }
+      const stemPath = path.join(outputDir, `${baseName}-${stem.name}.${outputFormat}`)
+      fs.writeFileSync(stemPath, bytes)
+      savedFiles.push({ stem: stem.name, path: stemPath, size: bytes.length })
+      console.error(pc.green(`Saved: ${stemPath} (${(bytes.length / 1024 / 1024).toFixed(1)} MB)`))
+    }
+
+    if (options.json) {
+      console.log(JSON.stringify({
+        model: result.model,
+        stems: savedFiles,
+      }, null, 2))
+    }
+  })
+
+// ─── voice clone command ─────────────────────────────────────────────────────
+
+cli
+  .command(
+    'voice clone [audio]',
+    dedent`
+      Clone a voice from an audio clip. Returns a voice ID for use with
+      'egaki speech --voice <id>'. Supports Cartesia (default) and ElevenLabs.
+
+      Best practices for high-quality clones:
+
+      1. Isolate vocals first: 'egaki demucs recording.mp3 --stems vocals'
+         removes background music, noise, and other speakers.
+      2. Find a clean snippet: 'egaki transcribe recording-vocals.mp3' to get
+         word timestamps. Pick a 5-10s segment with a complete phrase, clear
+         speech, no hesitations or crosstalk.
+      3. Trim to speech boundaries:
+         ffmpeg -i recording-vocals.mp3 -ss 12.5 -to 22.0 -c copy clip.mp3
+         No silence padding at start or end.
+      4. Match energy to intent: the clone mimics the tone and pacing of the
+         source clip. Use an energetic clip for energetic output.
+       5. Speak in the target language. Use --language for Cartesia clones.
+
+      Cartesia: up to 10s of audio, instant, free. Good for short clean clips.
+      ElevenLabs: 1-3 min recommended, has --remove-background-noise option.
+    `,
+  )
+  .option(
+    '--name [name]',
+    z
+      .string()
+      .describe('Name for the cloned voice (required)'),
+  )
+  .option(
+    '-p, --provider [provider]',
+    z
+      .enum(['cartesia', 'elevenlabs'])
+      .default('cartesia')
+      .describe('Voice cloning provider: cartesia or elevenlabs'),
+  )
+  .option(
+    '--language [lang]',
+    z
+      .string()
+      .describe('Cartesia only: ISO 639-1 language code (default: en). E.g. en, es, fr, de, ja'),
+  )
+  .option(
+    '--description [text]',
+    z
+      .string()
+      .describe('Optional description for the voice'),
+  )
+  .option(
+    '--base-voice-id [id]',
+    z
+      .string()
+      .describe('Cartesia: optional base voice ID to derive from'),
+  )
+  .option(
+    '--remove-background-noise',
+    'ElevenLabs: apply AI noise removal to the clip before cloning',
+  )
+  .option(
+    '--stdin',
+    'Read audio from stdin instead of a file path',
+  )
+  .option(
+    '--json',
+    'Output result as JSON to stdout',
+  )
+  .example('# Clone a voice from a recording')
+  .example('egaki voice clone recording.wav --name "My Voice"')
+  .example('# Clone with ElevenLabs and noise removal')
+  .example('egaki voice clone vocals.mp3 --name "Narrator" --provider elevenlabs --remove-background-noise')
+  .example('# Full pipeline: separate → trim → clone')
+  .example('egaki demucs interview.mp3 --stems vocals')
+  .example('ffmpeg -i interview-vocals.mp3 -ss 5.0 -to 15.0 -c copy clip.mp3')
+  .example('egaki voice clone clip.mp3 --name "Speaker"')
+  .example('# Use the cloned voice')
+  .example('egaki speech "Hello world" --voice <voice-id>')
+  .action(async (audioPath = '', options) => {
+    if (!options.stdin && !audioPath) {
+      console.error(pc.red('No audio provided. Pass an audio file path or use --stdin.'))
+      process.exit(1)
+    }
+
+    const name = options.name
+    if (!name) {
+      console.error(pc.red('Voice name is required. Use --name "My Voice".'))
+      process.exit(1)
+    }
+
+    let audioData: Uint8Array
+    let filename: string | undefined
+
+    if (options.stdin) {
+      const chunks: Buffer[] = []
+      for await (const chunk of process.stdin) {
+        chunks.push(chunk)
+      }
+      audioData = new Uint8Array(Buffer.concat(chunks))
+    } else {
+      const resolved = path.resolve(audioPath)
+      if (!fs.existsSync(resolved)) {
+        console.error(pc.red(`File not found: ${resolved}`))
+        process.exit(1)
+      }
+      audioData = new Uint8Array(fs.readFileSync(resolved))
+      filename = path.basename(resolved)
+    }
+
+    if (audioData.length === 0) {
+      console.error(pc.red('No audio data provided.'))
+      process.exit(1)
+    }
+
+    const provider = (options.provider ?? 'cartesia') as CloneProvider
+
+    console.error(pc.dim(`Provider: ${provider}`))
+    console.error(pc.dim(`Name: ${name}`))
+    console.error(pc.dim(`Audio: ${options.stdin ? 'stdin' : audioPath} (${(audioData.length / 1024).toFixed(1)} KB)`))
+    console.error(pc.cyan('Cloning voice...'))
+
+    const result = await runProviderCall('Voice cloning', () => cloneVoice({
+      audio: audioData,
+      name,
+      provider,
+      language: options.language,
+      description: options.description,
+      baseVoiceId: options.baseVoiceId,
+      removeBackgroundNoise: options.removeBackgroundNoise || false,
+      filename,
+    }))
+
+    console.error(pc.green(`Voice cloned successfully!`))
+    console.error(pc.bold(`Voice ID: ${result.voiceId}`))
+    console.error(pc.dim(`Use it: egaki speech "Hello" --voice ${result.voiceId}`))
+
+    if (options.json) {
+      console.log(JSON.stringify({
+        voiceId: result.voiceId,
+        name: result.name,
+        provider: result.provider,
+      }, null, 2))
+    }
   })
 
 // ─── models command ──────────────────────────────────────────────────────────
@@ -620,9 +1170,9 @@ cli
   .option(
     '--type [type]',
     z
-      .enum(['all', 'image', 'video'])
+      .enum(['all', 'image', 'video', 'speech', 'transcription'])
       .default('all')
-      .describe('Filter by model type: image (image+text-image), video, or all'),
+      .describe('Filter by model type: image, video, speech, transcription, or all'),
   )
   .option('--json', 'Output as JSON instead of YAML')
   .action(async (options) => {
@@ -631,12 +1181,16 @@ cli
       Object.keys(PROVIDERS).map((provider) => [provider, getKeyStatus(provider)]),
     )
 
-    let models: Array<typeof CATALOG[number] | typeof VIDEO_CATALOG[number]> =
+    let models: Array<typeof CATALOG[number] | typeof VIDEO_CATALOG[number] | SpeechModelEntry | TranscriptionModelEntry> =
       options.type === 'video'
         ? [...VIDEO_CATALOG]
         : options.type === 'image'
           ? [...CATALOG]
-          : [...CATALOG, ...VIDEO_CATALOG]
+          : options.type === 'speech'
+            ? [...SPEECH_CATALOG]
+            : options.type === 'transcription'
+              ? [...TRANSCRIPTION_CATALOG]
+              : [...CATALOG, ...VIDEO_CATALOG, ...SPEECH_CATALOG, ...TRANSCRIPTION_CATALOG]
 
     if (options.provider) {
       models = models.filter((m) => m.provider === options.provider)
@@ -669,14 +1223,34 @@ cli
                 ? `${m.features.durationRangeSec.min}-${m.features.durationRangeSec.max}`
                 : 'unknown',
             }
-          : {
-              editing: m.features.editing,
-              inpainting: m.features.inpainting,
-              seed: m.features.seed,
-              multipleImages: m.features.multipleImages,
-              aspectRatios: m.features.aspectRatios.join(', ') || 'none',
-              ...(m.features.sizes ? { sizes: m.features.sizes.join(', ') } : {}),
-            },
+          : m.strategy === 'speech'
+            ? {
+                outputFormats: m.features.outputFormats.join(', '),
+                instructions: m.features.instructions,
+                speed: m.features.speed,
+                language: m.features.language,
+                maxChars: m.features.maxChars || 'unlimited',
+                voices: m.features.defaultVoices.length > 0
+                  ? m.features.defaultVoices.join(', ')
+                  : 'use provider voice library',
+              }
+            : m.strategy === 'transcription'
+              ? {
+                  wordTimestamps: m.features.wordTimestamps,
+                  diarization: m.features.diarization,
+                  languageDetection: m.features.languageDetection,
+                  languageHint: m.features.languageHint,
+                  inputFormats: m.features.inputFormats.join(', '),
+                  maxDurationSec: m.features.maxDurationSec || 'unlimited',
+                }
+              : {
+                editing: m.features.editing,
+                inpainting: m.features.inpainting,
+                seed: m.features.seed,
+                multipleImages: m.features.multipleImages,
+                aspectRatios: m.features.aspectRatios.join(', ') || 'none',
+                ...(m.features.sizes ? { sizes: m.features.sizes.join(', ') } : {}),
+              },
     }))
 
     if (options.json) {
@@ -693,18 +1267,30 @@ const MAX_UPLOAD_SIZE = 100 * 1024 * 1024
 
 cli.help()
 cli.version(pkg.version)
-await cli.parse()
+
+export { cli }
+
 
 // ─── error output helpers ────────────────────────────────────────────────────
 
 type PrintableValue = unknown
 type ErrorDetailsInput = Parameters<typeof APICallError.isInstance>[0]
 
-async function runProviderCall<T>(operation: string, call: () => Promise<T>): Promise<T> {
+async function runProviderCall<T>(operation: string, call: () => Promise<Error | T>): Promise<T> {
   const result = await call().catch((error) => {
     printErrorDetails(error, operation)
     process.exit(1)
   })
+  if (result instanceof Error) {
+    // Validation errors get a clean one-line message; provider/runtime errors
+    // get full details (status code, response body, stack trace, etc.).
+    if (result instanceof ValidationError) {
+      console.error(pc.red(result.message))
+      process.exit(1)
+    }
+    printErrorDetails(result, operation)
+    process.exit(1)
+  }
   return result
 }
 
@@ -749,6 +1335,18 @@ function printErrorDetails(error: ErrorDetailsInput, operation?: string): void {
   if (error instanceof Error) {
     printKeyValue('name', error.name)
     printKeyValue('message', error.message)
+    // @ai-sdk/xai discards statusResponse.error when status==='failed',
+    // so XAI_VIDEO_GENERATION_FAILED carries no useful info. Add a hint.
+    if (error.name === 'XAI_VIDEO_GENERATION_FAILED') {
+      console.error(
+        pc.dim(
+          'hint: xAI returned status "failed" but @ai-sdk/xai discards the error details.\n' +
+            'Common causes: invalid/corrupt input image, content policy violation, or transient backend error.\n' +
+            'To see the real error, poll the video status endpoint manually:\n' +
+            '  curl https://api.x.ai/v1/videos/<request_id> -H "Authorization: Bearer $TOKEN"',
+        ),
+      )
+    }
     printJsonBlock('details', serializeOwnProperties(error))
     printCause(error.cause)
     printStack(error)
@@ -841,7 +1439,7 @@ const FEATURED_IMAGE_MODELS = [
   'flux-pro-1.1-ultra',
   'recraft-v4',
   'dall-e-3',
-  'grok-imagine-image-pro',
+  'grok-imagine-image-quality',
 ]
 
 /**
@@ -911,6 +1509,75 @@ async function resolveVideoModel(): Promise<string> {
   return selected
 }
 
+/**
+ * Resolve the speech model: show interactive picker in TTY, use default otherwise.
+ */
+async function resolveSpeechModel(): Promise<string> {
+  const isTTY = process.stdin.isTTY && process.stderr.isTTY
+  if (!isTTY) return DEFAULT_SPEECH_MODEL
+
+  const options = SPEECH_CATALOG.map((m) => {
+    const cost = pc.dim(`$${m.cost.perMillionChars}/M chars`)
+    return {
+      value: m.id,
+      label: `${m.name} ${cost}`,
+      hint: m.id,
+    }
+  })
+
+  const selected = await select({
+    message: 'Select a speech model',
+    options,
+  })
+
+  if (isCancel(selected)) {
+    cancel('Cancelled.')
+    process.exit(0)
+  }
+
+  return selected
+}
+
+/**
+ * Resolve the transcription model: show interactive picker in TTY, use default otherwise.
+ */
+async function resolveTranscriptionModel(): Promise<string> {
+  const isTTY = process.stdin.isTTY && process.stderr.isTTY
+  if (!isTTY) return DEFAULT_TRANSCRIPTION_MODEL
+
+  const options = TRANSCRIPTION_CATALOG.map((m) => {
+    const cost = pc.dim(`${formatCost(m.cost.perSecond * 60)}/min`)
+    return {
+      value: m.id,
+      label: `${m.name} ${cost}`,
+      hint: m.id,
+    }
+  })
+
+  const selected = await select({
+    message: 'Select a transcription model',
+    options,
+  })
+
+  if (isCancel(selected)) {
+    cancel('Cancelled.')
+    process.exit(0)
+  }
+
+  return selected
+}
+
+/**
+ * Read text from stdin (for piping: cat file.txt | egaki speech --stdin).
+ */
+async function readTextFromStdin(): Promise<string> {
+  const chunks: Buffer[] = []
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk)
+  }
+  return Buffer.concat(chunks).toString('utf-8').trim()
+}
+
 function isUrl(input: string): boolean {
   return /^https?:\/\//i.test(input)
 }
@@ -926,6 +1593,13 @@ function mimeTypeFromExtension(ext: string): string {
     '.jpeg': 'image/jpeg',
     '.webp': 'image/webp',
     '.gif': 'image/gif',
+    '.mp3': 'audio/mpeg',
+    '.wav': 'audio/wav',
+    '.pcm': 'audio/pcm',
+    '.opus': 'audio/opus',
+    '.aac': 'audio/aac',
+    '.flac': 'audio/flac',
+    '.ogg': 'audio/ogg',
   }
   return map[ext.toLowerCase()] || 'application/octet-stream'
 }
@@ -1007,639 +1681,8 @@ 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,
-  model,
-  outputPath,
-  count,
-  aspectRatio,
-  seed,
-  inputImages,
-  maskImage,
-  allowPeople,
-  quality,
-  resolution,
-  outputFormat,
-  negativePrompt,
-  json,
-  stdout,
-}: {
-  prompt: string
-  model: string
-  outputPath: string
-  count: number
-  aspectRatio?: `${number}:${number}`
-  seed?: number
-  inputImages: Uint8Array[]
-  maskImage?: Uint8Array
-  allowPeople: boolean
-  quality?: string
-  resolution?: string
-  outputFormat?: string
-  negativePrompt?: string
-  json: boolean
-  stdout: boolean
-}) {
-  // Build the prompt: plain string or multimodal with reference images
-  const imagePrompt = inputImages.length > 0
-    ? { text: prompt, images: inputImages, ...(maskImage ? { mask: maskImage } : {}) }
-    : prompt
-
-  const config = getModelConfig(model)
-  const imageModel = await createImageModel(model)
-
-  // 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 runProviderCall('Image generation', () => aiGenerateImage({
-    model: imageModel,
-    prompt: imagePrompt,
-    n: count,
-    ...(aspectRatio ? { aspectRatio } : {}),
-    ...(seed !== undefined ? { seed } : {}),
-    providerOptions,
-  }))
-
-  const files = result.images.map((img) => ({
-    uint8Array: img.uint8Array,
-    mediaType: img.mediaType,
-  }))
-
-  if (stdout) {
-    writeFirstToStdout(files)
-    return
-  }
-
-  const savedFiles = saveGeneratedFiles(files, outputPath)
-  const cost = calculateCost(config.cost, result.usage, result.images.length)
-  printCost(cost)
-
-  if (json) {
-    console.log(JSON.stringify({
-      model,
-      files: savedFiles,
-      count: result.images.length,
-      cost,
-      usage: result.usage,
-      warnings: result.warnings,
-    }, null, 2))
-  }
-}
-
-// Generate using generateText with responseModalities (Gemini multimodal models)
-async function generateWithTextModel({
-  prompt,
-  model,
-  outputPath,
-  inputImages,
-  imageSize,
-  aspectRatio,
-  json,
-  stdout,
-}: {
-  prompt: string
-  model: string
-  outputPath: string
-  inputImages: Uint8Array[]
-  imageSize?: '1K' | '2K' | '4K'
-  aspectRatio?: string
-  json: boolean
-  stdout: boolean
-}) {
-  const textModel = await createTextModel(model)
-  const config = getModelConfig(model)
-
-  if (!stdout) {
-    console.error(pc.cyan('Generating...'))
-  }
-
-  // Build messages: if we have input images, create a multimodal prompt
-  const messages = inputImages.length > 0
-    ? [
-        {
-          role: 'user' as const,
-          content: [
-            { type: 'text' as const, text: prompt },
-            ...inputImages.map((img) => ({
-              type: 'image' as const,
-              image: img,
-            })),
-          ],
-        },
-      ]
-    : undefined
-
-  // 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]: googleOpts,
-    },
-  }))
-
-  const imageFiles = result.files.filter((f) => f.mediaType.startsWith('image/'))
-
-  if (imageFiles.length === 0) {
-    console.error(pc.red('No images generated.'))
-    process.exit(1)
-  }
-
-  if (stdout) {
-    writeFirstToStdout(imageFiles)
-    return
-  }
-
-  const savedFiles = saveGeneratedFiles(imageFiles, outputPath)
-  const cost = calculateCost(config.cost, result.usage, imageFiles.length)
-  printCost(cost)
-
-  if (result.text && !json) {
-    console.error(pc.dim(result.text))
-  }
-
-  if (json) {
-    console.log(JSON.stringify({
-      model,
-      files: savedFiles,
-      count: imageFiles.length,
-      text: result.text || null,
-      cost,
-      usage: result.usage,
-    }, null, 2))
-  }
-}
-
-// Generate using the OpenAI Responses API with imageGeneration tool.
-// Used when auth comes from ChatGPT OAuth (no Image API scope).
-async function generateWithResponsesApi({
-  prompt,
-  model,
-  outputPath,
-  count,
-  aspectRatio,
-  seed,
-  inputImages,
-  maskImage,
-  json,
-  stdout,
-}: {
-  prompt: string
-  model: string
-  outputPath: string
-  count: number
-  aspectRatio?: `${number}:${number}`
-  seed?: number
-  inputImages: Uint8Array[]
-  maskImage?: Uint8Array
-  json: boolean
-  stdout: boolean
-}) {
-  if (count !== 1) {
-    console.error(pc.red('ChatGPT image generation currently supports exactly one output image.'))
-    process.exit(1)
-  }
-
-  if (seed !== undefined) {
-    console.error(pc.red('ChatGPT image generation does not support --seed.'))
-    process.exit(1)
-  }
-
-  if (maskImage) {
-    console.error(pc.red('ChatGPT image generation does not support --mask yet.'))
-    process.exit(1)
-  }
-
-  const size = aspectRatio ? chatGptImageSizeFromAspectRatio(aspectRatio) : undefined
-  if (aspectRatio && !size) {
-    console.error(
-      pc.red(
-        'ChatGPT image generation only supports --aspect-ratio 1:1, 3:2, or 2:3.',
-      ),
-    )
-    process.exit(1)
-  }
-
-  const storedAuth = getChatGptAuth()
-  if (!storedAuth?.accountId) {
-    console.error(pc.red('Missing ChatGPT account metadata. Please run `egaki login --provider chatgpt` again.'))
-    process.exit(1)
-  }
-
-  const auth = await getValidChatGptAuth(storedAuth, saveChatGptAuth)
-  if (auth instanceof Error) {
-    console.error(pc.red(auth.message))
-    process.exit(1)
-  }
-
-  if (!stdout) {
-    console.error(pc.cyan('Generating...'))
-  }
-
-  const content: Array<{ type: 'input_text'; text: string } | { type: 'input_image'; image_url: string }> = [
-    { type: 'input_text', text: prompt },
-    ...inputImages.map((image) => ({
-      type: 'input_image' as const,
-      image_url: imageBytesToDataUrl(image),
-    })),
-  ]
-
-  const response = await fetch('https://chatgpt.com/backend-api/codex/responses', {
-    method: 'POST',
-    headers: {
-      Authorization: `Bearer ${auth.access}`,
-      'ChatGPT-Account-ID': auth.accountId,
-      'Content-Type': 'application/json',
-    },
-    body: JSON.stringify({
-      model: 'gpt-5.4',
-      instructions: 'You are Codex.',
-      input: [
-        {
-          type: 'message',
-          role: 'user',
-          content,
-        },
-      ],
-      tools: [
-        {
-          type: 'image_generation',
-          model,
-          size: 'auto',
-          quality: 'auto',
-          output_format: 'png',
-          output_compression: 100,
-          moderation: 'auto',
-          ...(size ? { size } : {}),
-        },
-      ],
-      tool_choice: 'auto',
-      parallel_tool_calls: true,
-      stream: true,
-      store: false,
-      include: [],
-    }),
-  })
-
-  if (!response.ok || !response.body) {
-    const body = await response.text().catch(() => '')
-    console.error(pc.red(`ChatGPT image generation failed: ${response.status}`))
-    if (body) console.error(pc.dim(body))
-    process.exit(1)
-  }
-
-  let imageBase64: string | undefined
-  let revisedPrompt: string | null = null
-
-  const processSseMessage = (message: EventSourceMessage) => {
-    if (!message.data) return
-    try {
-      const event = JSON.parse(message.data) as {
-        type?: string
-        partial_image_b64?: string
-        item?: { type?: string; result?: string; revised_prompt?: string | null }
-      }
-      if (
-        event.type === 'response.image_generation_call.partial_image' &&
-        event.partial_image_b64 &&
-        !imageBase64
-      ) {
-        imageBase64 = event.partial_image_b64
-      }
-      if (
-        event.type === 'response.output_item.done' &&
-        event.item?.type === 'image_generation_call'
-      ) {
-        if (event.item.result) imageBase64 = event.item.result
-        revisedPrompt = event.item.revised_prompt ?? revisedPrompt
-      }
-    } catch {
-      // Ignore keepalive and partial parse noise.
-    }
-  }
-
-  const parser = createParser({
-    onEvent: processSseMessage,
-  })
-
-  const decoder = new TextDecoder()
-
-  for await (const chunk of response.body) {
-    parser.feed(decoder.decode(chunk, { stream: true }))
-  }
-  parser.feed(decoder.decode())
-
-  if (!imageBase64) {
-    console.error(pc.red('No images generated.'))
-    process.exit(1)
-  }
-
-  const imageBytes = Buffer.from(imageBase64, 'base64')
-  const mediaType = 'image/png'
-
-  if (stdout) {
-    process.stdout.write(imageBytes)
-    return
-  }
-
-  const savedFiles: string[] = []
-  const filePath = ensureExtension(outputPath, extensionFromMediaType(mediaType))
-  fs.writeFileSync(filePath, imageBytes)
-  console.error(pc.green(`Saved: ${filePath}`))
-  savedFiles.push(filePath)
-
-  if (revisedPrompt && !json) {
-    console.error(pc.dim(`Revised prompt: ${revisedPrompt}`))
-  }
-
-  if (json) {
-    const output = {
-      model,
-      files: savedFiles,
-      count: 1,
-      revisedPrompt,
-    }
-    console.log(JSON.stringify(output, null, 2))
-  }
-}
-
-// Generate using experimental_generateVideo (video models)
-async function generateWithVideoModel({
-  prompt,
-  model,
-  outputPath,
-  count,
-  aspectRatio,
-  resolution,
-  duration,
-  fps,
-  seed,
-  inputImage,
-  mode,
-  videoUrl,
-  referenceImages,
-  negativePrompt,
-  json,
-  stdout,
-}: {
-  prompt: string
-  model: string
-  outputPath: string
-  count: number
-  aspectRatio?: string
-  resolution?: string
-  duration?: number
-  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 runProviderCall('Video generation', () => aiGenerateVideo({
-    model: videoModel,
-    prompt: inputImage
-      ? { image: inputImage, text: prompt }
-      : prompt,
-    n: count,
-    ...(aspectRatio ? { aspectRatio: aspectRatio as `${number}:${number}` } : {}),
-    ...(resolution ? { resolution: resolution as `${number}x${number}` } : {}),
-    ...(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) {
-    writeFirstToStdout(files)
-    return
-  }
-
-  const savedFiles = saveGeneratedFiles(files, outputPath)
-  const cost = calculateCost(config.cost, {
-    videosGenerated: result.videos.length,
-    durationSeconds: duration,
-    resolution,
-  }, result.videos.length)
-  printCost(cost)
-
-  if (json) {
-    console.log(JSON.stringify({
-      model,
-      files: savedFiles,
-      count: result.videos.length,
-      cost,
-      warnings: result.warnings,
-      responses: result.responses,
-    }, 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,
@@ -1660,18 +1703,12 @@ function saveGeneratedFiles(
   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) {
@@ -1679,54 +1716,7 @@ function writeFirstToStdout(files: GeneratedFile[]): void {
   }
 }
 
-// ─── cost helpers ────────────────────────────────────────────────────────────
-
-function calculateCost(
-  cost: {
-    type: 'per-image'
-    perImage: number
-  } | {
-    type: 'per-token'
-    inputPerM: number
-    outputPerM: number
-  } | {
-    type: 'per-video-second'
-    defaultDurationSec: number
-    tiers: Array<{ resolution?: string; costPerSecond: number }>
-  } | {
-    type: 'unknown'
-  },
-  usage: {
-    inputTokens?: number
-    outputTokens?: number
-    imagesGenerated?: number
-    videosGenerated?: number
-    durationSeconds?: number
-    resolution?: string
-  },
-  count: number = 1,
-): number | null {
-  if (cost.type === 'per-image') {
-    return cost.perImage * count
-  }
-  if (cost.type === 'per-token' && usage.inputTokens != null && usage.outputTokens != null) {
-    return (
-      (usage.inputTokens * cost.inputPerM + usage.outputTokens * cost.outputPerM) / 1_000_000
-    )
-  }
-  if (cost.type === 'per-video-second') {
-    const durationSec = usage.durationSeconds ?? cost.defaultDurationSec
-    const resolution = normalizeResolutionKey(usage.resolution)
-    const tier =
-      cost.tiers.find((t) => normalizeResolutionKey(t.resolution) === resolution) ??
-      cost.tiers[0]
-    if (!tier) {
-      return null
-    }
-    return tier.costPerSecond * durationSec * count
-  }
-  return null
-}
+// ─── display helpers ─────────────────────────────────────────────────────────
 
 function formatCatalogCost(
   cost: {
@@ -1740,6 +1730,12 @@ function formatCatalogCost(
     type: 'per-video-second'
     defaultDurationSec: number
     tiers: Array<{ resolution?: string; mode?: string; audio?: boolean; costPerSecond: number }>
+  } | {
+    type: 'per-character'
+    perMillionChars: number
+  } | {
+    type: 'per-second'
+    perSecond: number
   } | {
     type: 'unknown'
   },
@@ -1750,6 +1746,12 @@ function formatCatalogCost(
   if (cost.type === 'per-token') {
     return `$${cost.inputPerM}/M input, $${cost.outputPerM}/M output`
   }
+  if (cost.type === 'per-character') {
+    return `$${cost.perMillionChars}/M chars`
+  }
+  if (cost.type === 'per-second') {
+    return `${formatCost(cost.perSecond * 60)}/min`
+  }
   if (cost.type === 'per-video-second') {
     const tierText = cost.tiers
       .map((t) => {
@@ -1769,6 +1771,9 @@ function formatCatalogCost(
 }
 
 function formatCost(dollars: number): string {
+  if (dollars < 0.0001) {
+    return `$${dollars.toFixed(6)}`
+  }
   if (dollars < 0.01) {
     return `$${dollars.toFixed(4)}`
   }
@@ -1784,71 +1789,18 @@ function extensionFromMediaType(mediaType: string): string {
     'video/mp4': '.mp4',
     'video/webm': '.webm',
     'video/quicktime': '.mov',
+    'audio/mpeg': '.mp3',
+    'audio/wav': '.wav',
+    'audio/pcm': '.pcm',
+    'audio/opus': '.opus',
+    'audio/aac': '.aac',
+    'audio/flac': '.flac',
+    'audio/ogg': '.ogg',
   }
-  return map[mediaType] || (mediaType.startsWith('video/') ? '.mp4' : '.png')
-}
-
-function inferImageMediaType(image: Uint8Array): string {
-  if (image.length >= 8 && image[0] === 0x89 && image[1] === 0x50 && image[2] === 0x4e && image[3] === 0x47) {
-    return 'image/png'
-  }
-  if (image.length >= 3 && image[0] === 0xff && image[1] === 0xd8 && image[2] === 0xff) {
-    return 'image/jpeg'
-  }
-  if (
-    image.length >= 12 &&
-    image[0] === 0x52 && image[1] === 0x49 && image[2] === 0x46 && image[3] === 0x46 &&
-    image[8] === 0x57 && image[9] === 0x45 && image[10] === 0x42 && image[11] === 0x50
-  ) {
-    return 'image/webp'
-  }
-  if (
-    image.length >= 6 &&
-    image[0] === 0x47 && image[1] === 0x49 && image[2] === 0x46 && image[3] === 0x38
-  ) {
-    return 'image/gif'
-  }
-  return 'image/png'
-}
-
-function imageBytesToDataUrl(image: Uint8Array): string {
-  const mediaType = inferImageMediaType(image)
-  return `data:${mediaType};base64,${Buffer.from(image).toString('base64')}`
-}
-
-function chatGptImageSizeFromAspectRatio(
-  aspectRatio: `${number}:${number}`,
-): '1024x1024' | '1536x1024' | '1024x1536' | undefined {
-  switch (aspectRatio) {
-    case '1:1':
-      return '1024x1024'
-    case '3:2':
-      return '1536x1024'
-    case '2:3':
-      return '1024x1536'
-    default:
-      return undefined
-  }
-}
-
-function normalizeResolutionKey(input?: string): string | undefined {
-  if (!input) return undefined
-  const normalized = input.trim().toLowerCase()
-  if (normalized === '1920x1080') return '1080p'
-  if (normalized === '1280x720') return '720p'
-  if (normalized === '854x480' || normalized === '848x480') return '480p'
-  return normalized
-}
-
-function isAspectRatio(input: string): input is `${number}:${number}` {
-  return /^\d+:\d+$/.test(input)
-}
-
-function parseAspectRatioOption(input?: string): `${number}:${number}` | undefined {
-  if (!input || !isAspectRatio(input)) {
-    return undefined
-  }
-  return input
+  if (map[mediaType]) return map[mediaType]!
+  if (mediaType.startsWith('audio/')) return '.mp3'
+  if (mediaType.startsWith('video/')) return '.mp4'
+  return '.png'
 }
 
 function ensureExtension(filePath: string, ext: string): string {