@telepat/rilo 0.1.7 → 0.1.8

package/README.de.md

@@ -0,0 +1,101 @@
+<p align="center"><img src="./assets/avatar/rilo-logo.webp" width="128" alt="Rilo"></p>
+<h1 align="center">Rilo</h1>
+<p align="center"><em>Verwandle eine Geschichte in ein fertiges Video — KI-generiertes Skript, Voiceover, Keyframes und Komposition, alles mit einem Befehl.</em></p>
+
+<p align="center">
+  <a href="https://docs.telepat.io/rilo">📖 Docs</a>
+  · <a href="./README.md">🇺🇸 English</a>
+  · <a href="./README.zh-CN.md">🇨🇳 简体中文</a>
+  · <a href="./README.de.md">🇩🇪 Deutsch</a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/telepat-io/rilo/actions/workflows/ci.yml"><img src="https://github.com/telepat-io/rilo/actions/workflows/ci.yml/badge.svg?branch=main" alt="Build"></a>
+  <a href="https://codecov.io/gh/telepat-io/rilo"><img src="https://codecov.io/gh/telepat-io/rilo/graph/badge.svg" alt="Codecov"></a>
+  <a href="https://www.npmjs.com/package/@telepat/rilo"><img src="https://img.shields.io/npm/v/@telepat/rilo" alt="npm"></a>
+  <a href="https://github.com/telepat-io/rilo/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-yellow.svg" alt="License"></a>
+</p>
+
+Rilo verwandelt eine Geschichte in ein fertiges Video — KI-generiertes Skript, Voiceover, Keyframes und Komposition, alles mit einem Befehl.
+
+Schreiben Sie Ihre Geschichte in einfachem Text. Rilo übernimmt den Rest: Skripterstellung, Erzählung, visuelle Keyframes, Videosegmente und die finale Komposition – mit optionaler Untertitel-Synchronisation und Einbrennung.
+
+Entwickelt für Kreative und Teams, die reproduzierbare, hochwertige Videos in großem Umfang ohne manuellen Schnitt benötigen.
+
+## Features
+
+- **Vollständige Pipeline, ein Befehl** — Story → Skript → Voiceover → Keyframes → Segmente → finales Video. `rilo --project demo --story-file ./story.txt`
+- **Checkpoint-gestützte Durchläufe** — Jede Stufe speichert Artefakte. Setzen Sie beliebige Stufen fort oder generieren Sie sie selektiv neu. `rilo --project demo --force`
+- **Ihre Modelle, Ihre Kontrolle** — Wählen Sie T2I- und I2V-Modelle. Überschreiben Sie modellspezifische Optionen. Wechseln Sie Modelle jederzeit.
+- **Code-gesteuerte Pipeline** — Deterministische Orchestrierung, Checkpointing und Artefaktverwaltung. Tokens werden für die Generierung ausgegeben, nicht für Infrastruktur.
+- **Untertitel-Synchronisation & Einbrennung** — Untertitel automatisch an Voiceover-Timing ausrichten. Ins finale Video einbrennen.
+- **Vorschau-Dashboard** — Web-UI für Projektverwaltung, Neugenerierung und Asset-Vorschau. `rilo preview`
+- **HTTP-API & Webhooks** — Bearer-Token-Authentifizierung, OpenAPI-3.1-Spezifikation, Webhook-Abonnements. Firebase oder lokal.
+- **Plattformübergreifend** — macOS, Linux, Windows. Node.js 22+ und ffmpeg.
+
+## Quick Start
+
+Voraussetzungen: Node.js 22+, ffmpeg im PATH und ein Replicate API-Token.
+
+```bash
+npm install -g @telepat/rilo
+rilo settings
+rilo --project demo --story-file ./story.txt
+```
+
+Erwartetes Ergebnis:
+
+- Ein Projektordner wird unter `projects/demo/` erstellt.
+- Die vollständige Pipeline durchläuft Skript, Voiceover, Keyframes, Segmente und Komposition.
+- Das finale Video wird unter `projects/demo/final.mp4` abgelegt.
+- Dashboard-Vorschau verfügbar via `rilo preview`.
+
+## Requirements
+
+- Node.js 22+
+- ffmpeg im PATH
+- Replicate API-Token
+- macOS, Linux oder Windows
+
+## How It Works
+
+Rilo durchläuft eine gestufte Pipeline: Skripterstellung, Voiceover-Synthese, Shot-Prompt-Generierung, Keyframe-Rendering, Segmentgenerierung und finale Videokomposition. Jede Stufe schreibt Checkpoint-Artefakte, sodass Sie selektiv fortsetzen oder neugenerieren können.
+
+Die Konfiguration fasst CLI-Flags, Umgebungsvariablen und `~/.rilo/config.json` mit Schema-Defaults zusammen. Das Vorschau-Dashboard (`rilo preview`) startet eine lokale API, einen Worker und ein Vite-React-Frontend für Monitoring und Bearbeitung.
+
+## Using With AI Agents
+
+Rilo bietet mehrere Schnittstellen für agentische und automatisierte Workflows:
+
+- **CLI-Automatisierung** — Die gesamte Generierung wird durch CLI-Flags und Umgebungsvariablen gesteuert. Nach der initialen Einrichtung sind keine interaktiven Prompts erforderlich.
+- **HTTP-API** — `rilo preview` startet eine Express-API mit vollständigem Job- und Projekt-CRUD, Asset-Serving und Webhook-Endpunkten. Bearer-Token-Authentifizierung via `Authorization: Bearer <API_BEARER_TOKEN>`.
+- **OpenAPI-Spezifikation** — Automatisch generierte OpenAPI-3.1-Spezifikation für schema-gesteuerte Agent-Integration.
+- **Webhooks** — Abonnieren Sie Job-Lifecycle-Events für externe Orchestrierung.
+- **Firebase Functions** — Stellen Sie `src/api/firebaseFunction.js` für serverloses API-Hosting bereit.
+- **Agent-Dokumentation** — [API Reference](https://docs.telepat.io/rilo/reference/api-reference) behandelt Endpunkte, Authentifizierung und Webhooks.
+
+## Security And Trust
+
+- API-Tokens und Replicate-Zugangsdaten werden, wenn verfügbar, im OS-Keystore gespeichert (macOS Keychain, Windows Credential Manager, Linux Secret Service).
+- Fallback auf eine AES-256-verschlüsselte Datei unter `~/.rilo/.secrets`, falls kein nativer Keystore verfügbar ist.
+- Umgebungsvariablen (`TELEPAT_REPLICATE_TOKEN`, `RILO_API_BEARER_TOKEN`) haben höchste Priorität und überschreiben gespeicherte Werte.
+- Der Preview-Modus `--expose` sollte nur in vertrauenswürdigen Netzwerken oder isolierten Umgebungen verwendet werden.
+
+## Documentation And Support
+
+- [Documentation site](https://docs.telepat.io/rilo)
+- [Quickstart](https://docs.telepat.io/rilo/getting-started/quickstart)
+- [CLI Reference](https://docs.telepat.io/rilo/reference/cli-reference)
+- [Configuration Guide](https://docs.telepat.io/rilo/guides/configuration)
+- [API Reference](https://docs.telepat.io/rilo/reference/api-reference)
+- [Troubleshooting](https://docs.telepat.io/rilo/guides/troubleshooting)
+- [Repository](https://github.com/telepat-io/rilo)
+- [npm package](https://www.npmjs.com/package/@telepat/rilo)
+
+## Contributing
+
+Beiträge sind willkommen. Siehe [Development](https://docs.telepat.io/rilo/contributing/development) für lokale Einrichtung, Build-Befehle und Test-Workflows.
+
+## License
+
+MIT. Siehe [LICENSE](./LICENSE).

package/README.md

@@ -6,6 +6,7 @@
   <a href="https://docs.telepat.io/rilo">📖 Docs</a>
   · <a href="./README.md">🇺🇸 English</a>
   · <a href="./README.zh-CN.md">🇨🇳 简体中文</a>
+  · <a href="./README.de.md">🇩🇪 Deutsch</a>
 </p>
 
 <p align="center">
@@ -77,7 +78,7 @@ Rilo provides multiple surfaces for agentic and automated workflows:
 
 - API tokens and Replicate credentials are stored in the OS keystore (macOS Keychain, Windows Credential Manager, Linux Secret Service) when available.
 - Falls back to an AES-256 encrypted file at `~/.rilo/.secrets` if no native keystore is available.
-- Environment variables (`RILO_REPLICATE_API_TOKEN`, `RILO_API_BEARER_TOKEN`) take highest precedence and override stored values.
+- Environment variables (`TELEPAT_REPLICATE_TOKEN`, `RILO_API_BEARER_TOKEN`) take highest precedence and override stored values.
 - Preview `--expose` mode should only be used on trusted networks or isolated environments.
 
 ## Documentation And Support

package/README.zh-CN.md

@@ -6,6 +6,7 @@
   <a href="https://docs.telepat.io/rilo">📖 文档</a>
   · <a href="./README.md">🇺🇸 English</a>
   · <a href="./README.zh-CN.md">🇨🇳 简体中文</a>
+  · <a href="./README.de.md">🇩🇪 Deutsch</a>
 </p>
 
 <p align="center">
@@ -77,7 +78,7 @@ Rilo 为智能体和自动化工作流提供多种接口：
 
 - API token 和 Replicate 凭证在 OS 密钥库可用时保存（macOS Keychain、Windows Credential Manager、Linux Secret Service）。
 - 如果无原生密钥库可用，则回退到 `~/.rilo/.secrets` 的 AES-256 加密文件。
-- 环境变量（`RILO_REPLICATE_API_TOKEN`、`RILO_API_BEARER_TOKEN`）优先级最高，会覆盖已存储的值。
+- 环境变量（`TELEPAT_REPLICATE_TOKEN`、`RILO_API_BEARER_TOKEN`）优先级最高，会覆盖已存储的值。
 - Preview `--expose` 模式应仅在可信网络或隔离环境中使用。
 
 ## 文档与支持

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telepat/rilo",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "license": "MIT",
   "bin": {
     "rilo": "src/cli/index.js"
@@ -53,6 +53,7 @@
     "express": "^4.21.2",
     "firebase-admin": "^13.4.0",
     "firebase-functions": "^6.4.0",
+    "@telepat/limn": "^0.1.7",
     "replicate": "^1.0.1",
     "uuid": "^11.1.0"
   },

package/src/api/firebaseFunction.js

@@ -21,7 +21,7 @@ const runtimeOptions = {
   invoker: 'public',
   secrets: [
     'SECRET_API_BEARER_TOKEN',
-    'SECRET_REPLICATE_API_TOKEN',
+    'TELEPAT_REPLICATE_TOKEN',
     'SECRET_OUTPUT_BACKEND',
     'SECRET_FIREBASE_PROJECT_ID',
     'SECRET_FIREBASE_STORAGE_BUCKET'

package/src/cli/index.js

@@ -138,7 +138,7 @@ SETTINGS
     npm install -g @telepat/rilo
 
   Or with environment variables:
-    export RILO_REPLICATE_API_TOKEN=r8_xxxxx
+    export TELEPAT_REPLICATE_TOKEN=r8_xxxxx
     export RILO_MAX_RETRIES=5
     export PREDICTION_MAX_WAIT_MS=900000
     rilo --project my-project --story-file ./story.txt

package/src/config/env.js

@@ -41,9 +41,11 @@ export function parseAllowedHosts(value, fallback = 'replicate.delivery,replicat
 
 export const env = {
   replicateApiToken: parseEnvString(
-    process.env.SECRET_REPLICATE_API_TOKEN
-      || process.env.RILO_REPLICATE_API_TOKEN
-      || process.env.REPLICATE_API_TOKEN,
+    process.env.TELEPAT_REPLICATE_TOKEN,
+    ''
+  ),
+  openRouterApiKey: parseEnvString(
+    process.env.TELEPAT_OPENROUTER_KEY,
     ''
   ),
   apiBearerToken: parseEnvString(
@@ -147,7 +149,7 @@ export async function applyStoredSettings() {
 
 export function assertRequiredEnv() {
   if (!env.replicateApiToken) {
-    throw new Error('Missing REPLICATE_API_TOKEN in environment');
+    throw new Error('Missing TELEPAT_REPLICATE_TOKEN in environment');
   }
 }
 

package/src/config/models.js

@@ -1,17 +1,17 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import {
+  getLimnGenerationModels,
+  isKnownLimnFamily,
+  resolveFamilyFromReplicateModelId
+} from '../images/limnModelCatalog.js';
 
 const CONFIG_DIR = path.dirname(fileURLToPath(import.meta.url));
 const MODELS_DIR = path.resolve(CONFIG_DIR, '../../models');
 
 export const MODELS = {
   deepseek: 'deepseek-ai/deepseek-v3',
-  keyframe: 'prunaai/z-image-turbo',
-  flux: 'black-forest-labs/flux-2-pro',
-  fluxSchnell: 'black-forest-labs/flux-schnell',
-  nanoBananaPro: 'google/nano-banana-pro',
-  seedream4: 'bytedance/seedream-4',
   video: 'wan-video/wan-2.2-i2v-fast',
   klingVideo3: 'kwaivgi/kling-v3-video',
   pixverseV56: 'pixverse/pixverse-v5.6',
@@ -32,7 +32,7 @@ export const MODEL_CATEGORIES = {
 export const DEFAULT_MODEL_SELECTIONS = {
   [MODEL_CATEGORIES.textToText]: MODELS.deepseek,
   [MODEL_CATEGORIES.textToSpeech]: MODELS.tts,
-  [MODEL_CATEGORIES.textToImage]: MODELS.keyframe,
+  [MODEL_CATEGORIES.textToImage]: 'z-image',
   [MODEL_CATEGORIES.imageTextToVideo]: MODELS.video
 };
 
@@ -41,11 +41,6 @@ export const MODEL_OPTION_KEYS = [...MODEL_SELECTION_KEYS];
 
 const MODEL_METADATA_FILES = {
   [MODELS.deepseek]: 'deepseek-ai__deepseek-v3.json',
-  [MODELS.keyframe]: 'prunaai__z-image-turbo.json',
-  [MODELS.flux]: 'black-forest-labs__flux-2-pro.json',
-  [MODELS.fluxSchnell]: 'black-forest-labs__flux-schnell.json',
-  [MODELS.nanoBananaPro]: 'google__nano-banana-pro.json',
-  [MODELS.seedream4]: 'bytedance__seedream-4.json',
   [MODELS.video]: 'wan-video__wan-2.2-i2v-fast.json',
   [MODELS.klingVideo3]: 'kwaivgi__kling-v3-video.json',
   [MODELS.pixverseV56]: 'pixverse__pixverse-v5.6.json',
@@ -59,10 +54,13 @@ const MODEL_METADATA_FILES = {
 export const MODEL_IDS_BY_CATEGORY = {
   [MODEL_CATEGORIES.textToText]: [MODELS.deepseek],
   [MODEL_CATEGORIES.textToSpeech]: [MODELS.tts, MODELS.chatterboxTurbo, MODELS.kokoro82m],
-  [MODEL_CATEGORIES.textToImage]: [MODELS.keyframe, MODELS.flux, MODELS.fluxSchnell, MODELS.nanoBananaPro, MODELS.seedream4],
   [MODEL_CATEGORIES.imageTextToVideo]: [MODELS.video, MODELS.klingVideo3, MODELS.pixverseV56, MODELS.veo31, MODELS.veo31Fast]
 };
 
+export function getTextToImageModelIds() {
+  return getLimnGenerationModels().map((model) => model.family);
+}
+
 export function toNullableNumber(value) {
   if (value === null || value === undefined || value === '') {
     return null;
@@ -109,7 +107,14 @@ export const MODEL_METADATA = Object.fromEntries(
   Object.values(MODELS).map((modelId) => [modelId, readModelMetadata(modelId)])
 );
 
-export const SUPPORTED_MODEL_IDS = Object.keys(MODEL_METADATA);
+export const SUPPORTED_MODEL_IDS = [
+  ...Object.keys(MODEL_METADATA),
+  ...getTextToImageModelIds(),
+  ...getTextToImageModelIds().flatMap((family) => {
+    const match = getLimnGenerationModels().find((m) => m.family === family);
+    return match ? match.replicateModelIds : [];
+  })
+];
 
 export const MODEL_PRICING = Object.fromEntries(
   Object.entries(MODEL_METADATA).map(([modelId, metadata]) => [modelId, normalizePricing(metadata.pricing || {})])
@@ -181,6 +186,9 @@ export function resolveProjectModelOptions(modelOptions = {}, modelSelections =
 }
 
 export function isKnownModelId(modelId) {
+  if (typeof modelId === 'string' && isKnownLimnFamily(modelId)) {
+    return true;
+  }
   return typeof modelId === 'string' && SUPPORTED_MODEL_IDS.includes(modelId);
 }
 
@@ -198,10 +206,22 @@ export function resolveProjectModelSelections(modelSelections = {}) {
   for (const key of MODEL_SELECTION_KEYS) {
     const candidate = modelSelections[key];
     if (typeof candidate === 'string' && candidate.trim()) {
-      resolved[key] = candidate.trim();
+      const trimmed = candidate.trim();
+      // Normalize old Replicate T2I IDs to Limn family names
+      if (key === MODEL_CATEGORIES.textToImage) {
+        const family = resolveFamilyFromReplicateModelId(trimmed);
+        resolved[key] = family ?? trimmed;
+      } else {
+        resolved[key] = trimmed;
+      }
     }
   }
 
+  // Preserve textToImageReplicateModel if present
+  if (typeof modelSelections.textToImageReplicateModel === 'string' && modelSelections.textToImageReplicateModel.trim()) {
+    resolved.textToImageReplicateModel = modelSelections.textToImageReplicateModel.trim();
+  }
+
   return resolved;
 }
 
@@ -217,6 +237,10 @@ export function getSupportedModelIdsForCategory(category) {
     throw new Error(`Unknown model category: ${category}`);
   }
 
+  if (category === MODEL_CATEGORIES.textToImage) {
+    return getTextToImageModelIds();
+  }
+
   return [...(MODEL_IDS_BY_CATEGORY[category] || [])];
 }
 

package/src/config/settingsSchema.js

@@ -22,7 +22,16 @@ export const SETTINGS = [
     description: 'Your Replicate API key (replicate.com/account/api-tokens).',
     type: 'secure',
     keystoreKey: 'replicateApiToken',
-    envNames: ['RILO_REPLICATE_API_TOKEN', 'REPLICATE_API_TOKEN'],
+    envNames: ['TELEPAT_REPLICATE_TOKEN'],
+    default: ''
+  },
+  {
+    id: 'openRouterApiKey',
+    label: 'OpenRouter API Key',
+    description: 'Your OpenRouter API key for LLM-driven prompt transformation (openrouter.ai/keys).',
+    type: 'secure',
+    keystoreKey: 'openRouterApiKey',
+    envNames: ['TELEPAT_OPENROUTER_KEY'],
     default: ''
   },
   {

package/src/images/limnModelCatalog.js

@@ -0,0 +1,39 @@
+import { getSupportedModelCatalog } from '@telepat/limn';
+
+export function getLimnGenerationModels() {
+  return getSupportedModelCatalog().filter((entry) => entry.generationEnabled);
+}
+
+export const DEFAULT_LIMN_MODEL_ID = 'z-image';
+
+export function resolveFamilyFromReplicateModelId(replicateModelId) {
+  const match = getLimnGenerationModels().find((model) =>
+    model.replicateModelIds.includes(replicateModelId)
+  );
+  return match?.family ?? null;
+}
+
+export function isKnownLimnFamily(family) {
+  return getLimnGenerationModels().some((model) => model.family === family);
+}
+
+export function isReplicateModelIdForFamily(family, replicateModelId) {
+  const match = getLimnGenerationModels().find((model) => model.family === family);
+  if (!match) {
+    return false;
+  }
+  return match.replicateModelIds.includes(replicateModelId);
+}
+
+export function getLimnReplicateModelsForFamily(family) {
+  const match = getLimnGenerationModels().find((model) => model.family === family);
+  if (!match) {
+    return [];
+  }
+  return [...match.replicateModelIds];
+}
+
+export function getLimnDefaultReplicateModel(family) {
+  const match = getLimnGenerationModels().find((model) => model.family === family);
+  return match?.defaultReplicateModelId ?? null;
+}

package/src/pipeline/orchestrator.js

@@ -28,17 +28,21 @@ import {
 import {
   DEFAULT_VIDEO_CONFIG,
   MODEL_CATEGORIES,
+  MODEL_SELECTION_KEYS,
   resolveKeyframeSize,
   resolveProjectModelOptions,
   resolveProjectModelSelections,
   resolveShotCount,
   resolveTargetDurationSec
 } from '../config/models.js';
+import { Limn } from '@telepat/limn';
+import { resolveFamilyFromReplicateModelId } from '../images/limnModelCatalog.js';
 import fs from 'node:fs/promises';
 import crypto from 'node:crypto';
 import path from 'node:path';
 import { ensureDir, writeJson } from '../media/files.js';
 import { probeMediaDurationSeconds } from '../media/ffmpeg.js';
+import { env } from '../config/env.js';
 import {
   ensureProject,
   readProjectConfig,
@@ -229,6 +233,15 @@ export async function regenerateProjectAsset(projectName, target, options = {})
   const projectConfig = await deps.readProjectConfig(project);
   const modelSelections = resolveProjectModelSelections(projectConfig.models);
   const modelOptions = resolveProjectModelOptions(projectConfig.modelOptions, modelSelections);
+  const rawT2IModel = modelSelections[MODEL_CATEGORIES.textToImage];
+  const limnFamily = resolveFamilyFromReplicateModelId(rawT2IModel) ?? rawT2IModel;
+  const limnImageDryRun = !env.replicateApiToken;
+  const limn = limnImageDryRun ? null : new Limn({
+    openrouterApiKey: env.openRouterApiKey || undefined,
+    replicateApiKey: env.replicateApiToken,
+    openrouterModel: modelSelections[MODEL_CATEGORIES.textToText]
+  });
+  const t2iReplicateModel = modelSelections.textToImageReplicateModel || undefined;
   const projectDir = deps.getProjectDir(project);
   const runState = await deps.readProjectRunState(project);
 
@@ -452,21 +465,21 @@ export async function regenerateProjectAsset(projectName, target, options = {})
   }
 
   if (targetType === 'keyframe') {
-    const keyframeSize = resolveKeyframeSize(projectConfig);
-    const keyframeUrl = await deps.generateKeyframe(
+    const keyframeResult = await deps.generateKeyframe(
       artifacts.shots[index],
       artifacts.tone || 'neutral',
       projectConfig.aspectRatio,
       index,
       traceBase,
-      keyframeSize,
       {
-        modelId: modelSelections[MODEL_CATEGORIES.textToImage],
+        limn,
+        family: limnFamily,
+        replicateModel: t2iReplicateModel,
         modelOptions: modelOptions[MODEL_CATEGORIES.textToImage]
       }
     );
-    artifacts.keyframeUrls[index] = keyframeUrl;
-    artifacts.keyframePaths[index] = await deps.persistKeyframe(projectDir, keyframeUrl, index);
+    artifacts.keyframeUrls[index] = keyframeResult.outputUrl || keyframeResult.modelSlug;
+    artifacts.keyframePaths[index] = await deps.persistKeyframe(projectDir, keyframeResult, index);
 
     const affectedSegmentIndexes = collectAffectedSegmentIndexes([index], artifacts.shots.length);
     const maxSegmentIndex = Math.max(0, artifacts.shots.length - 1);
@@ -627,6 +640,15 @@ export async function runPipeline(jobId, options = {}) {
     const projectConfig = await deps.readProjectConfig(project);
     const modelSelections = resolveProjectModelSelections(projectConfig.models);
     const modelOptions = resolveProjectModelOptions(projectConfig.modelOptions, modelSelections);
+    const rawT2IModel = modelSelections[MODEL_CATEGORIES.textToImage];
+    const limnFamily = resolveFamilyFromReplicateModelId(rawT2IModel) ?? rawT2IModel;
+    const limnImageDryRun = !env.replicateApiToken;
+    const limn = limnImageDryRun ? null : new Limn({
+      openrouterApiKey: env.openRouterApiKey || undefined,
+      replicateApiKey: env.replicateApiToken,
+      openrouterModel: modelSelections[MODEL_CATEGORIES.textToText]
+    });
+    const t2iReplicateModel = modelSelections.textToImageReplicateModel || undefined;
     const projectDir = deps.getProjectDir(project);
     const targetDurationSec = resolveTargetDurationSec(projectConfig);
     const plannedShots = resolveShotCount(projectConfig);
@@ -899,6 +921,10 @@ export async function runPipeline(jobId, options = {}) {
       (category) => JSON.stringify(previousModelOptions[category]) !== JSON.stringify(modelOptions[category])
     );
 
+    const modelSelectionsChanged = MODEL_SELECTION_KEYS.some(
+      (key) => modelSelections[key] !== previousModelSelections[key]
+    );
+
     const resetFromScript = () => {
       seedSteps[JobStep.SCRIPT] = false;
       seedSteps[JobStep.VOICE] = false;
@@ -975,7 +1001,7 @@ export async function runPipeline(jobId, options = {}) {
       resetFromScript();
     }
 
-    if (JSON.stringify(previousModelSelections) !== JSON.stringify(modelSelections)) {
+    if (modelSelectionsChanged) {
       resetFromScript();
     }
 
@@ -1214,20 +1240,21 @@ export async function runPipeline(jobId, options = {}) {
         if (shotIndex < 0 || shotIndex >= currentJob.artifacts.shots.length) {
           continue;
         }
-        const keyframeUrl = await deps.generateKeyframe(
+        const keyframeResult = await deps.generateKeyframe(
           currentJob.artifacts.shots[shotIndex],
           currentJob.artifacts.tone || 'neutral',
           projectConfig.aspectRatio,
           shotIndex,
           traceBase,
-          keyframeSize,
           {
-            modelId: modelSelections[MODEL_CATEGORIES.textToImage],
+            limn,
+            family: limnFamily,
+            replicateModel: t2iReplicateModel,
             modelOptions: modelOptions[MODEL_CATEGORIES.textToImage]
           }
         );
-        keyframeUrls[shotIndex] = keyframeUrl;
-        keyframePaths[shotIndex] = await deps.persistKeyframe(projectDir, keyframeUrl, shotIndex);
+        keyframeUrls[shotIndex] = keyframeResult.outputUrl || keyframeResult.modelSlug;
+        keyframePaths[shotIndex] = await deps.persistKeyframe(projectDir, keyframeResult, shotIndex);
       }
 
       const totalShots = currentJob.artifacts.shots.length;
@@ -1356,18 +1383,20 @@ export async function runPipeline(jobId, options = {}) {
         }
 
         if (!hasUrl) {
-          keyframeUrls[shotIndex] = await deps.generateKeyframe(
+          const keyframeResult = await deps.generateKeyframe(
             currentJob.artifacts.shots[shotIndex],
             currentJob.artifacts.tone || 'neutral',
             projectConfig.aspectRatio,
             shotIndex,
             traceBase,
-            keyframeSize,
             {
-              modelId: modelSelections[MODEL_CATEGORIES.textToImage],
+              limn,
+              family: limnFamily,
+              replicateModel: t2iReplicateModel,
               modelOptions: modelOptions[MODEL_CATEGORIES.textToImage]
             }
           );
+          keyframeUrls[shotIndex] = keyframeResult.outputUrl || keyframeResult.modelSlug;
         }
 
         keyframePaths[shotIndex] = await deps.persistKeyframe(projectDir, keyframeUrls[shotIndex], shotIndex);

package/src/steps/generateKeyframes.js

@@ -1,68 +1,94 @@
-import { ASPECT_RATIO_PRESETS, MODEL_CATEGORIES, resolveModelForCategory } from '../config/models.js';
-import { runModel, extractOutputUri } from '../providers/predictions.js';
 import path from 'node:path';
-import { downloadToFile, ensureDir } from '../media/files.js';
-import { resolveTextToImageAdapter } from './textToImageAdapters.js';
+import { writeFile } from 'node:fs/promises';
+import { ensureDir } from '../media/files.js';
 
 export async function generateKeyframe(
   promptText,
   tone,
   aspectRatio = '9:16',
   index = 0,
-  trace = null,
-  sizeOverride = null,
+  _trace,
   options = {}
 ) {
   const deps = options.deps || {};
-  const runModelFn = deps.runModel || runModel;
-  const extractOutputUriFn = deps.extractOutputUri || extractOutputUri;
+  const limn = options.limn || deps.limn || null;
+  const family = options.family;
+  const replicateModel = options.replicateModel;
+  const modelOptions = options.modelOptions ?? {};
 
-  const preset = ASPECT_RATIO_PRESETS[aspectRatio] || ASPECT_RATIO_PRESETS['9:16'];
-  const width = sizeOverride?.width || preset.keyframeWidth || ASPECT_RATIO_PRESETS['9:16'].keyframeWidth;
-  const height = sizeOverride?.height || preset.keyframeHeight || ASPECT_RATIO_PRESETS['9:16'].keyframeHeight;
-  const modelId = options.modelId || resolveModelForCategory(MODEL_CATEGORIES.textToImage);
-  const modelOptions = options.modelOptions;
-  const adapter = resolveTextToImageAdapter(modelId);
+  if (!family) {
+    throw new Error('Limn model family is required for keyframe generation');
+  }
+
+  if (!limn) {
+    throw new Error('Limn instance is required for keyframe generation');
+  }
 
-  const prediction = await runModelFn({
-    model: modelId,
-    input: adapter.buildInput({ promptText, tone, index, aspectRatio, width, height, modelOptions }),
-    trace: trace ? { ...trace, step: 'keyframe', index } : null
+  const result = await limn.generate(promptText, family, {
+    aspectRatio,
+    ...(replicateModel ? { replicateModel } : {}),
+    options: modelOptions
   });
 
-  const imageUrl = extractOutputUriFn(prediction.output);
-  if (!imageUrl) {
+  if (!result || !result.image) {
     throw new Error(`Missing keyframe output for shot ${index + 1}`);
   }
 
-  return imageUrl;
+  return {
+    buffer: result.image,
+    outputUrl: result.outputUrl || '',
+    mimeType: result.mimeType || 'image/png',
+    modelSlug: result.modelSlug || family
+  };
 }
 
-export async function generateKeyframes(shots, tone, aspectRatio = '9:16', trace = null, options = {}) {
-  const urls = [];
+export async function generateKeyframes(shots, tone, aspectRatio = '9:16', _trace, options = {}) {
+  const results = [];
   for (let i = 0; i < shots.length; i += 1) {
-    const imageUrl = await generateKeyframe(shots[i], tone, aspectRatio, i, trace, null, options);
-    urls.push(imageUrl);
+    const result = await generateKeyframe(shots[i], tone, aspectRatio, i, _trace, options);
+    results.push(result);
   }
-  return urls;
+  return results;
+}
+
+function mimeTypeToExtension(mimeType) {
+  if (mimeType === 'image/jpeg') return 'jpg';
+  if (mimeType === 'image/webp') return 'webp';
+  return 'png';
 }
 
-export async function persistKeyframe(projectDir, keyframeUrl, index, options = {}) {
+export async function persistKeyframe(projectDir, keyframeResult, index, options = {}) {
   const deps = options.deps || {};
   const ensureDirFn = deps.ensureDir || ensureDir;
-  const downloadToFileFn = deps.downloadToFile || downloadToFile;
+  const writeFileFn = deps.writeFile || writeFile;
 
   const keyframesDir = path.join(projectDir, 'assets', 'keyframes');
   await ensureDirFn(keyframesDir);
-  const keyframePath = path.join(keyframesDir, `keyframe_${String(index + 1).padStart(2, '0')}.png`);
-  await downloadToFileFn(keyframeUrl, keyframePath);
-  return keyframePath;
+
+  // Handle Limn buffer result
+  if (keyframeResult && typeof keyframeResult === 'object' && keyframeResult.buffer) {
+    const ext = mimeTypeToExtension(keyframeResult.mimeType || 'image/png');
+    const keyframePath = path.join(keyframesDir, `keyframe_${String(index + 1).padStart(2, '0')}.${ext}`);
+    await writeFileFn(keyframePath, keyframeResult.buffer);
+    return keyframePath;
+  }
+
+  // Handle legacy URL string
+  if (typeof keyframeResult === 'string') {
+    const depsDownload = deps.downloadToFile;
+    const downloadToFileFn = depsDownload || (await import('../media/files.js')).downloadToFile;
+    const keyframePath = path.join(keyframesDir, `keyframe_${String(index + 1).padStart(2, '0')}.png`);
+    await downloadToFileFn(keyframeResult, keyframePath);
+    return keyframePath;
+  }
+
+  throw new Error('Invalid keyframe result: expected buffer object or URL string');
 }
 
-export async function persistKeyframes(projectDir, keyframeUrls, options = {}) {
+export async function persistKeyframes(projectDir, keyframeResults, options = {}) {
   const keyframePaths = [];
-  for (let i = 0; i < keyframeUrls.length; i += 1) {
-    const keyframePath = await persistKeyframe(projectDir, keyframeUrls[i], i, options);
+  for (let i = 0; i < keyframeResults.length; i += 1) {
+    const keyframePath = await persistKeyframe(projectDir, keyframeResults[i], i, options);
     keyframePaths.push(keyframePath);
   }
 

package/src/store/projectStore.js

@@ -5,11 +5,13 @@ import { ensureDir, writeJson } from '../media/files.js';
 import {
   DEFAULT_MODEL_SELECTIONS,
   DEFAULT_VIDEO_CONFIG,
+  MODEL_CATEGORIES,
   MODEL_OPTION_KEYS,
   MODEL_SELECTION_KEYS,
   SUPPORTED_MODEL_IDS,
   resolveModelInputOptionsForCategory,
-  resolveProjectModelOptions
+  resolveProjectModelOptions,
+  resolveProjectModelSelections
 } from '../config/models.js';
 
 export const SUPPORTED_ASPECT_RATIOS = ['1:1', '16:9', '9:16'];
@@ -358,6 +360,11 @@ function validateProjectModelOptions(modelOptions, modelSelections) {
       throw new Error(`Invalid project config: modelOptions.${category} must be an object`);
     }
 
+    // T2I model options are validated by Limn at generation time
+    if (category === MODEL_CATEGORIES.textToImage) {
+      continue;
+    }
+
     const inputOptions = resolveModelInputOptionsForCategory(category, modelSelections);
     const allowedOptions = new Set(inputOptions.userConfigurable);
     const fields = inputOptions.fields || {};
@@ -400,12 +407,18 @@ export function normalizeProjectConfig(config) {
     }
   }
 
+  // Reject unknown model selection keys before normalization
+  if (nextConfig.models && typeof nextConfig.models === 'object' && !Array.isArray(nextConfig.models)) {
+    for (const key of Object.keys(nextConfig.models)) {
+      if (!MODEL_SELECTION_KEYS.includes(key) && key !== 'textToImageReplicateModel') {
+        throw new Error(`Invalid project config: models.${key} is not a supported model category`);
+      }
+    }
+  }
+
   const mergedModels = nextConfig.models === undefined
     ? { ...DEFAULT_MODEL_SELECTIONS }
-    : {
-        ...DEFAULT_MODEL_SELECTIONS,
-        ...(nextConfig.models || {})
-      };
+    : resolveProjectModelSelections(nextConfig.models);
   const mergedModelOptions = mergeProjectModelOptions(nextConfig.modelOptions, mergedModels);
 
   return {

package/models/black-forest-labs__flux-2-pro.json

@@ -1,78 +0,0 @@
-{
-  "modelId": "black-forest-labs/flux-2-pro",
-  "provider": "replicate",
-  "displayName": "FLUX 2 Pro",
-  "category": "image-generation",
-  "pricingSourceUrl": "https://replicate.com/black-forest-labs/flux-2-pro",
-  "pricingNotes": "Replicate lists multi-property pricing for run and input/output megapixels; this model currently uses best-effort cost fallback when exact rule mapping is unavailable.",
-  "pricing": {
-    "usdPerSecond": null,
-    "usdPer1kInputTokens": null,
-    "usdPer1kOutputTokens": null
-  },
-  "inputOptions": {
-    "userConfigurable": [
-      "safety_tolerance",
-      "seed",
-      "output_format",
-      "output_quality"
-    ],
-    "pipelineManaged": [
-      "prompt",
-      "aspect_ratio",
-      "width",
-      "height"
-    ],
-    "fields": {
-      "safety_tolerance": {
-        "type": "integer",
-        "default": 2,
-        "minimum": 1,
-        "maximum": 5
-      },
-      "seed": {
-        "type": "integer",
-        "nullable": true
-      },
-      "output_format": {
-        "type": "string",
-        "default": "webp",
-        "enum": [
-          "webp",
-          "png",
-          "jpg",
-          "jpeg"
-        ]
-      },
-      "output_quality": {
-        "type": "integer",
-        "default": 80,
-        "minimum": 0,
-        "maximum": 100
-      },
-      "prompt": {
-        "type": "string",
-        "required": true
-      },
-      "aspect_ratio": {
-        "type": "string",
-        "required": true,
-        "enum": [
-          "custom"
-        ]
-      },
-      "width": {
-        "type": "integer",
-        "required": true,
-        "minimum": 256,
-        "maximum": 2048
-      },
-      "height": {
-        "type": "integer",
-        "required": true,
-        "minimum": 256,
-        "maximum": 2048
-      }
-    }
-  }
-}

package/models/black-forest-labs__flux-schnell.json

@@ -1,95 +0,0 @@
-{
-  "modelId": "black-forest-labs/flux-schnell",
-  "provider": "replicate",
-  "displayName": "FLUX Schnell",
-  "category": "image-generation",
-  "pricingSourceUrl": "https://replicate.com/black-forest-labs/flux-schnell",
-  "pricingNotes": "Replicate pricing: $3 per 1000 output images.",
-  "pricing": {
-    "usdPerSecond": null,
-    "usdPer1kInputTokens": null,
-    "usdPer1kOutputTokens": null
-  },
-  "pricingRules": {
-    "basis": "output_image_count",
-    "usdPerImage": 0.003
-  },
-  "inputOptions": {
-    "userConfigurable": [
-      "num_outputs",
-      "num_inference_steps",
-      "seed",
-      "output_format",
-      "output_quality",
-      "disable_safety_checker",
-      "go_fast",
-      "megapixels"
-    ],
-    "pipelineManaged": [
-      "prompt",
-      "aspect_ratio"
-    ],
-    "fields": {
-      "num_outputs": {
-        "type": "integer",
-        "default": 1,
-        "minimum": 1,
-        "maximum": 4
-      },
-      "num_inference_steps": {
-        "type": "integer",
-        "default": 4,
-        "minimum": 1,
-        "maximum": 4
-      },
-      "seed": {
-        "type": "integer",
-        "nullable": true
-      },
-      "output_format": {
-        "type": "string",
-        "default": "webp",
-        "enum": [
-          "webp",
-          "jpg",
-          "png"
-        ]
-      },
-      "output_quality": {
-        "type": "integer",
-        "default": 80,
-        "minimum": 0,
-        "maximum": 100
-      },
-      "disable_safety_checker": {
-        "type": "boolean",
-        "default": false
-      },
-      "go_fast": {
-        "type": "boolean",
-        "default": true
-      },
-      "megapixels": {
-        "type": "string",
-        "default": "1",
-        "allowAnyString": true,
-        "recommendedValues": [
-          "1"
-        ]
-      },
-      "prompt": {
-        "type": "string",
-        "required": true
-      },
-      "aspect_ratio": {
-        "type": "string",
-        "required": true,
-        "enum": [
-          "1:1",
-          "16:9",
-          "9:16"
-        ]
-      }
-    }
-  }
-}

package/models/bytedance__seedream-4.json

@@ -1,71 +0,0 @@
-{
-  "modelId": "bytedance/seedream-4",
-  "provider": "replicate",
-  "displayName": "Seedream 4",
-  "category": "image-generation",
-  "pricingSourceUrl": "https://replicate.com/bytedance/seedream-4",
-  "pricingNotes": "Replicate pricing: $0.03 per output image.",
-  "pricing": {
-    "usdPerSecond": null,
-    "usdPer1kInputTokens": null,
-    "usdPer1kOutputTokens": null
-  },
-  "pricingRules": {
-    "basis": "output_image_count",
-    "usdPerImage": 0.03
-  },
-  "inputOptions": {
-    "userConfigurable": [
-      "size",
-      "sequential_image_generation",
-      "max_images",
-      "enhance_prompt"
-    ],
-    "pipelineManaged": [
-      "prompt",
-      "aspect_ratio"
-    ],
-    "fields": {
-      "size": {
-        "type": "string",
-        "default": "2K",
-        "enum": [
-          "1K",
-          "2K",
-          "4K"
-        ]
-      },
-      "sequential_image_generation": {
-        "type": "string",
-        "default": "disabled",
-        "enum": [
-          "disabled",
-          "auto"
-        ]
-      },
-      "max_images": {
-        "type": "integer",
-        "default": 1,
-        "minimum": 1,
-        "maximum": 15
-      },
-      "enhance_prompt": {
-        "type": "boolean",
-        "default": true
-      },
-      "prompt": {
-        "type": "string",
-        "required": true
-      },
-      "aspect_ratio": {
-        "type": "string",
-        "required": true,
-        "enum": [
-          "1:1",
-          "16:9",
-          "9:16"
-        ]
-      }
-    }
-  }
-}

package/models/google__nano-banana-pro.json

@@ -1,92 +0,0 @@
-{
-  "modelId": "google/nano-banana-pro",
-  "provider": "replicate",
-  "displayName": "Nano Banana Pro",
-  "category": "image-generation",
-  "pricingSourceUrl": "https://replicate.com/google/nano-banana-pro",
-  "pricingNotes": "Replicate pricing by target resolution: 1K/2K=$0.15 per output image, 4K=$0.30 per output image, fallback tier=$0.035 per output image.",
-  "pricing": {
-    "usdPerSecond": null,
-    "usdPer1kInputTokens": null,
-    "usdPer1kOutputTokens": null
-  },
-  "pricingRules": {
-    "basis": "output_image_resolution",
-    "tiers": [
-      {
-        "resolution": "1K",
-        "usdPerImage": 0.15
-      },
-      {
-        "resolution": "2K",
-        "usdPerImage": 0.15
-      },
-      {
-        "resolution": "4K",
-        "usdPerImage": 0.3
-      },
-      {
-        "resolution": "fallback",
-        "usdPerImage": 0.035
-      }
-    ]
-  },
-  "inputOptions": {
-    "userConfigurable": [
-      "resolution",
-      "output_format",
-      "safety_filter_level",
-      "allow_fallback_model"
-    ],
-    "pipelineManaged": [
-      "prompt",
-      "aspect_ratio"
-    ],
-    "fields": {
-      "resolution": {
-        "type": "string",
-        "default": "2K",
-        "enum": [
-          "1K",
-          "2K",
-          "4K"
-        ]
-      },
-      "output_format": {
-        "type": "string",
-        "default": "jpg",
-        "enum": [
-          "jpg",
-          "png",
-          "webp"
-        ]
-      },
-      "safety_filter_level": {
-        "type": "string",
-        "default": "block_only_high",
-        "enum": [
-          "block_low_and_above",
-          "block_medium_and_above",
-          "block_only_high"
-        ]
-      },
-      "allow_fallback_model": {
-        "type": "boolean",
-        "default": false
-      },
-      "prompt": {
-        "type": "string",
-        "required": true
-      },
-      "aspect_ratio": {
-        "type": "string",
-        "required": true,
-        "enum": [
-          "1:1",
-          "16:9",
-          "9:16"
-        ]
-      }
-    }
-  }
-}

package/models/prunaai__z-image-turbo.json

@@ -1,107 +0,0 @@
-{
-  "modelId": "prunaai/z-image-turbo",
-  "provider": "replicate",
-  "displayName": "Z Image Turbo",
-  "category": "image-generation",
-  "pricingSourceUrl": "https://replicate.com/prunaai/z-image-turbo",
-  "pricingNotes": "Replicate pricing is tiered by output image resolution (megapixels).",
-  "pricing": {
-    "usdPerSecond": null,
-    "usdPer1kInputTokens": null,
-    "usdPer1kOutputTokens": null
-  },
-  "pricingRules": {
-    "basis": "output_image_megapixels",
-    "tiers": [
-      {
-        "maxMegapixels": 0.5,
-        "usdPerImage": 0.0025
-      },
-      {
-        "maxMegapixels": 1,
-        "usdPerImage": 0.005
-      },
-      {
-        "maxMegapixels": 2,
-        "usdPerImage": 0.01
-      },
-      {
-        "maxMegapixels": 3,
-        "usdPerImage": 0.015
-      },
-      {
-        "maxMegapixels": 4,
-        "usdPerImage": 0.02
-      }
-    ]
-  },
-  "inputOptions": {
-    "userConfigurable": [
-      "num_inference_steps",
-      "guidance_scale",
-      "seed",
-      "go_fast",
-      "output_format",
-      "output_quality"
-    ],
-    "pipelineManaged": [
-      "prompt",
-      "width",
-      "height"
-    ],
-    "fields": {
-      "num_inference_steps": {
-        "type": "integer",
-        "default": 8,
-        "minimum": 1,
-        "maximum": 50
-      },
-      "guidance_scale": {
-        "type": "number",
-        "default": 0,
-        "minimum": 0,
-        "maximum": 20
-      },
-      "seed": {
-        "type": "integer",
-        "nullable": true
-      },
-      "go_fast": {
-        "type": "boolean",
-        "default": false
-      },
-      "output_format": {
-        "type": "string",
-        "default": "jpg",
-        "enum": [
-          "jpg",
-          "jpeg",
-          "png",
-          "webp"
-        ]
-      },
-      "output_quality": {
-        "type": "integer",
-        "default": 80,
-        "minimum": 0,
-        "maximum": 100
-      },
-      "prompt": {
-        "type": "string",
-        "required": true
-      },
-      "width": {
-        "type": "integer",
-        "required": true,
-        "minimum": 64,
-        "maximum": 2048
-      },
-      "height": {
-        "type": "integer",
-        "required": true,
-        "minimum": 64,
-        "maximum": 2048
-      }
-    }
-  }
-}

package/src/steps/textToImageAdapters.js

@@ -1,87 +0,0 @@
-import { MODELS } from '../config/models.js';
-
-function normalizeModelOptions(candidate) {
-  if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) {
-    return {};
-  }
-  return candidate;
-}
-
-function buildCommonPrompt(promptText, tone, index) {
-  return `Cinematic documentary style, coherent character continuity, shot ${index + 1}, tone ${tone}. ${promptText}`;
-}
-
-function buildPrunaInput({ promptText, tone, index, width, height, modelOptions }) {
-  return {
-    ...normalizeModelOptions(modelOptions),
-    prompt: buildCommonPrompt(promptText, tone, index),
-    width,
-    height
-  };
-}
-
-function buildFluxInput({ promptText, tone, index, width, height, modelOptions }) {
-  return {
-    ...normalizeModelOptions(modelOptions),
-    prompt: buildCommonPrompt(promptText, tone, index),
-    aspect_ratio: 'custom',
-    width,
-    height
-  };
-}
-
-function buildFluxSchnellInput({ promptText, tone, index, aspectRatio, modelOptions }) {
-  return {
-    ...normalizeModelOptions(modelOptions),
-    prompt: buildCommonPrompt(promptText, tone, index),
-    aspect_ratio: aspectRatio
-  };
-}
-
-function buildNanoBananaProInput({ promptText, tone, index, aspectRatio, modelOptions }) {
-  return {
-    ...normalizeModelOptions(modelOptions),
-    prompt: buildCommonPrompt(promptText, tone, index),
-    aspect_ratio: aspectRatio
-  };
-}
-
-function buildSeedream4Input({ promptText, tone, index, aspectRatio, modelOptions }) {
-  return {
-    ...normalizeModelOptions(modelOptions),
-    prompt: buildCommonPrompt(promptText, tone, index),
-    aspect_ratio: aspectRatio
-  };
-}
-
-const TEXT_TO_IMAGE_ADAPTERS = {
-  [MODELS.keyframe]: {
-    modelId: MODELS.keyframe,
-    buildInput: buildPrunaInput
-  },
-  [MODELS.flux]: {
-    modelId: MODELS.flux,
-    buildInput: buildFluxInput
-  },
-  [MODELS.fluxSchnell]: {
-    modelId: MODELS.fluxSchnell,
-    buildInput: buildFluxSchnellInput
-  },
-  [MODELS.nanoBananaPro]: {
-    modelId: MODELS.nanoBananaPro,
-    buildInput: buildNanoBananaProInput
-  },
-  [MODELS.seedream4]: {
-    modelId: MODELS.seedream4,
-    buildInput: buildSeedream4Input
-  }
-};
-
-const DEFAULT_TEXT_TO_IMAGE_ADAPTER = {
-  modelId: null,
-  buildInput: buildPrunaInput
-};
-
-export function resolveTextToImageAdapter(modelId) {
-  return TEXT_TO_IMAGE_ADAPTERS[modelId] || DEFAULT_TEXT_TO_IMAGE_ADAPTER;
-}