Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

feat: render Runway stills with tagged canon references (#13105)

Adam Eivy3371b723ca9e
diff --git a/client/src/components/fableloom/LoomProductionPanel.jsx b/client/src/components/fableloom/LoomProductionPanel.jsx
index 6a73039a8a..fc62199aa8 100644
--- a/client/src/components/fableloom/LoomProductionPanel.jsx
+++ b/client/src/components/fableloom/LoomProductionPanel.jsx
@@ -49,6 +49,7 @@ const IMAGE_BACKENDS = [
{ id: 'codex', label: 'Codex', icon: Cloud },
{ id: 'grok', label: 'Grok', icon: Cloud },
{ id: 'agy', label: 'Agy', icon: Sparkles },
+ { id: 'runway', label: 'Runway', icon: Cloud },
];
const VIDEO_BACKENDS = [
diff --git a/client/src/components/fableloom/LoomSettingsDrawer.jsx b/client/src/components/fableloom/LoomSettingsDrawer.jsx
index 46251ddfce..c30e01ec1e 100644
--- a/client/src/components/fableloom/LoomSettingsDrawer.jsx
+++ b/client/src/components/fableloom/LoomSettingsDrawer.jsx
@@ -48,6 +48,7 @@ const IMAGE_RENDER_BACKENDS = [
{ id: 'codex', label: 'Codex', icon: Cloud },
{ id: 'grok', label: 'Grok', icon: Cloud },
{ id: 'agy', label: 'Agy', icon: Sparkles },
+ { id: 'runway', label: 'Runway', icon: Cloud },
];
const VIDEO_RENDER_BACKENDS = [
diff --git a/client/src/components/imageGen/ImageGenFormEditor.jsx b/client/src/components/imageGen/ImageGenFormEditor.jsx
index af5b70956d..5dbdeb7c35 100644
--- a/client/src/components/imageGen/ImageGenFormEditor.jsx
+++ b/client/src/components/imageGen/ImageGenFormEditor.jsx
@@ -17,6 +17,7 @@ import LoraPicker from './LoraPicker';
import ReferenceImagePicker from './ReferenceImagePicker';
import { appendTriggerWords } from '../../lib/loraTriggers';
import {
+ RUNWAY_IMAGE_MODELS, RUNWAY_IMAGE_DEFAULT_MODEL,
AGY_IMAGEGEN_DEFAULT_MODEL, FAL_IMAGE_DEFAULT_MODEL, FAL_IMAGE_MODEL_OPTIONS, IMAGE_GEN_MODE, falImageFamily,
} from '../../lib/imageGenBackends';
@@ -41,7 +42,7 @@ export default function ImageGenFormEditor({ form, backend, generation }) {
effectiveMode,
isLocalMode,
isAgyMode,
- isFalMode,
+ isFalMode, isRunwayMode, effectiveRunwayModel,
remoteTarget,
effectiveAgyModel,
effectiveFalModel,
@@ -240,11 +241,11 @@ export default function ImageGenFormEditor({ form, backend, generation }) {
modelStatus={isLocalMode ? modelDownload.getStatus(fields.modelId) : null}
onModelDownload={isLocalMode ? modelDownload.start : undefined}
onModelDownloadCancel={modelDownload.cancel}
- cloudModels={isAgyMode ? backend.agy.models : isFalMode ? FAL_IMAGE_MODEL_OPTIONS : []}
- cloudModel={isFalMode ? effectiveFalModel : effectiveAgyModel}
- onCloudModelChange={isFalMode ? fields.setFalModel : fields.setAgyModel}
- cloudModelLabel={isFalMode ? 'fal.ai model' : 'Agent model'}
- cloudModelDefaultLabel={isFalMode
+ cloudModels={isAgyMode ? backend.agy.models : isFalMode ? FAL_IMAGE_MODEL_OPTIONS : isRunwayMode ? RUNWAY_IMAGE_MODELS : []}
+ cloudModel={isRunwayMode ? effectiveRunwayModel : isFalMode ? effectiveFalModel : effectiveAgyModel}
+ onCloudModelChange={isRunwayMode ? fields.setRunwayModel : isFalMode ? fields.setFalModel : fields.setAgyModel}
+ cloudModelLabel={isRunwayMode ? 'Runway model' : isFalMode ? 'fal.ai model' : 'Agent model'}
+ cloudModelDefaultLabel={isRunwayMode ? settings.savedRunwayModel || RUNWAY_IMAGE_DEFAULT_MODEL : isFalMode
? falImageFamily(settings.savedFalModel || FAL_IMAGE_DEFAULT_MODEL)?.label || FAL_IMAGE_DEFAULT_MODEL
: settings.savedAgyModel || AGY_IMAGEGEN_DEFAULT_MODEL}
/>
diff --git a/client/src/components/imageGen/ImageGenHeader.jsx b/client/src/components/imageGen/ImageGenHeader.jsx
index 20a2340c12..620c13d360 100644
--- a/client/src/components/imageGen/ImageGenHeader.jsx
+++ b/client/src/components/imageGen/ImageGenHeader.jsx
@@ -13,6 +13,7 @@ const CONNECTED_MODE_LABELS = {
[IMAGE_GEN_MODE.GROK]: 'grok CLI',
[IMAGE_GEN_MODE.AGY]: 'agy CLI',
[IMAGE_GEN_MODE.FAL]: 'fal.ai',
+ [IMAGE_GEN_MODE.RUNWAY]: 'Runway',
};
export default function ImageGenHeader({ status, backends, remix, actions }) {
diff --git a/client/src/components/imageGen/RecordRenderPinRow.jsx b/client/src/components/imageGen/RecordRenderPinRow.jsx
index ff5e7e3fa1..89486f422c 100644
--- a/client/src/components/imageGen/RecordRenderPinRow.jsx
+++ b/client/src/components/imageGen/RecordRenderPinRow.jsx
@@ -1,3 +1,4 @@
+import RunwayModelSelect from './RunwayModelSelect';
import ModelSelect from '../ModelSelect';
import FalModelSelect from './FalModelSelect';
import {
@@ -7,7 +8,7 @@ import {
import useFieldDraft from '../../hooks/useFieldDraft';
import useLocalImageModels from '../../hooks/useLocalImageModels';
-const DEFAULT_MODES = [IMAGE_GEN_MODE.LOCAL, IMAGE_GEN_MODE.CODEX, IMAGE_GEN_MODE.GROK, IMAGE_GEN_MODE.AGY, IMAGE_GEN_MODE.FAL];
+const DEFAULT_MODES = [IMAGE_GEN_MODE.LOCAL, IMAGE_GEN_MODE.CODEX, IMAGE_GEN_MODE.GROK, IMAGE_GEN_MODE.AGY, IMAGE_GEN_MODE.FAL, IMAGE_GEN_MODE.RUNWAY];
const FIELD = 'w-full max-w-full bg-port-bg border border-port-border rounded-lg px-2 py-2 text-sm text-white focus:outline-none focus:border-port-accent';
// Per-record render pin editor (#3231 Phase 3) — one row pinning a record's
@@ -72,6 +73,14 @@ export default function RecordRenderPinRow({
value={imageModelId}
onChange={(modelId) => onChange({ imageMode: pinnedMode, imageModelId: modelId })}
/>
+ ) : pinnedMode === IMAGE_GEN_MODE.RUNWAY ? (
+ <RunwayModelSelect
+ id={`${idPrefix}-model`}
+ aria-label={`${label} model`}
+ value={imageModelId}
+ onChange={(v) => onChange({ imageMode: pinnedMode, imageModelId: v })}
+ className={`${FIELD} sm:w-52`}
+ />
) : pinnedMode === IMAGE_GEN_MODE.FAL ? (
<FalModelSelect
id={`${idPrefix}-model`}
diff --git a/client/src/components/imageGen/RunwayModelSelect.jsx b/client/src/components/imageGen/RunwayModelSelect.jsx
new file mode 100644
index 0000000000..a2ab27c33b
--- /dev/null
+++ b/client/src/components/imageGen/RunwayModelSelect.jsx
@@ -0,0 +1,14 @@
+import { RUNWAY_IMAGE_MODELS } from '../../lib/imageGenBackends';
+
+export default function RunwayModelSelect({ value, onChange, ...props }) {
+ return (
+ <select {...props} value={value || ''} onChange={(e) => onChange(e.target.value || null)}>
+ <option value="">Runway default (Settings)</option>
+ {RUNWAY_IMAGE_MODELS.map((model) => (
+ <option key={model.id} value={model.id}>
+ {model.label}{model.minReferences ? ' (requires reference)' : ''}
+ </option>
+ ))}
+ </select>
+ );
+}
diff --git a/client/src/components/settings/ImageGenBackendSections.jsx b/client/src/components/settings/ImageGenBackendSections.jsx
index 89a41cb5ca..e9a3ed0581 100644
--- a/client/src/components/settings/ImageGenBackendSections.jsx
+++ b/client/src/components/settings/ImageGenBackendSections.jsx
@@ -1,3 +1,4 @@
+import RunwayModelSelect from '../imageGen/RunwayModelSelect';
/**
* Media settings — the install-wide routing sections: the Backend tile
* picker and the Defaults tab (default video backend, display sleep, the
@@ -24,6 +25,7 @@ const BACKEND_TILES = [
{ mode: IMAGE_GEN_MODE.CODEX, icon: Terminal, label: 'Codex CLI', blurb: 'Route through the Codex CLI built-in image_gen tool. Counts against your Codex plan.', enabledKey: 'codexEnabled' },
{ mode: IMAGE_GEN_MODE.GROK, icon: Sparkles, label: 'Grok CLI', blurb: 'Route through the Grok Build CLI built-in image_gen tool. Counts against your Grok plan.', enabledKey: 'grokEnabled' },
{ mode: IMAGE_GEN_MODE.AGY, icon: Terminal, label: 'Agy CLI', blurb: "Text-to-image through Antigravity's generate_image tool and your selected model.", enabledKey: 'agyEnabled' },
+ { mode: IMAGE_GEN_MODE.RUNWAY, icon: Cloud, label: 'Runway', blurb: 'Hosted Gen-4 stills with up to three tagged references. Billed per image.', enabledKey: 'runwayEnabled' },
{ mode: IMAGE_GEN_MODE.FAL, icon: Sparkles, label: 'fal.ai', blurb: "Hosted image and reference-edit models through fal.ai's API. Billed per image to your fal.ai account.", enabledKey: 'falEnabled' },
];
@@ -236,12 +238,21 @@ export default function ImageGenBackendSections({ mediaTab, form, credentials })
className={`${SELECT_CLASS} sm:w-44`}
>
<option value="">Auto (install default)</option>
- {[IMAGE_GEN_MODE.LOCAL, IMAGE_GEN_MODE.CODEX, IMAGE_GEN_MODE.GROK, IMAGE_GEN_MODE.AGY, IMAGE_GEN_MODE.FAL].map((m) => (
+ {[IMAGE_GEN_MODE.LOCAL, IMAGE_GEN_MODE.CODEX, IMAGE_GEN_MODE.GROK, IMAGE_GEN_MODE.AGY, IMAGE_GEN_MODE.FAL, IMAGE_GEN_MODE.RUNWAY].map((m) => (
<option key={m} value={m}>{modeLabel(m)}</option>
))}
</select>
</FormField>
- {pinnedMode === IMAGE_GEN_MODE.FAL ? (
+ {pinnedMode === IMAGE_GEN_MODE.RUNWAY ? (
+ <FormField label={`${label} model`} labelClassName="sr-only" className="contents">
+ <RunwayModelSelect
+ id={modelInputId}
+ value={entry.imageModel}
+ onChange={(v) => setPin('imageModel', v)}
+ className={`${SELECT_CLASS} sm:w-52`}
+ />
+ </FormField>
+ ) : pinnedMode === IMAGE_GEN_MODE.FAL ? (
<FormField label={`${label} model`} labelClassName="sr-only" className="contents">
<FalModelSelect
id={modelInputId}
diff --git a/client/src/components/settings/ImageGenProviderSections.jsx b/client/src/components/settings/ImageGenProviderSections.jsx
index f1b66e6b98..3eff144187 100644
--- a/client/src/components/settings/ImageGenProviderSections.jsx
+++ b/client/src/components/settings/ImageGenProviderSections.jsx
@@ -25,7 +25,7 @@ import { getVideoGenModelContext, getProviders } from '../../services/api';
import {
isLocalImageConfigured, IMAGE_GEN_MODE, FAL_IMAGE_DEFAULT_MODEL, falImageFamily,
AGY_IMAGEGEN_DEFAULT_MODEL, AGY_IMAGEGEN_IMAGE_MODEL, CODEX_IMAGEGEN_DEFAULT_EFFORT, CODEX_IMAGEGEN_DEFAULT_MODEL,
- GROK_ASPECT_RATIOS, localModelSelectOptions,
+ GROK_ASPECT_RATIOS, localModelSelectOptions, RUNWAY_IMAGE_MODELS, RUNWAY_IMAGE_DISCLOSURE,
} from '../../lib/imageGenBackends';
import { withUnlistedOption } from '../../lib/withUnlistedOption';
import { effortLevelsForProvider, isCodexSubscriptionProvider, providerModelList } from '../../utils/providers';
@@ -53,7 +53,7 @@ const INPUT_CLASS = 'w-full bg-port-bg border border-port-border rounded-lg px-3
const SECTION_CLASS = 'bg-port-card border border-port-border rounded-xl p-6 space-y-4';
const FIELD_LABEL_CLASS = 'block text-xs font-medium text-gray-400 mb-1';
-export default function ImageGenProviderSections({ mediaTab, setMediaTab, form, parallelBounds, falCredential, localRuntime, onStatusRecheck }) {
+export default function ImageGenProviderSections({ mediaTab, setMediaTab, form, parallelBounds, falCredential, runwayCredential, localRuntime, onStatusRecheck }) {
const { values, set } = form;
const {
mode, sdapiUrl, pythonPath, localModelId, localVideoModelId,
@@ -522,6 +522,24 @@ export default function ImageGenProviderSections({ mediaTab, setMediaTab, form,
</div>
)}
+ {mediaTab === 'runway' && (
+ <div className={SECTION_CLASS}>
+ <h2 className="text-lg font-semibold text-white">Runway Imagegen</h2>
+ <p className="text-xs text-gray-400">Uses the Runway credential from <a href="/settings/credentials" className="text-port-accent hover:underline">Settings → Credentials</a>, shared with video generation.</p>
+ <p className="text-xs text-gray-400">{runwayCredential == null ? 'Checking credential…' : runwayCredential.configured ? 'Runway credential configured.' : 'Add a Runway credential to render.'}</p>
+ <p className="text-xs text-gray-400">{RUNWAY_IMAGE_DISCLOSURE.summary} <a href={RUNWAY_IMAGE_DISCLOSURE.termsUrl} target="_blank" rel="noreferrer" className="text-port-accent hover:underline">Runway’s terms</a> and moderation apply. {RUNWAY_IMAGE_DISCLOSURE.billing}</p>
+ <label className="flex items-center gap-3 cursor-pointer"><input type="checkbox" checked={values.runwayEnabled} onChange={toggleProvider('runwayEnabled', IMAGE_GEN_MODE.RUNWAY)} /><span>Enable Runway Imagegen</span></label>
+ <FormField label="Default model" labelClassName={FIELD_LABEL_CLASS}>
+ <select value={values.runwayModel} onChange={(e) => set('runwayModel', e.target.value)} className={INPUT_CLASS}>
+ {RUNWAY_IMAGE_MODELS.map((model) => <option key={model.id} value={model.id}>{model.label}{model.minReferences ? ' (requires a reference)' : ''}</option>)}
+ </select>
+ </FormField>
+ <FormField label="Resolution" labelClassName={FIELD_LABEL_CLASS}>
+ <select value={values.runwayResolution} onChange={(e) => set('runwayResolution', e.target.value)} className={INPUT_CLASS}><option value="720p">720p · Gen-4: 5 credits / Turbo: 2 credits</option><option value="1080p">1080p · Gen-4: 8 credits / Turbo: 2 credits</option></select>
+ </FormField>
+ <CleanersToggles mode={IMAGE_GEN_MODE.RUNWAY} form={form} />
+ </div>
+ )}
{mediaTab === 'fal' && (
<div className={SECTION_CLASS}>
<div className="flex items-center gap-2 text-white">
diff --git a/client/src/components/settings/ImageGenTab.jsx b/client/src/components/settings/ImageGenTab.jsx
index 33f8583242..f3470fb3b3 100644
--- a/client/src/components/settings/ImageGenTab.jsx
+++ b/client/src/components/settings/ImageGenTab.jsx
@@ -65,6 +65,7 @@ export const MEDIA_TABS = [
{ id: 'codex', label: 'Codex CLI', icon: Terminal, probeMode: IMAGE_GEN_MODE.CODEX },
{ id: 'grok', label: 'Grok CLI', icon: Zap, probeMode: IMAGE_GEN_MODE.GROK },
{ id: 'agy', label: 'Agy CLI', icon: Bot, probeMode: IMAGE_GEN_MODE.AGY },
+ { id: 'runway', label: 'Runway', icon: Sparkles, probeMode: IMAGE_GEN_MODE.RUNWAY },
{ id: 'fal', label: 'fal.ai', icon: Sparkles, probeMode: IMAGE_GEN_MODE.FAL },
{ id: 'tokens', label: 'Tokens', icon: Key },
{ id: 'expose', label: 'Expose', icon: Globe },
@@ -102,12 +103,15 @@ const EMPTY_MEDIA_FORM = Object.freeze({
// fal.ai image backend — a metered API, gated by its own toggle like the
// CLIs. The API key is NOT part of this slice: it is the fal.ai credential
// the video backend already owns (the Defaults tab's key row).
+ runwayEnabled: false,
+ runwayModel: 'gen4_image',
+ runwayResolution: '720p',
falEnabled: false,
// '' = no pin → FAL_IMAGE_DEFAULT_MODEL server-side.
falModel: '',
// Per-provider cleaner toggles (see CleanersToggles in the provider sections).
- cleanC2PAByMode: { external: true, local: true, codex: true, grok: false, agy: false, fal: false },
- denoiseByMode: { external: false, local: false, codex: false, grok: false, agy: false, fal: false },
+ cleanC2PAByMode: { external: true, local: true, codex: true, grok: false, agy: false, fal: false, runway: false },
+ denoiseByMode: { external: false, local: false, codex: false, grok: false, agy: false, fal: false, runway: false },
// Per-surface render defaults (#3231) — `{ [target]: { imageMode, imageModel, videoMode } }`.
renderDefaults: {},
// Install-wide video backend pin (`settings.videoGen.mode`, #3231 Phase 4). '' = no pin (local).
@@ -131,7 +135,7 @@ const mediaFormFromSettings = (s) => {
// Per-mode cleaner reads via the shared helper (mirrored from server/lib/imageClean.js).
const cleaners = Object.fromEntries([
[IMAGE_GEN_MODE.EXTERNAL, ig.external], [IMAGE_GEN_MODE.LOCAL, ig.local], [IMAGE_GEN_MODE.CODEX, cx],
- [IMAGE_GEN_MODE.GROK, gk], [IMAGE_GEN_MODE.AGY, ay], [IMAGE_GEN_MODE.FAL, fl],
+ [IMAGE_GEN_MODE.GROK, gk], [IMAGE_GEN_MODE.AGY, ay], [IMAGE_GEN_MODE.FAL, fl], [IMAGE_GEN_MODE.RUNWAY, ig.runway],
].map(([m, config]) => [m, resolveCleanersFromConfig(config, m)]));
const values = {
mode: ig.mode || IMAGE_GEN_MODE.EXTERNAL,
@@ -150,6 +154,9 @@ const mediaFormFromSettings = (s) => {
agyEnabled: ay.enabled === true,
agyPath: ay.agyPath || '',
agyModel: ay.model || '',
+ runwayEnabled: ig.runway?.enabled === true,
+ runwayModel: ig.runway?.model || 'gen4_image',
+ runwayResolution: ig.runway?.resolution || '720p',
falEnabled: fl.enabled === true,
falModel: fl.model || '',
cleanC2PAByMode: Object.fromEntries(Object.entries(cleaners).map(([m, c]) => [m, c.cleanC2PA])),
@@ -222,6 +229,10 @@ const sliceFieldsOf = (f) => ({
enabled: f.agyEnabled, agyPath: f.agyPath, model: f.agyModel,
cleanC2PA: f.cleanC2PAByMode.agy, denoise: f.denoiseByMode.agy,
},
+ 'imageGen.runway': {
+ enabled: f.runwayEnabled, model: f.runwayModel, resolution: f.runwayResolution,
+ cleanC2PA: f.cleanC2PAByMode.runway, denoise: f.denoiseByMode.runway,
+ },
'imageGen.fal': {
enabled: f.falEnabled, model: falImageFamily(f.falModel) ? f.falModel : '',
cleanC2PA: f.cleanC2PAByMode.fal, denoise: f.denoiseByMode.fal,
@@ -489,6 +500,7 @@ export function ImageGenTab() {
setMediaTab={setMediaTab}
form={form}
parallelBounds={parallelBounds}
+ runwayCredential={credentialRows.runway}
falCredential={credentialRows.fal}
localRuntime={localRuntime}
onStatusRecheck={checkStatus}
diff --git a/client/src/components/settings/ImageGenTab.test.jsx b/client/src/components/settings/ImageGenTab.test.jsx
index 9b3b900c10..4ca3427d24 100644
--- a/client/src/components/settings/ImageGenTab.test.jsx
+++ b/client/src/components/settings/ImageGenTab.test.jsx
@@ -98,6 +98,19 @@ beforeEach(() => {
});
describe('ImageGenTab grouped tabs', () => {
+ // Catches persisting a second key or dropping Runway's enable/model/resolution slice.
+ it('configures Runway images with the shared credential and persists its own rendering settings', async () => {
+ await renderTab(['/media/image?mediaTab=runway']);
+ expect(screen.getByRole('heading', { name: 'Runway Imagegen' })).toBeTruthy();
+ expect(screen.getByRole('link', { name: 'Settings → Credentials' }).getAttribute('href')).toBe('/settings/credentials');
+ expect(screen.queryByPlaceholderText('key_...')).toBeNull();
+ fireEvent.click(screen.getByRole('checkbox', { name: 'Enable Runway Imagegen' }));
+ fireEvent.change(screen.getByLabelText('Default model'), { target: { value: 'gen4_image_turbo' } });
+ fireEvent.change(screen.getByLabelText('Resolution'), { target: { value: '1080p' } });
+ fireEvent.click(screen.getByRole('button', { name: 'Save' }));
+ await waitFor(() => expect(patchSettingsSlice).toHaveBeenCalledWith('imageGen.runway', expect.objectContaining({ enabled: true, model: 'gen4_image_turbo', resolution: '1080p' }), expect.anything()));
+ });
+
it.each([undefined, { min: 1, max: Number.MAX_SAFE_INTEGER, default: 1 }])(
'loads and saves render limits above ten with bounds %j', async (parallelLimitBounds) => {
getSettings.mockResolvedValue({
diff --git a/client/src/hooks/useImageGenForm.js b/client/src/hooks/useImageGenForm.js
index 476acb1f07..b9bb310f2b 100644
--- a/client/src/hooks/useImageGenForm.js
+++ b/client/src/hooks/useImageGenForm.js
@@ -6,7 +6,7 @@ import { composeStyledPrompt } from '../lib/composeStyledPrompt';
import { universeStylePreset, withUniverseLabel } from '../lib/universeStylePreset';
import { RUNNER_FAMILIES, loraCompatKey, loraCompatKeysMatch, loraFamilyOf, usesDiffusersRunner } from '../lib/runnerFamilies';
import {
- FAL_IMAGE_DEFAULT_MODEL,
+ FAL_IMAGE_DEFAULT_MODEL, RUNWAY_IMAGE_DEFAULT_MODEL,
IMAGE_GEN_MODE,
LOCAL_IMAGEGEN_DEFAULT_MODEL,
cloudPromptRequired,
@@ -98,6 +98,8 @@ export function useImageGenForm({ searchParams, setSearchParams, backend }) {
const [savedAgyModel, setSavedAgyModel] = useState('');
// Per-render fal.ai model ('' = the Settings default) and that default, for
// the picker's "Settings default (…)" row.
+ const [runwayModel, setRunwayModel] = useState('');
+ const [savedRunwayModel, setSavedRunwayModel] = useState('');
const [falModel, setFalModel] = useState('');
const [savedFalModel, setSavedFalModel] = useState('');
const [savedLocalModelId, setSavedLocalModelId] = useState(null);
@@ -134,6 +136,7 @@ export function useImageGenForm({ searchParams, setSearchParams, backend }) {
codex: resolveCleanersFromConfig(settings?.imageGen?.codex, IMAGE_GEN_MODE.CODEX),
grok: resolveCleanersFromConfig(settings?.imageGen?.grok, IMAGE_GEN_MODE.GROK),
agy: resolveCleanersFromConfig(settings?.imageGen?.agy, IMAGE_GEN_MODE.AGY),
+ runway: resolveCleanersFromConfig(settings?.imageGen?.runway, IMAGE_GEN_MODE.RUNWAY),
fal: resolveCleanersFromConfig(settings?.imageGen?.fal, IMAGE_GEN_MODE.FAL),
};
const c2 = {
@@ -142,6 +145,7 @@ export function useImageGenForm({ searchParams, setSearchParams, backend }) {
codex: perMode.codex.cleanC2PA,
grok: perMode.grok.cleanC2PA,
agy: perMode.agy.cleanC2PA,
+ runway: perMode.runway.cleanC2PA,
fal: perMode.fal.cleanC2PA,
};
const dn = {
@@ -150,11 +154,13 @@ export function useImageGenForm({ searchParams, setSearchParams, backend }) {
codex: perMode.codex.denoise,
grok: perMode.grok.denoise,
agy: perMode.agy.denoise,
+ runway: perMode.runway.denoise,
fal: perMode.fal.denoise,
};
const saved = settings?.imageGen?.mode || IMAGE_GEN_MODE.EXTERNAL;
const next = configureBackends(backends, saved);
setSavedAgyModel(settings?.imageGen?.agy?.model || '');
+ setSavedRunwayModel(settings?.imageGen?.runway?.model || RUNWAY_IMAGE_DEFAULT_MODEL);
setSavedFalModel(settings?.imageGen?.fal?.model || '');
setSavedLocalModelId(settings?.imageGen?.local?.modelId || '');
setSavedCleanC2PAByMode(c2);
@@ -686,6 +692,7 @@ export function useImageGenForm({ searchParams, setSearchParams, backend }) {
setSelectedLoras,
agyModel,
setAgyModel,
+ runwayModel, setRunwayModel,
falModel,
setFalModel,
batchCount,
@@ -707,6 +714,7 @@ export function useImageGenForm({ searchParams, setSearchParams, backend }) {
},
settings: {
savedAgyModel,
+ savedRunwayModel,
savedFalModel,
savedCleanC2PAByMode,
savedDenoiseByMode,
diff --git a/client/src/hooks/useImageGenPageRuntime.js b/client/src/hooks/useImageGenPageRuntime.js
index 0effc93e4d..43547dba88 100644
--- a/client/src/hooks/useImageGenPageRuntime.js
+++ b/client/src/hooks/useImageGenPageRuntime.js
@@ -2,7 +2,7 @@ import { useCallback, useEffect, useRef, useState } from 'react';
import { useNavigate, useSearchParams } from 'react-router';
import { composeStyledPrompt, stylePromptAdditions } from '../lib/composeStyledPrompt';
import {
- FAL_IMAGE_MODEL_IDS,
+ FAL_IMAGE_MODEL_IDS, RUNWAY_IMAGE_MODEL_IDS,
IMAGE_GEN_MODE,
isCloudCliMode,
modeLabel,
@@ -68,6 +68,7 @@ function useImageGenBackendRuntime() {
const isCloudMode = isCloudCliMode(effectiveMode);
const cloudModeLabel = modeLabel(effectiveMode);
const isAgyMode = effectiveMode === IMAGE_GEN_MODE.AGY;
+ const isRunwayMode = effectiveMode === IMAGE_GEN_MODE.RUNWAY;
const isFalMode = effectiveMode === IMAGE_GEN_MODE.FAL;
const remoteTarget = useFederatedMediaTarget('image');
const remoteTargetActive = effectiveMode !== IMAGE_GEN_MODE.GROK && remoteTarget.isRemote;
@@ -111,6 +112,7 @@ function useImageGenBackendRuntime() {
isCloudMode,
cloudModeLabel,
isAgyMode,
+ isRunwayMode,
isFalMode,
remoteTarget,
remoteTargetActive,
@@ -165,7 +167,8 @@ export function useImageGenPageRuntime() {
const effectiveAgyModel = backend.agy.models.includes(fields.agyModel) ? fields.agyModel : '';
// Only a catalog id is ever sent — the server refuses anything else.
const effectiveFalModel = FAL_IMAGE_MODEL_IDS.includes(fields.falModel) ? fields.falModel : '';
- const effectiveCloudModel = backend.isAgyMode ? effectiveAgyModel : backend.isFalMode ? effectiveFalModel : '';
+ const effectiveRunwayModel = RUNWAY_IMAGE_MODEL_IDS.includes(fields.runwayModel) ? fields.runwayModel : '';
+ const effectiveCloudModel = backend.isAgyMode ? effectiveAgyModel : backend.isFalMode ? effectiveFalModel : backend.isRunwayMode ? effectiveRunwayModel : '';
useEffect(() => {
if (!effectiveMode) return;
@@ -540,7 +543,7 @@ export function useImageGenPageRuntime() {
return {
form,
- backend: { ...backend, effectiveAgyModel, effectiveFalModel },
+ backend: { ...backend, effectiveAgyModel, effectiveFalModel, effectiveRunwayModel },
generation: {
handleGenerate,
handleCancel,
diff --git a/client/src/lib/imageGenBackends.js b/client/src/lib/imageGenBackends.js
index 04538bbc17..7205dba8e7 100644
--- a/client/src/lib/imageGenBackends.js
+++ b/client/src/lib/imageGenBackends.js
@@ -17,6 +17,7 @@ const MODE_ICONS = {
[IMAGE_GEN_MODE.GROK]: Sparkles,
[IMAGE_GEN_MODE.AGY]: Sparkles,
[IMAGE_GEN_MODE.FAL]: Zap,
+ [IMAGE_GEN_MODE.RUNWAY]: Cloud,
[IMAGE_GEN_MODE.EXTERNAL]: Cloud,
};
@@ -47,6 +48,8 @@ export function deriveAvailableBackends(settings, { excludeExternal = false } =
out.push({ id: IMAGE_GEN_MODE.GROK, ...metaFor(IMAGE_GEN_MODE.GROK) });
if (ig.agy?.enabled === true)
out.push({ id: IMAGE_GEN_MODE.AGY, ...metaFor(IMAGE_GEN_MODE.AGY) });
+ if (ig.runway?.enabled === true)
+ out.push({ id: IMAGE_GEN_MODE.RUNWAY, ...metaFor(IMAGE_GEN_MODE.RUNWAY) });
if (ig.fal?.enabled === true)
out.push({ id: IMAGE_GEN_MODE.FAL, ...metaFor(IMAGE_GEN_MODE.FAL) });
if (!excludeExternal && (ig.external?.sdapiUrl || ig.sdapiUrl || '').trim())
diff --git a/client/src/lib/imageGenBackends.test.js b/client/src/lib/imageGenBackends.test.js
index 43f0e896f1..039c7b481d 100644
--- a/client/src/lib/imageGenBackends.test.js
+++ b/client/src/lib/imageGenBackends.test.js
@@ -27,7 +27,7 @@ describe('imageGenReadiness', () => {
describe('I2I_CAPABLE_MODES / isI2iCapableMode', () => {
it('treats every generation backend as i2i-capable, but not external', () => {
expect(I2I_CAPABLE_MODES).toEqual([
- IMAGE_GEN_MODE.LOCAL, IMAGE_GEN_MODE.CODEX, IMAGE_GEN_MODE.GROK, IMAGE_GEN_MODE.AGY, IMAGE_GEN_MODE.FAL,
+ IMAGE_GEN_MODE.LOCAL, IMAGE_GEN_MODE.CODEX, IMAGE_GEN_MODE.GROK, IMAGE_GEN_MODE.AGY, IMAGE_GEN_MODE.FAL, IMAGE_GEN_MODE.RUNWAY,
]);
expect(isI2iCapableMode(IMAGE_GEN_MODE.LOCAL)).toBe(true);
expect(isI2iCapableMode(IMAGE_GEN_MODE.CODEX)).toBe(true);
diff --git a/client/src/lib/imageGenModes.js b/client/src/lib/imageGenModes.js
index 522358edf1..16508759a2 100644
--- a/client/src/lib/imageGenModes.js
+++ b/client/src/lib/imageGenModes.js
@@ -187,6 +187,8 @@ export const MODE_LABELS = Object.freeze({
// text-to-image endpoint (the provider switches to the family's /edit endpoint
// on its own whenever a render carries input images), labeled with its price
// because each choice is a different cost per image.
+export { RUNWAY_IMAGE_DISCLOSURE, RUNWAY_IMAGE_MODELS, RUNWAY_IMAGE_DEFAULT_MODEL, RUNWAY_IMAGE_MODEL_IDS, getRunwayImageModel } from '../../../server/lib/runwayImageModels.js';
+
export const FAL_IMAGE_MODEL_OPTIONS = Object.freeze(FAL_IMAGE_FAMILIES.map((family) => Object.freeze({
id: family.textEndpoint,
label: `${family.label} (${falImagePriceLabel(family)}, up to ${family.maxInputImages} refs)`,
diff --git a/server/lib/credentialRegistry.js b/server/lib/credentialRegistry.js
index 0a77181b76..3ceee89bb6 100644
--- a/server/lib/credentialRegistry.js
+++ b/server/lib/credentialRegistry.js
@@ -46,7 +46,7 @@ export const CREDENTIALS = Object.freeze([
}),
Object.freeze({
id: 'runway', label: 'Runway', privateStore: true,
- unlocks: 'Video generation through Runway\'s developer API.', tier: 'metered',
+ unlocks: 'Image and video generation through Runway\'s developer API.', tier: 'metered',
getUrl: 'https://dev.runwayml.com/', envVars: Object.freeze(['RUNWAYML_API_SECRET']),
settingsPath: 'videoGen.runway.apiKey', configurePath: '/settings/credentials',
}),
diff --git a/server/lib/generationModes.js b/server/lib/generationModes.js
index b5b4b672ec..2697abb7ec 100644
--- a/server/lib/generationModes.js
+++ b/server/lib/generationModes.js
@@ -15,6 +15,7 @@ export const IMAGE_GEN_MODE = Object.freeze({
// fal.ai's metered queue REST API (services/imageGen/fal.js) — the same
// literal as VIDEO_GEN_MODE.FAL below: one provider, one key, one id.
FAL: 'fal',
+ RUNWAY: 'runway',
});
export const IMAGE_GEN_MODES = Object.freeze(Object.values(IMAGE_GEN_MODE));
@@ -27,6 +28,7 @@ export const CLOUD_IMAGE_GEN_MODES = Object.freeze([
IMAGE_GEN_MODE.GROK,
IMAGE_GEN_MODE.AGY,
IMAGE_GEN_MODE.FAL,
+ IMAGE_GEN_MODE.RUNWAY,
]);
// The external SD-API backend remains synchronous; every other image backend
@@ -38,15 +40,14 @@ export const QUEUEABLE_IMAGE_MODES = Object.freeze([
// Video deliberately shares the image backend discriminator namespace. Local
// video's text/image/fflf modes are a separate semantic value carried elsewhere.
-// REACTOR and RUNWAY have no image-gen counterpart, so they are video-only
-// literals rather than re-exports of an IMAGE_GEN_MODE entry.
+// REACTOR has no image-gen counterpart.
export const VIDEO_GEN_MODE = Object.freeze({
LOCAL: IMAGE_GEN_MODE.LOCAL,
GROK: IMAGE_GEN_MODE.GROK,
FAL: IMAGE_GEN_MODE.FAL,
REACTOR: 'reactor',
// Runway's developer API (services/videoGen/runway.js).
- RUNWAY: 'runway',
+ RUNWAY: IMAGE_GEN_MODE.RUNWAY,
});
export const VIDEO_GEN_MODES = Object.freeze(Object.values(VIDEO_GEN_MODE));
diff --git a/server/lib/generationModes.test.js b/server/lib/generationModes.test.js
index 8c47736d0f..b04278b482 100644
--- a/server/lib/generationModes.test.js
+++ b/server/lib/generationModes.test.js
@@ -11,9 +11,9 @@ import {
describe('generation mode alphabets', () => {
it('derives immutable image mode lists from the shared discriminator', () => {
- expect(IMAGE_GEN_MODES).toEqual(['external', 'local', 'codex', 'grok', 'agy', 'fal']);
- expect(CLOUD_IMAGE_GEN_MODES).toEqual(['codex', 'grok', 'agy', 'fal']);
- expect(QUEUEABLE_IMAGE_MODES).toEqual(['local', 'codex', 'grok', 'agy', 'fal']);
+ expect(IMAGE_GEN_MODES).toEqual(['external', 'local', 'codex', 'grok', 'agy', 'fal', 'runway']);
+ expect(CLOUD_IMAGE_GEN_MODES).toEqual(['codex', 'grok', 'agy', 'fal', 'runway']);
+ expect(QUEUEABLE_IMAGE_MODES).toEqual(['local', 'codex', 'grok', 'agy', 'fal', 'runway']);
expect([
IMAGE_GEN_MODE,
IMAGE_GEN_MODES,
@@ -22,7 +22,7 @@ describe('generation mode alphabets', () => {
].every(Object.isFrozen)).toBe(true);
});
- it('keeps the video backend alphabet in the image discriminator namespace, plus reactor and runway as video-only extras', () => {
+ it('keeps the video backend alphabet in the image discriminator namespace, plus reactor as a video-only extra', () => {
expect(VIDEO_GEN_MODE).toEqual({
LOCAL: IMAGE_GEN_MODE.LOCAL, GROK: IMAGE_GEN_MODE.GROK, FAL: IMAGE_GEN_MODE.FAL, REACTOR: 'reactor', RUNWAY: 'runway',
});
diff --git a/server/lib/imageGenCapabilities.js b/server/lib/imageGenCapabilities.js
index 83bcff754b..283986e56d 100644
--- a/server/lib/imageGenCapabilities.js
+++ b/server/lib/imageGenCapabilities.js
@@ -189,6 +189,10 @@ export const IMAGE_GEN_PROVIDER_CAPABILITIES = Object.freeze({
// render has nothing to send.
promptRequiredWithInputImage: true,
}),
+ [IMAGE_GEN_MODE.RUNWAY]: Object.freeze({
+ supportsModelOverride: true, maxInputImages: 3, maxReferences: 3,
+ multiCharacterPreservation: true, promptRequiredWithInputImage: true,
+ }),
[IMAGE_GEN_MODE.FAL]: Object.freeze({
// The model IS the product here — each catalog family is a different
// price and look (lib/falImageModels.js), and a per-render override is
diff --git a/server/lib/index.js b/server/lib/index.js
index 5f3cad6fd9..29c8c8c1a6 100644
--- a/server/lib/index.js
+++ b/server/lib/index.js
@@ -228,6 +228,7 @@ export * from './musicVideoCoverOverlay.js';
export * from './musicVideoShotTiming.js';
export * from './reactorStartingFrame.js';
export * from './runwayVideoModels.js';
+export * from './runwayImageModels.js';
export * from './reactorVideoClip.js';
export * from './heavyJobClaim.js';
export * from './hfErrors.js';
diff --git a/server/lib/runwayImageModels.js b/server/lib/runwayImageModels.js
new file mode 100644
index 0000000000..271d633cbc
--- /dev/null
+++ b/server/lib/runwayImageModels.js
@@ -0,0 +1,75 @@
+/** Curated native Runway image schemas and list prices, verified 2026-10-22.
+ * Sources: https://docs.dev.runwayml.com/api.md and guides/pricing.md;
+ * https://github.com/runwayml/sdk-node/blob/main/src/resources/text-to-image.ts
+ * Dependency-free: shared by the server and browser model pickers.
+ */
+export const RUNWAY_IMAGE_PRICING_VERIFIED_AT = '2026-10-22';
+const refuse = (message) => Object.assign(new Error(message), { status: 400, code: 'RUNWAY_IMAGE_INPUT_INVALID' });
+export const RUNWAY_IMAGE_DEFAULT_MODEL = 'gen4_image';
+export const RUNWAY_IMAGE_DISCLOSURE = Object.freeze({
+ execution: 'hosted', provider: 'Runway',
+ summary: 'Prompts and reference images leave this machine and are sent to Runway.',
+ termsUrl: 'https://runwayml.com/terms-of-use',
+ billing: 'Each image is billed. Moderated tasks are not retried.',
+});
+const RATIOS = Object.freeze({
+ '720p': Object.freeze(['1280:720', '720:1280', '720:720', '960:720', '720:960', '1680:720']),
+ '1080p': Object.freeze(['1920:1080', '1080:1920', '1024:1024', '1080:1080', '1360:768', '1168:880', '1440:1080', '1080:1440', '1808:768', '2112:912']),
+});
+export const RUNWAY_IMAGE_MODELS = Object.freeze([
+ { id: 'gen4_image', label: 'Runway Gen-4 Image', minReferences: 0, credits: Object.freeze({ '720p': 5, '1080p': 8 }) },
+ { id: 'gen4_image_turbo', label: 'Runway Gen-4 Image Turbo', minReferences: 1, credits: Object.freeze({ '720p': 2, '1080p': 2 }) },
+].map((row) => Object.freeze({ ...row, ratios: RATIOS, maxReferences: 3, promptMaxChars: 1000, seed: true })));
+export const RUNWAY_IMAGE_MODEL_IDS = Object.freeze(RUNWAY_IMAGE_MODELS.map((row) => row.id));
+export const getRunwayImageModel = (id) => RUNWAY_IMAGE_MODELS.find((row) => row.id === id) || null;
+
+/** Preserve caller framing using the closest supported canvas at the chosen tier. */
+export function runwayImageRatio(model, { width, height, resolution = '720p', ratio } = {}) {
+ const ratios = model.ratios[resolution];
+ if (!ratios) throw refuse(`Runway image resolution must be 720p or 1080p`);
+ if (ratio) {
+ if (!ratios.includes(ratio)) throw refuse(`Runway ${model.id} does not support ratio ${ratio} at ${resolution}`);
+ return ratio;
+ }
+ const aspect = Number(width) > 0 && Number(height) > 0 ? Number(width) / Number(height) : 1;
+ const distance = (value) => { const [w, h] = value.split(':').map(Number); return Math.abs(Math.log(w / h / aspect)); };
+ return ratios.reduce((best, value) => distance(value) < distance(best) ? value : best);
+}
+
+/** Tags identify bindings across renders; supplemental images get distinct suffixes. */
+export function runwayReferenceTags(references = []) {
+ const used = new Set();
+ return references.map((ref, index) => {
+ const identity = String(ref.bindingId || `reference_${index + 1}`);
+ let hash = 2166136261;
+ for (let i = 0; i < identity.length; i += 1) hash = Math.imul(hash ^ identity.charCodeAt(i), 16777619) >>> 0;
+ const prefix = ref.role?.startsWith('character') ? 'char' : ref.role === 'environment' ? 'place' : 'ref';
+ const base = `${prefix}_${hash.toString(36)}`;
+ let tag = base;
+ for (let suffix = 2; used.has(tag); suffix += 1) tag = `${base}_${suffix}`;
+ used.add(tag);
+ return { ...ref, tag };
+ });
+}
+
+export function buildRunwayImageRequest({ modelId = RUNWAY_IMAGE_DEFAULT_MODEL, prompt, referenceImages = [], seed, ...size }) {
+ const model = getRunwayImageModel(modelId);
+ if (!model) throw refuse(`Unknown Runway image model: ${modelId}`);
+ if (typeof prompt !== 'string' || !prompt.trim() || prompt.length > model.promptMaxChars) {
+ throw refuse(`Runway ${modelId} prompt must contain 1–${model.promptMaxChars} characters (received ${prompt?.length ?? 0})`);
+ }
+ if (referenceImages.length < model.minReferences || referenceImages.length > model.maxReferences) {
+ throw refuse(`Runway ${modelId} requires ${model.minReferences}–${model.maxReferences} reference images`);
+ }
+ const tags = referenceImages.map((ref) => ref.tag);
+ if (referenceImages.some((ref) => typeof ref.uri !== 'string' || !ref.uri || !/^[a-z][a-z0-9_]{2,15}$/i.test(ref.tag)) || new Set(tags).size !== tags.length) {
+ throw refuse('Runway reference images require a URI and unique 3–16 character tags');
+ }
+ if (seed != null && seed !== -1 && (!Number.isInteger(Number(seed)) || Number(seed) < 0 || Number(seed) > 4294967295)) throw refuse('Runway seed must be an unsigned 32-bit integer');
+ const ratio = runwayImageRatio(model, size);
+ const resolution = size.resolution || '720p';
+ return {
+ body: { model: model.id, promptText: prompt, ratio, ...(referenceImages.length ? { referenceImages } : {}), ...(seed != null && seed !== -1 ? { seed: Number(seed) } : {}) },
+ resolution, estimatedCredits: model.credits[resolution], estimatedCostUsd: model.credits[resolution] / 100,
+ };
+}
diff --git a/server/lib/runwayImageModels.test.js b/server/lib/runwayImageModels.test.js
new file mode 100644
index 0000000000..8ee1498ede
--- /dev/null
+++ b/server/lib/runwayImageModels.test.js
@@ -0,0 +1,32 @@
+import { describe, it, expect } from 'vitest';
+import { RUNWAY_IMAGE_MODELS, buildRunwayImageRequest, runwayReferenceTags } from './runwayImageModels.js';
+
+const ref = { uri: 'https://example.com/anchor.png', tag: 'char1' };
+describe('Runway image wire contracts', () => {
+ // Catches unsupported model fields and resolution/price drift without paid requests.
+ it.each(RUNWAY_IMAGE_MODELS)('$id emits only the image API fields and prices each canvas', (model) => {
+ for (const [resolution, ratios] of Object.entries(model.ratios)) {
+ for (const ratio of ratios) {
+ const request = buildRunwayImageRequest({ modelId: model.id, prompt: ' @char1 in a garden ', resolution, ratio, seed: 42, referenceImages: [ref] });
+ expect(request.body).toEqual({ model: model.id, promptText: ' @char1 in a garden ', ratio, seed: 42, referenceImages: [ref] });
+ expect(request.estimatedCredits).toBe(model.credits[resolution]);
+ }
+ }
+ });
+ it('permits text-only Gen-4, refuses Turbo without a reference and refuses excess inputs', () => {
+ expect(buildRunwayImageRequest({ prompt: 'garden' }).body).toEqual({ model: 'gen4_image', promptText: 'garden', ratio: '720:720' });
+ expect(() => buildRunwayImageRequest({ modelId: 'gen4_image_turbo', prompt: 'garden' })).toThrow('1–3 reference');
+ expect(() => buildRunwayImageRequest({ prompt: 'garden', referenceImages: [ref, ref, ref, ref] })).toThrow('0–3 reference');
+ expect(() => buildRunwayImageRequest({ prompt: 'x'.repeat(1001) })).toThrow('1001');
+ expect(() => buildRunwayImageRequest({ prompt: 'garden', ratio: '1:1' })).toThrow('ratio');
+ expect(() => buildRunwayImageRequest({ prompt: 'garden', seed: 4294967296 })).toThrow('32-bit');
+ });
+ it('keeps binding tags stable across ordering, distinguishes supplemental anchors and obeys the tag grammar', () => {
+ const a = { bindingId: 'character-example-a', role: 'character-neutral' };
+ const b = { bindingId: 'character-example-b', role: 'character-neutral' };
+ const tags = runwayReferenceTags([a, b, a]);
+ expect(tags[0].tag).toBe(runwayReferenceTags([b, a])[1].tag);
+ expect(new Set(tags.map((r) => r.tag)).size).toBe(3);
+ for (const { tag } of tags) expect(tag).toMatch(/^[a-z][a-z0-9_]{2,15}$/i);
+ });
+});
diff --git a/server/lib/schemaVersions.js b/server/lib/schemaVersions.js
index eb452e0141..ccfa5b0257 100644
--- a/server/lib/schemaVersions.js
+++ b/server/lib/schemaVersions.js
@@ -507,7 +507,8 @@ export const PORTOS_SCHEMA_VERSIONS = Object.freeze({
// nulls an unknown mode on receive, and its next edit would LWW that lost pin
// back onto the newer peer. Backend values in `IMAGE_GEN_MODES` /
// `VIDEO_GEN_MODES` are pinned in schemaVersions.test.js to move with this.
- fableLoom: 10,
+ // v11 adds Runway image backend pins; older peers would erase the unknown mode.
+ fableLoom: 11,
// v1 = Creative Director projects (PostgreSQL `creative_director_projects`)
// federated via the per-record peer-sync push pipeline (record kind
// `creativeDirectorProject`, sync category `creativeDirectorProjects`, #1564).
@@ -787,7 +788,8 @@ export const PORTOS_SCHEMA_VERSIONS = Object.freeze({
// value into `auto`, and its next edit would LWW that un-pinned downgrade back
// onto the newer peer. Any new `IMAGE_GEN_MODES`/`VIDEO_GEN_MODES` value needs
// another bump (guarded in schemaVersions.test.js).
- creativeCommissions: 5,
+ // v6 adds Runway image backend pins; older peers would coerce them to auto.
+ creativeCommissions: 6,
// v1 = standalone media-library federation (#1566). NOT a record kind — it's
// the wire contract for the library-level asset manifest a full-sync peer
// advertises at GET /api/peer-sync/library-manifest. The receiver-pull sweep
diff --git a/server/lib/schemaVersions.test.js b/server/lib/schemaVersions.test.js
index b71b9c4d44..1b4885c7d5 100644
--- a/server/lib/schemaVersions.test.js
+++ b/server/lib/schemaVersions.test.js
@@ -63,11 +63,11 @@ describe('PORTOS_SCHEMA_VERSIONS', () => {
// adds the shared finite/renewable series-design brief.
// Older peers stay behind the full render contract until they advertise
// support for the additive fields.
- expect(PORTOS_SCHEMA_VERSIONS.fableLoom).toBe(10);
+ expect(PORTOS_SCHEMA_VERSIONS.fableLoom).toBe(11);
});
it('version-gates the additive Creative Commission taste brief shape', () => {
- expect(PORTOS_SCHEMA_VERSIONS.creativeCommissions).toBe(5);
+ expect(PORTOS_SCHEMA_VERSIONS.creativeCommissions).toBe(6);
});
it('moves the render-backend alphabets and their sync versions together', () => {
@@ -80,10 +80,10 @@ describe('PORTOS_SCHEMA_VERSIONS', () => {
creativeCommissions: PORTOS_SCHEMA_VERSIONS.creativeCommissions,
fableLoom: PORTOS_SCHEMA_VERSIONS.fableLoom,
}).toEqual({
- image: ['external', 'local', 'codex', 'grok', 'agy', 'fal'],
+ image: ['external', 'local', 'codex', 'grok', 'agy', 'fal', 'runway'],
video: ['local', 'grok', 'fal', 'reactor', 'runway'],
- creativeCommissions: 5,
- fableLoom: 10,
+ creativeCommissions: 6,
+ fableLoom: 11,
});
});
});
diff --git a/server/lib/validation.js b/server/lib/validation.js
index 094f33bfe3..7a59fc32a9 100644
--- a/server/lib/validation.js
+++ b/server/lib/validation.js
@@ -18,6 +18,7 @@ import { APP_FEATURE_IDS, INSTANCE_FEATURE_IDS, INSTANCE_FEATURE_GROUP_IDS } fro
import { MAX_MONTHLY_COST } from './subscriptionSavings.js';
import { MAX_PLAN_TIER_LENGTH } from './subscriptionPlanTiers.js';
import { IMAGE_GEN_MODES, QUEUEABLE_IMAGE_MODES, VIDEO_GEN_MODES } from './generationModes.js';
+import { RUNWAY_IMAGE_MODEL_IDS } from './runwayImageModels.js';
import { FAL_IMAGE_MODEL_IDS } from './falImageModels.js';
import { RENDER_TARGETS, RENDER_TARGET_BACKEND_AUTO } from './renderTargets.js';
import {
@@ -2234,6 +2235,14 @@ export const videoModelTermsSchema = z.object({
// PUT /api/settings/credentials/fal). `model` must name a catalog endpoint
// (lib/falImageModels.js): each id is a different price, so free text is
// refused rather than persisted and discovered at render time.
+export const imageGenRunwaySettingsSchema = z.object({
+ enabled: z.boolean().optional(),
+ model: z.preprocess((v) => v === '' ? undefined : v, z.enum(RUNWAY_IMAGE_MODEL_IDS).optional()),
+ resolution: z.enum(['720p', '1080p']).optional(),
+ cleanC2PA: z.boolean().optional(),
+ denoise: z.boolean().optional(),
+});
+
export const imageGenFalSettingsSchema = z.object({
enabled: z.boolean().optional(),
model: z.preprocess((v) => (v === '' ? undefined : v), z.enum(FAL_IMAGE_MODEL_IDS).optional()),
@@ -2356,6 +2365,7 @@ export const settingsSlicePartialSchemas = Object.freeze({
'imageGen.grok': imageGenGrokSettingsSchema.strict(),
'imageGen.agy': imageGenAgySettingsSchema.strict(),
'imageGen.fal': imageGenFalSettingsSchema.strict(),
+ 'imageGen.runway': imageGenRunwaySettingsSchema.strict(),
'imageGen.expose': z.object({ a1111: z.boolean().optional() }).strict(),
renderDefaults: renderDefaultsSettingsSchema,
videoGen: videoGenSettingsSchema.pick({ mode: true, defaultModelId: true, displaySleep: true }).strict(),
diff --git a/server/routes/settings.js b/server/routes/settings.js
index e1d8b09e8f..784d450c8a 100644
--- a/server/routes/settings.js
+++ b/server/routes/settings.js
@@ -27,7 +27,7 @@ import { storableAutoUpdateConfig } from '../lib/sharedSchemas.js';
import { DEFAULT_UNTRUSTED_CONTENT_POLICY, untrustedContentSettingsSchema } from '../lib/untrustedContent.js';
import { agentContextSettingsSchema } from '../lib/agentContextValidation.js';
import { EFFORT_LEVELS } from '../lib/providerModels.js';
-import { settingsSlicePatchSchema, privateCredentialParamsSchema, privateCredentialInputSchema, backupConfigSchema, autoUpdateSettingsSchema, sharingSettingsPatchSchema, featureProviderConfigSchema, autofixerSettingsSchema, codeReviewSettingsSchema, locationSettingsSchema, hideFirstRunCardSchema, networkSetupPreferenceSchema, settingsEmbeddingsSchema, localLlmSettingsSchema, imessageConfigSchema, signalConfigSchema, beeperSettingsSchema, beeperSavedScopesSchema, spotifyConfigSchema, youtubeConfigSchema, apiAccessSettingsSchema, instanceFeatureSettingsSchema, instanceFeatureIdSchema, instanceFeatureUpdateSchema, instanceFeatureGroupSettingsSchema, instanceFeatureGroupIdSchema, instanceFeatureGroupUpdateSchema, loraTrainingConfigSchema, pipelineEditorialChecksSettingsSchema, creativeDirectorSettingsSchema, musicSettingsSchema, federationSettingsSchema, privacySettingsSchema, seriesAutopilotSettingsSchema, layeredIntelligenceSettingsSchema, imageGenGrokSettingsSchema, imageGenAgySettingsSchema, imageGenFalSettingsSchema, renderDefaultsSettingsSchema, videoGenSettingsSchema, subscriptionCostsMapSchema, subscriptionPlanTiersMapSchema, usageApiBilledInstanceIdsSchema, namedOrchestrationProfileSchema, orchestrationProfilesSettingsSchema, harnessSettingsSchema, credentialBootstrapsSettingsSchema, validateRequest } from '../lib/validation.js';
+import { settingsSlicePatchSchema, privateCredentialParamsSchema, privateCredentialInputSchema, backupConfigSchema, autoUpdateSettingsSchema, sharingSettingsPatchSchema, featureProviderConfigSchema, autofixerSettingsSchema, codeReviewSettingsSchema, locationSettingsSchema, hideFirstRunCardSchema, networkSetupPreferenceSchema, settingsEmbeddingsSchema, localLlmSettingsSchema, imessageConfigSchema, signalConfigSchema, beeperSettingsSchema, beeperSavedScopesSchema, spotifyConfigSchema, youtubeConfigSchema, apiAccessSettingsSchema, instanceFeatureSettingsSchema, instanceFeatureIdSchema, instanceFeatureUpdateSchema, instanceFeatureGroupSettingsSchema, instanceFeatureGroupIdSchema, instanceFeatureGroupUpdateSchema, loraTrainingConfigSchema, pipelineEditorialChecksSettingsSchema, creativeDirectorSettingsSchema, musicSettingsSchema, federationSettingsSchema, privacySettingsSchema, seriesAutopilotSettingsSchema, layeredIntelligenceSettingsSchema, imageGenGrokSettingsSchema, imageGenAgySettingsSchema, imageGenFalSettingsSchema, imageGenRunwaySettingsSchema, renderDefaultsSettingsSchema, videoGenSettingsSchema, subscriptionCostsMapSchema, subscriptionPlanTiersMapSchema, usageApiBilledInstanceIdsSchema, namedOrchestrationProfileSchema, orchestrationProfilesSettingsSchema, harnessSettingsSchema, credentialBootstrapsSettingsSchema, validateRequest } from '../lib/validation.js';
import { filmLookSavedPresetsSchema } from '../lib/filmLookValidation.js';
import { dockerContainmentSettingsSchema } from '../lib/dockerContainmentValidation.js';
@@ -609,6 +609,9 @@ const validateSettingsPatch = async (body) => {
if (body?.imageGen?.agy !== undefined) {
validateRequest(imageGenAgySettingsSchema.partial(), body.imageGen.agy);
}
+ if (body?.imageGen?.runway !== undefined) {
+ validateRequest(imageGenRunwaySettingsSchema.partial(), body.imageGen.runway);
+ }
if (body?.imageGen?.fal !== undefined) {
validateRequest(imageGenFalSettingsSchema.partial(), body.imageGen.fal);
}
diff --git a/server/services/fableLoom/visualConditioning.js b/server/services/fableLoom/visualConditioning.js
index e536b1bc22..c4d4672afb 100644
--- a/server/services/fableLoom/visualConditioning.js
+++ b/server/services/fableLoom/visualConditioning.js
@@ -16,6 +16,7 @@ import {
matchCharactersInText, matchObjectsInText, matchPlacesInText,
} from '../../lib/scenePrompt.js';
import { resolveFableLoomProtagonistPresence } from '../../lib/fableLoomPlayback.js';
+import { IMAGE_GEN_PROVIDER_CAPABILITIES } from '../../lib/imageGenCapabilities.js';
import { CLOUD_IMAGE_GEN_MODES } from '../../lib/generationModes.js';
import { buildFableLoomVisualPrompts } from '../../lib/fableLoomVisualPrompts.js';
import { getUniverse } from '../universeBuilder.js';
@@ -434,11 +435,11 @@ export function fableLoomImageCapabilities({ mode, model = null, inputBudget = 4
referenceRoles: localFlux2 || cloudEdit
? ['temporal-predecessor', 'character-neutral', 'character-profile', 'character-full-body', 'character-expression-gesture', 'character-wardrobe', 'character-prop-scale', 'character-negative-identity', 'character-draft-reference', 'environment', 'object']
: [],
- referenceBudget: localFlux2 || cloudEdit ? inputBudget : 0,
+ referenceBudget: localFlux2 || cloudEdit ? Math.min(inputBudget, IMAGE_GEN_PROVIDER_CAPABILITIES[mode]?.maxInputImages ?? inputBudget) : 0,
supportsLora: localFlux2 || (mode === 'local' && model?.runner === 'mflux'),
loraCompatKey: model?.loraCompatKey || null,
loraBudget: 8,
- multiCharacterPreservation: localFlux2,
+ multiCharacterPreservation: localFlux2 || IMAGE_GEN_PROVIDER_CAPABILITIES[mode]?.multiCharacterPreservation === true,
});
}
diff --git a/server/services/fableLoom/visualConditioning.test.js b/server/services/fableLoom/visualConditioning.test.js
index 7d84a6cbdb..4eb8cbd25a 100644
--- a/server/services/fableLoom/visualConditioning.test.js
+++ b/server/services/fableLoom/visualConditioning.test.js
@@ -71,6 +71,19 @@ const lockedBinding = {
};
describe('FableLoom visual conditioning compiler', () => {
+ // Catches rejecting two cloud-bound characters or over-admitting their reference budget.
+ it('admits locked Runway scenes with both approved identity anchors inside three slots', async () => {
+ const loom = loomWith({ mode: 'locked', characterAppearances: [{ characterId: 'char-a' }, { characterId: 'char-b' }] });
+ const capability = fableLoomImageCapabilities({ mode: 'runway', model: { id: 'gen4_image' }, inputBudget: 8 });
+ expect(capability).toMatchObject({ referenceBudget: 3, multiCharacterPreservation: true });
+ const result = await compileFableLoomVisualRequest({
+ tag: { loomId: loom.id, episodeId: 'episode-1', nodeId: 'shot' }, kind: 'image', capability,
+ authoredPrompt: 'Two rivals', ...deps(loom),
+ });
+ expect(result.visualConditioning.status).toBe('locked');
+ expect(result.referenceImagePaths).toEqual(['/approved/opening.png', '/approved/aria-neutral.png', '/approved/bex-neutral.png']);
+ });
+
it('compiles stable bindings, approved identity assets, adapters, graph continuity and provenance', async () => {
const loom = loomWith(lockedBinding);
const result = await compileFableLoomVisualRequest({
diff --git a/server/services/imageGen/cloudProviderConfig.js b/server/services/imageGen/cloudProviderConfig.js
index 72661835e9..db00a5b865 100644
--- a/server/services/imageGen/cloudProviderConfig.js
+++ b/server/services/imageGen/cloudProviderConfig.js
@@ -29,6 +29,7 @@ import {
renderTargetDefaults,
resolveRenderTargetPins,
} from '../../lib/renderModeLadder.js';
+import { RUNWAY_IMAGE_DEFAULT_MODEL, RUNWAY_IMAGE_MODEL_IDS, getRunwayImageModel } from '../../lib/runwayImageModels.js';
import { FAL_IMAGE_DEFAULT_MODEL, FAL_IMAGE_MODEL_IDS, isFalImageModel } from '../../lib/falImageModels.js';
import {
AGY_IMAGEGEN_DEFAULT_MODEL,
@@ -127,6 +128,13 @@ export const CLOUD_PROVIDER_SPECS = Object.freeze({
modelIsShippedDefault: overrideIsShippedDefault || (!override && !a.model),
}),
}),
+ [IMAGE_GEN_MODE.RUNWAY]: Object.freeze({
+ ...IMAGE_GEN_PROVIDER_CAPABILITIES[IMAGE_GEN_MODE.RUNWAY],
+ label: 'Runway Imagegen', errorCode: 'RUNWAY_IMAGEGEN_DISABLED',
+ knownModels: RUNWAY_IMAGE_MODEL_IDS, unknownModelCode: 'RUNWAY_IMAGE_MODEL_UNKNOWN',
+ modelId: (c, override) => override || (getRunwayImageModel(c.model) ? c.model : RUNWAY_IMAGE_DEFAULT_MODEL),
+ params: (c, override) => ({ model: override || (getRunwayImageModel(c.model) ? c.model : RUNWAY_IMAGE_DEFAULT_MODEL), resolution: c.resolution || '720p' }),
+ }),
[IMAGE_GEN_MODE.FAL]: Object.freeze({
...IMAGE_GEN_PROVIDER_CAPABILITIES[IMAGE_GEN_MODE.FAL],
label: 'fal.ai Imagegen',
diff --git a/server/services/imageGen/cloudProviderConfig.test.js b/server/services/imageGen/cloudProviderConfig.test.js
index 535e67f340..be9370d812 100644
--- a/server/services/imageGen/cloudProviderConfig.test.js
+++ b/server/services/imageGen/cloudProviderConfig.test.js
@@ -18,6 +18,14 @@ import { FAL_IMAGE_DEFAULT_MODEL } from '../../lib/falImageModels.js';
const settingsWith = (imageGen) => ({ imageGen });
describe('resolveCloudProviderConfig', () => {
+ it('carries Runway model and resolution without the shared secret, and rejects an unknown paid model', () => {
+ const settings = { imageGen: { runway: { enabled: true, model: 'gen4_image_turbo', resolution: '1080p' } }, videoGen: { runway: { apiKey: 'test-secret' } } };
+ const resolved = resolveRenderTargetConfig(settings, 'universe-bible', { mode: 'runway' }).cloud;
+ expect(resolved.jobParams).toEqual({ mode: 'runway', model: 'gen4_image_turbo', resolution: '1080p' });
+ expect(() => resolveRenderTargetConfig(settings, 'universe-bible', { mode: 'runway', model: 'unknown' })).toThrow('has no model');
+ expect(resolveCloudProviderConfig({}, 'runway').enabled).toBe(false);
+ });
+
it('returns null for non-cloud modes', () => {
expect(resolveCloudProviderConfig(settingsWith({}), IMAGE_GEN_MODE.LOCAL)).toBeNull();
expect(resolveCloudProviderConfig(settingsWith({}), IMAGE_GEN_MODE.EXTERNAL)).toBeNull();
diff --git a/server/services/imageGen/index.js b/server/services/imageGen/index.js
index c877f8eb3c..559b563c22 100644
--- a/server/services/imageGen/index.js
+++ b/server/services/imageGen/index.js
@@ -26,6 +26,7 @@ import * as codex from './codex.js';
import * as grok from './grok.js';
import * as agy from './agy.js';
import * as fal from './fal.js';
+import * as runway from './runway.js';
import {
IMAGE_GEN_MODE, IMAGE_GEN_MODES, CLOUD_IMAGE_GEN_MODES, isEditCapableMode,
} from './modes.js';
@@ -42,6 +43,7 @@ const CLOUD_PROVIDERS = {
[IMAGE_GEN_MODE.GROK]: grok,
[IMAGE_GEN_MODE.AGY]: agy,
[IMAGE_GEN_MODE.FAL]: fal,
+ [IMAGE_GEN_MODE.RUNWAY]: runway,
};
// Re-export the enum + array so the existing import surface from this module
@@ -249,7 +251,7 @@ export async function generateAvatar({ name, characterClass, prompt }) {
// Callers wanting all of them can read individual providers via the
// re-exports below.
export async function getActiveJob() {
- const jobs = [local.getActiveJob(), external.getActiveJob(), codex.getActiveJob(), grok.getActiveJob(), agy.getActiveJob(), fal.getActiveJob()].filter(Boolean);
+ const jobs = [local.getActiveJob(), external.getActiveJob(), codex.getActiveJob(), grok.getActiveJob(), agy.getActiveJob(), fal.getActiveJob(), runway.getActiveJob()].filter(Boolean);
if (!jobs.length) return null;
return jobs.sort((a, b) => {
const ta = a.createdAt ? Date.parse(a.createdAt) : 0;
@@ -267,6 +269,7 @@ export const attachSseClient = (jobId, res) => {
if (grok.attachSseClient(jobId, res)) return true;
if (agy.attachSseClient(jobId, res)) return true;
if (fal.attachSseClient(jobId, res)) return true;
+ if (runway.attachSseClient(jobId, res)) return true;
return false;
};
@@ -282,7 +285,8 @@ export const cancel = () => {
const grokCancelled = grok.cancelAll();
const agyCancelled = agy.cancelAll();
const falCancelled = fal.cancelAll();
- return Boolean(localCancelled || codexCancelled || grokCancelled || agyCancelled || falCancelled);
+ const runwayCancelled = runway.cancelAll();
+ return Boolean(localCancelled || codexCancelled || grokCancelled || agyCancelled || falCancelled || runwayCancelled);
};
// Exact-ID cancel (#9932). The explicit-target counterpart to cancel(): stops
@@ -295,10 +299,10 @@ export const cancelJob = (jobId) => {
if (!jobId) return false;
const localJob = local.getActiveJob();
if ((localJob?.id === jobId || localJob?.generationId === jobId) && local.cancel()) return true;
- return codex.cancel(jobId) || grok.cancel(jobId) || agy.cancel(jobId) || fal.cancel(jobId);
+ return codex.cancel(jobId) || grok.cancel(jobId) || agy.cancel(jobId) || fal.cancel(jobId) || runway.cancel(jobId);
};
// Re-exports so routes can hit a specific backend directly when the request
// is shape-specific (gallery, LoRAs). The dispatcher is for the generic
// generate/status flow used by all modes.
-export { local, external, codex, grok, agy, fal };
+export { local, external, codex, grok, agy, fal, runway };
diff --git a/server/services/imageGen/modes.js b/server/services/imageGen/modes.js
index 08892a8ccc..d782a12dcf 100644
--- a/server/services/imageGen/modes.js
+++ b/server/services/imageGen/modes.js
@@ -101,6 +101,7 @@ const MODE_LABELS = Object.freeze({
[IMAGE_GEN_MODE.GROK]: 'Grok',
[IMAGE_GEN_MODE.AGY]: 'Agy',
[IMAGE_GEN_MODE.FAL]: 'fal.ai',
+ [IMAGE_GEN_MODE.RUNWAY]: 'Runway',
[IMAGE_GEN_MODE.EXTERNAL]: 'External',
});
diff --git a/server/services/imageGen/promptPreview.js b/server/services/imageGen/promptPreview.js
index 7d4503d11f..2cc8d3df3d 100644
--- a/server/services/imageGen/promptPreview.js
+++ b/server/services/imageGen/promptPreview.js
@@ -17,6 +17,7 @@ import { codexSentPrompt } from './codex.js';
import { grokSentPrompt } from './grok.js';
import { agySentPrompt } from './agy.js';
import { falImageSentPrompt } from './fal.js';
+import { runwayImageSentPrompt } from './runway.js';
import { localSentPrompt } from './local.js';
const isUploadLabel = (path) => typeof path === 'string' && path.startsWith('(uploaded image ');
@@ -68,6 +69,9 @@ export async function previewImagePrompt({ uploadedInitImage = false, uploadedRe
if (mode === IMAGE_GEN_MODE.AGY) {
return { mode, ...agySentPrompt({ ...common, stagingPath: jobOutputPath('portos-agy'), inputImages: previewInputImages(mode, params) }).record };
}
+ if (mode === IMAGE_GEN_MODE.RUNWAY) {
+ return { mode, ...runwayImageSentPrompt({ ...common, inputImages: previewInputImages(mode, params), visualConditioning: params.visualConditioning }).record };
+ }
if (mode === IMAGE_GEN_MODE.FAL) {
const family = falImageFamily(cloud?.providerParams.model || FAL_IMAGE_DEFAULT_MODEL) || falImageFamily(FAL_IMAGE_DEFAULT_MODEL);
return { mode, ...falImageSentPrompt({ ...common, family, inputImages: previewInputImages(mode, params, family.textEndpoint) }).record };
diff --git a/server/services/imageGen/runway.js b/server/services/imageGen/runway.js
new file mode 100644
index 0000000000..ecad6fdaa1
--- /dev/null
+++ b/server/services/imageGen/runway.js
@@ -0,0 +1,269 @@
+import { createMediaJobPreparation } from '../../lib/mediaJobPreparation.js';
+import { withBackupAssetPublication } from '../../lib/backupSnapshotBoundary.js';
+import { randomUUID } from 'crypto';
+import { readFile } from 'fs/promises';
+import { basename, join } from 'path';
+import sharp from 'sharp';
+import { atomicWrite, detectImageFormat, ensureDir, PATHS, unlinkGuarded } from '../../lib/fileUtils.js';
+import { ServerError } from '../../lib/errorHandler.js';
+import { withAbortTimeout } from '../../lib/abortTimeout.js';
+import { anyAbortSignal } from '../../lib/requestAbort.js';
+import { fetchWithTimeout } from '../../lib/fetchWithTimeout.js';
+import { autoCleanGeneratedImage } from '../../lib/imageClean.js';
+import { renderTimingFields } from '../../lib/renderTiming.js';
+import {
+ RUNWAY_IMAGE_DEFAULT_MODEL, getRunwayImageModel, buildRunwayImageRequest, runwayReferenceTags,
+} from '../../lib/runwayImageModels.js';
+import {
+ broadcastSse, attachSseClient as attachSse, closeJobAfterDelay, createJobFailureFinalizer, dispatchTerminalEvent,
+} from '../../lib/sseUtils.js';
+import { imageGenEvents } from '../imageGenEvents.js';
+import { getSettings } from '../settings.js';
+import {
+ awaitRunwayTask, cancelRunwayTask, createRunwayTaskEntry, resolveRunwayApiKey, submitRunwayTask,
+} from '../runwayApi.js';
+import { IMAGE_GEN_MODE } from './modes.js';
+import { resolveInputImages } from './inputImages.js';
+import { cloudPromptRequired } from './cloudProviderConfig.js';
+import { rejectDegenerateFrame } from './frameGuard.js';
+import { carriedPromptAdditions, promptAddition, sentPromptRecord } from '../../lib/modelInput.js';
+
+const MODE = IMAGE_GEN_MODE.RUNWAY;
+const RUNWAY_IMAGE_TIMEOUT_MS = (() => {
+ const n = Number(process.env.RUNWAY_IMAGE_TIMEOUT_MS);
+ return Number.isFinite(n) && n > 0 ? n : 15 * 60 * 1000;
+})();
+const RUNWAY_IMAGE_DOWNLOAD_TIMEOUT_MS = 5 * 60 * 1000;
+const jobs = new Map();
+const activeRequests = new Map();
+const activeJobs = new Map();
+
+export const getActiveJob = () => {
+ const entries = [...activeJobs.values()];
+ return entries.length ? entries[entries.length - 1] : null;
+};
+
+export const attachSseClient = (jobId, res) => attachSse(jobs, jobId, res);
+const preparations = createMediaJobPreparation();
+
+export const cancel = (jobId) => {
+ if (!jobId) {
+ throw new Error('imageGen/runway.cancel requires a jobId — use cancelAll() to terminate every in-flight render');
+ }
+ const pending = preparations.cancel(jobId);
+ if (pending) return pending;
+ const entry = activeRequests.get(jobId);
+ if (!entry) return false;
+ entry.aborted = true;
+ entry.controller.abort();
+ void cancelRunwayTask(entry);
+ return true;
+};
+
+export const cancelAll = () => {
+ const ids = [...preparations.ids(), ...activeRequests.keys()];
+ if (ids.length === 0) return false;
+ for (const id of ids) cancel(id);
+ return true;
+};
+
+const noKeyReason = 'No Runway credential configured — add it in Settings → Credentials or set RUNWAYML_API_SECRET';
+// This probe confirms configuration only; never test credentials with a paid render.
+export async function checkConnection({ model = RUNWAY_IMAGE_DEFAULT_MODEL } = {}) {
+ const apiKey = resolveRunwayApiKey(await getSettings());
+ return { connected: Boolean(apiKey), mode: MODE, model, ...(apiKey ? {} : { reason: noKeyReason }) };
+}
+
+export function runwayImageSentPrompt({ prompt = '', negativePrompt, inputImages, visualConditioning, promptAdditions = [] }) {
+ const references = runwayReferenceTags(inputImages.paths.map((path) => {
+ const asset = visualConditioning?.assets?.find((item) => item.filename === basename(path));
+ return { filename: basename(path), ...(asset || {}), path };
+ }));
+ const roles = references.map((ref) => `@${ref.tag}: ${ref.role || (ref.path === inputImages.initPath ? 'source image to edit' : 'visual reference')}${ref.bindingId ? ` (${ref.bindingId})` : ''}.`).join('\n');
+ const added = [promptAddition('reference-tags', 'Tagged Runway reference images', roles), promptAddition('avoid', 'Negative prompt, sent as "Avoid:"', negativePrompt ? `Avoid: ${negativePrompt}` : '')];
+ const fullPrompt = [prompt, ...added.map((item) => item?.text).filter(Boolean)].join('\n\n');
+ return { fullPrompt, references, record: sentPromptRecord({ sentPrompt: fullPrompt, carried: carriedPromptAdditions({ promptAdditions }), added }) };
+}
+
+async function encodeInputImage(path) {
+ const bytes = await readFile(path);
+ const mime = detectImageFormat(bytes)?.mime;
+ if (!mime || bytes.length > 5 * 1024 * 1024) throw new ServerError('Runway references must be images no larger than 5 MB', { status: 400, code: 'RUNWAY_IMAGE_INPUT_INVALID' });
+ return `data:${mime};base64,${bytes.toString('base64')}`;
+}
+
+export const generateImage = (params) => preparations.run(params, generateImagePrepared);
+
+async function generateImagePrepared({
+ promptAdditions = [],
+ model, resolution = '720p', ratio, prompt = '', negativePrompt, width, height, seed,
+ initImagePath, referenceImagePaths = [],
+ visualConditioning = null,
+ jobId: providedJobId = null,
+ cleanC2PA = false,
+ denoise = false,
+ apiKey: providedApiKey = null,
+ settings = null,
+}) {
+ const renderStartedAtMs = Date.now();
+ await ensureDir(PATHS.images);
+ const family = getRunwayImageModel(model || RUNWAY_IMAGE_DEFAULT_MODEL);
+ if (!family) {
+ throw new ServerError(`Runway Imagegen has no model "${model}"`, { status: 400, code: 'RUNWAY_IMAGE_MODEL_UNKNOWN' });
+ }
+ const inputImages = resolveInputImages({
+ mode: MODE, initImagePath, referenceImagePaths, modelId: family.id,
+ });
+ if (cloudPromptRequired(MODE, inputImages.paths.length > 0) && !prompt?.trim()) {
+ throw new ServerError('Prompt is required', { status: 400, code: 'VALIDATION_ERROR' });
+ }
+ // Resolve the shared credential at dispatch; keys never enter persisted job params.
+ const effectiveSettings = settings || (providedApiKey ? null : await getSettings().catch(() => null));
+ const apiKey = providedApiKey || resolveRunwayApiKey(effectiveSettings);
+ if (!apiKey) {
+ throw new ServerError(noKeyReason, { status: 400, code: 'RUNWAY_NOT_CONFIGURED' });
+ }
+
+ const endpointId = family.id;
+ const jobId = providedJobId || randomUUID();
+ const filename = `${jobId}.png`;
+ const outputPath = join(PATHS.images, filename);
+ if (inputImages.paths.length !== (initImagePath ? 1 : 0) + referenceImagePaths.length) throw new ServerError('Runway reference inputs are unavailable or exceed the three-image limit', { status: 400, code: 'RUNWAY_IMAGE_INPUT_INVALID' });
+ const { fullPrompt, references, record: sentRecord } = runwayImageSentPrompt({ prompt, negativePrompt, inputImages, visualConditioning, promptAdditions });
+ const request = buildRunwayImageRequest({ modelId: family.id, prompt: fullPrompt, resolution, ratio, width, height, seed, referenceImages: references.map((ref) => ({ uri: '(validated input)', tag: ref.tag })) });
+
+ const meta = {
+ id: jobId, prompt: prompt.trim(), negativePrompt: negativePrompt || '',
+ width: width ? Number(width) : null, height: height ? Number(height) : null,
+ filename, mode: MODE,
+ model: endpointId,
+ ratio: request.body.ratio, resolution: request.resolution,
+ referenceTags: references.map(({ path: _path, ...ref }) => ref),
+ inputProvenance: 'provider-inputs',
+ initImageFilename: inputImages.initPath ? basename(inputImages.initPath) : null,
+ referenceImageFilenames: inputImages.referencePaths.map(path => basename(path)),
+ ...(inputImages.paths.length ? { inputImageCount: inputImages.paths.length } : {}),
+ ...(visualConditioning ? { visualConditioning } : {}),
+ ...sentRecord,
+ createdAt: new Date().toISOString(),
+ };
+ const job = { ...meta, clients: [], status: 'running', renderStartedAtMs };
+ jobs.set(jobId, job);
+
+ console.log(`🎨 Generating image [${jobId.slice(0, 8)}] Runway (${endpointId})`);
+ imageGenEvents.emit('started', { generationId: jobId, totalSteps: 1 });
+ activeJobs.set(jobId, { ...meta, generationId: jobId, totalSteps: 1, step: 0, progress: 0, currentImage: null });
+ broadcastSse(job, { type: 'status', message: 'Submitting to Runway…' });
+ runRunway(job, jobId, {
+ apiKey, request, references,
+ outputPath, filename, meta, cleanC2PA, denoise,
+ }).catch((err) => {
+ console.error(`❌ Runway image run failed [${jobId.slice(0, 8)}]: ${err?.message}`);
+ });
+
+ return {
+ jobId, filename, path: `/data/images/${filename}`, generationId: jobId,
+ mode: MODE,
+ status: 'running',
+ };
+}
+
+async function runRunway(job, jobId, {
+ apiKey, request, references,
+ outputPath, filename, meta, cleanC2PA = false, denoise = false,
+}) {
+ const entry = createRunwayTaskEntry(apiKey);
+ entry.aborted = preparations.take(jobId);
+ activeRequests.set(jobId, entry);
+ const deadline = Date.now() + RUNWAY_IMAGE_TIMEOUT_MS;
+ let wroteOutput = false;
+ try {
+ const referenceImages = [];
+ for (const ref of references) referenceImages.push({ uri: await encodeInputImage(ref.path), tag: ref.tag });
+ if (entry.aborted) return finalizeCanceled(job, jobId);
+ entry.taskId = await submitRunwayTask({ apiKey, endpoint: 'text_to_image', body: { ...request.body, ...(referenceImages.length ? { referenceImages } : {}) } });
+ // THROTTLED waits on this accepted task. A failed/moderated task is terminal, never resubmitted.
+ const polled = await awaitRunwayTask({
+ entry, apiKey, deadline, timeoutMs: RUNWAY_IMAGE_TIMEOUT_MS, verbatimFailure: true,
+ onPoll: () => imageGenEvents.emit('activity', { generationId: jobId }),
+ onStatus: (status) => broadcastSse(job, { type: 'status', message: status === 'RUNNING' ? 'Rendering…' : status === 'THROTTLED' ? 'Waiting for Runway model capacity…' : 'Queued at Runway…' }),
+ });
+ if (polled.outcome === 'canceled') return finalizeCanceled(job, jobId);
+ if (polled.outcome === 'failed') return finalizeJobFailure(job, jobId, null, polled.reason);
+
+ const bytes = await withAbortTimeout(RUNWAY_IMAGE_DOWNLOAD_TIMEOUT_MS, async (timeoutSignal) => {
+ const signal = anyAbortSignal([timeoutSignal, entry.controller.signal]);
+ const response = await fetchWithTimeout(polled.outputUrl, { signal }, RUNWAY_IMAGE_DOWNLOAD_TIMEOUT_MS);
+ if (!response.ok) throw new Error(`Runway image download failed: HTTP ${response.status}`);
+ return Buffer.from(await response.arrayBuffer());
+ });
+ if (entry.aborted) return finalizeCanceled(job, jobId);
+
+ await withBackupAssetPublication(async () => {
+ if (entry.aborted) return finalizeCanceled(job, jobId);
+ try {
+ const format = detectImageFormat(bytes)?.format;
+ if (!format) return finalizeJobFailure(job, jobId, null, 'Runway returned a file that is not an image');
+ await atomicWrite(outputPath, format === 'png' ? bytes : await sharp(bytes).png().toBuffer());
+ wroteOutput = true;
+ if (entry.aborted) {
+ await unlinkGuarded(outputPath).catch(() => {});
+ return finalizeCanceled(job, jobId);
+ }
+ const emptyFrame = await rejectDegenerateFrame(outputPath);
+ if (emptyFrame) {
+ await unlinkGuarded(outputPath).catch(() => {});
+ return finalizeJobFailure(job, jobId, null, emptyFrame);
+ }
+
+ const sidecar = join(PATHS.images, `${jobId}.metadata.json`);
+ const actualSeed = request.body.seed ?? null;
+ await atomicWrite(sidecar, {
+ ...meta,
+ ...(request.body.ratio ? { aspectRatio: request.body.ratio } : {}),
+ ...(request.resolution ? { resolution: request.resolution } : {}),
+ ...(actualSeed != null ? { seed: actualSeed } : {}),
+ estimatedCostUsd: request.estimatedCostUsd,
+ estimatedCredits: request.estimatedCredits,
+ ...renderTimingFields(job.renderStartedAtMs),
+ });
+ await autoCleanGeneratedImage({ cleanC2PA, denoise, pngPath: outputPath, sidecarPath: sidecar, mode: MODE });
+ if (entry.aborted) {
+ await Promise.all([outputPath, sidecar].map(path => unlinkGuarded(path)));
+ return finalizeCanceled(job, jobId);
+ }
+ job.status = 'complete';
+ if (activeRequests.get(jobId) === entry) activeRequests.delete(jobId);
+ activeJobs.delete(jobId);
+ console.log(`✅ Image generated [${jobId.slice(0, 8)}]: ${filename} (Runway ${request.body.model}, ~$${request.estimatedCostUsd})`);
+ const done = { filename, path: `/data/images/${filename}` };
+ dispatchTerminalEvent(
+ jobId,
+ () => broadcastSse(job, { type: 'complete', result: done }),
+ () => imageGenEvents.emit('completed', { mode: MODE, generationId: jobId, path: done.path, filename }),
+ );
+ closeJobAfterDelay(jobs, jobId);
+ } catch (err) {
+ if (wroteOutput && job.status !== 'complete') {
+ await Promise.all([outputPath, join(PATHS.images, `${jobId}.metadata.json`)].map(path => unlinkGuarded(path).catch(() => {})));
+ }
+ throw err;
+ }
+ });
+ } catch (err) {
+ await cancelRunwayTask(entry);
+ if (entry.aborted) return finalizeCanceled(job, jobId);
+ finalizeJobFailure(job, jobId, null, `Runway image generation failed: ${err?.message || err}`, { force: true });
+ }
+}
+
+const finalizeJobFailure = createJobFailureFinalizer({
+ jobs,
+ activeJobs,
+ activeSlots: activeRequests,
+ label: 'Runway image generation',
+ events: imageGenEvents,
+ failedPayload: (jobId, reason) => ({ mode: MODE, generationId: jobId, error: reason }),
+});
+const finalizeCanceled = finalizeJobFailure.canceled;
+
diff --git a/server/services/imageGen/runway.test.js b/server/services/imageGen/runway.test.js
new file mode 100644
index 0000000000..7d3c4b4456
--- /dev/null
+++ b/server/services/imageGen/runway.test.js
@@ -0,0 +1,88 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, mkdir, rm, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import sharp from 'sharp';
+import { makePathsProxy } from '../../lib/mockPathsDataRoot.js';
+
+const root = await mkdtemp(join(tmpdir(), 'portos-runway-image-'));
+vi.mock('../../lib/fileUtils.js', async (original) => {
+ const actual = await original();
+ actual.PATHS.images = join(root, 'images');
+ return makePathsProxy(actual, { dataRoot: root });
+});
+vi.mock('../settings.js', () => ({ getSettings: vi.fn(async () => ({ videoGen: { runway: { apiKey: 'test-key' } } })) }));
+const { PATHS } = await import('../../lib/fileUtils.js');
+const runway = await import('./runway.js');
+const { imageGenEvents } = await import('../imageGenEvents.js');
+const terminals = new Map();
+const json = (value) => ({ ok: true, json: async () => value });
+let output;
+let calls;
+let nextTask;
+
+beforeEach(async () => {
+ await mkdir(PATHS.images, { recursive: true });
+ const raw = Buffer.from(Array.from({ length: 64 * 64 * 3 }, (_, i) => i * 37 % 256));
+ output = await sharp(raw, { raw: { width: 64, height: 64, channels: 3 } }).jpeg().toBuffer();
+ calls = []; nextTask = { status: 'SUCCEEDED', output: ['https://example.com/result'] };
+ imageGenEvents.on('completed', onComplete); imageGenEvents.on('failed', onFailed);
+ vi.stubGlobal('fetch', vi.fn(async (url, opts = {}) => {
+ calls.push({ url, method: opts.method || 'GET', body: opts.body ? JSON.parse(opts.body) : null, headers: opts.headers });
+ if (opts.method === 'POST') return json({ id: 'task-example' });
+ if (opts.method === 'DELETE') return json({});
+ if (url.endsWith('/task-example')) return json(nextTask);
+ return { ok: true, arrayBuffer: async () => output };
+ }));
+});
+const onComplete = (event) => terminals.set(event.generationId, { type: 'completed', ...event });
+const onFailed = (event) => terminals.set(event.generationId, { type: 'failed', ...event });
+const terminal = async (id) => { await vi.waitFor(() => expect(terminals.has(id)).toBe(true)); return terminals.get(id); };
+afterEach(async () => {
+ runway.cancelAll(); vi.useRealTimers(); vi.unstubAllGlobals(); terminals.clear();
+ imageGenEvents.off('completed', onComplete); imageGenEvents.off('failed', onFailed);
+ await rm(root, { recursive: true, force: true });
+});
+
+describe('Runway image workflow', () => {
+ it('reuses the video credential, files a text-only still as PNG and records the exact sent prompt and price', async () => {
+ const job = await runway.generateImage({ prompt: ' A garden ', width: 1920, height: 1080 });
+ expect(await terminal(job.jobId)).toMatchObject({ type: 'completed', mode: 'runway' });
+ expect(calls[0]).toMatchObject({ method: 'POST', url: 'https://api.dev.runwayml.com/v1/text_to_image', body: { model: 'gen4_image', promptText: ' A garden ', ratio: '1280:720' }, headers: { Authorization: 'Bearer test-key' } });
+ expect(await sharp(join(PATHS.images, job.filename)).metadata()).toMatchObject({ format: 'png' });
+ expect(JSON.parse(await readFile(join(PATHS.images, `${job.jobId}.metadata.json`), 'utf8'))).toMatchObject({ mode: 'runway', model: 'gen4_image', ratio: '1280:720', estimatedCredits: 5, sentPrompt: ' A garden ' });
+ });
+ it('sends both bound character anchors with distinct stable tags and records basenames rather than paths', async () => {
+ const paths = ['hero.png', 'rival.png'].map((name) => join(PATHS.images, name));
+ await Promise.all(paths.map((path) => writeFile(path, output)));
+ const visualConditioning = { assets: [{ filename: 'hero.png', bindingId: 'char-a', role: 'character-neutral' }, { filename: 'rival.png', bindingId: 'char-b', role: 'character-neutral' }] };
+ const job = await runway.generateImage({ prompt: 'Two rivals', model: 'gen4_image_turbo', referenceImagePaths: paths, visualConditioning });
+ expect(await terminal(job.jobId)).toMatchObject({ type: 'completed' });
+ const refs = calls[0].body.referenceImages;
+ expect(refs).toHaveLength(2);
+ expect(refs[0].tag).not.toBe(refs[1].tag);
+ for (const ref of refs) { expect(ref.uri).toMatch(/^data:image\/jpeg;base64,/); expect(calls[0].body.promptText).toContain(`@${ref.tag}`); }
+ const sidecar = JSON.parse(await readFile(join(PATHS.images, `${job.jobId}.metadata.json`), 'utf8'));
+ expect(sidecar.referenceTags.map((r) => r.filename)).toEqual(['hero.png', 'rival.png']);
+ expect(JSON.stringify(sidecar)).not.toContain(root);
+ });
+ it('fails a moderated task once with its verbatim reason and permits the next asset', async () => {
+ nextTask = { status: 'FAILED', failureCode: 'SAFETY.INPUT', failure: 'Input rejected by Runway moderation.' };
+ const job = await runway.generateImage({ prompt: 'A garden' });
+ expect(await terminal(job.jobId)).toMatchObject({ type: 'failed', error: nextTask.failure });
+ expect(calls.filter((c) => c.method === 'POST')).toHaveLength(1);
+ expect(calls.some((c) => c.method === 'DELETE')).toBe(false);
+ nextTask = { status: 'SUCCEEDED', output: ['https://example.com/result'] };
+ const next = await runway.generateImage({ prompt: 'A meadow' });
+ expect(await terminal(next.jobId)).toMatchObject({ type: 'completed' });
+ });
+ it('waits on the same throttled task and cancels it without a resubmission', async () => {
+ nextTask = { status: 'THROTTLED' };
+ const job = await runway.generateImage({ prompt: 'A garden' });
+ await vi.waitFor(() => expect(calls.some((c) => c.url.endsWith('/task-example'))).toBe(true));
+ expect(runway.cancel(job.jobId)).toBe(true);
+ expect(await terminal(job.jobId)).toMatchObject({ type: 'failed' });
+ expect(calls.filter((c) => c.method === 'POST')).toHaveLength(1);
+ expect(calls.filter((c) => c.method === 'DELETE')).toHaveLength(1);
+ });
+});
diff --git a/server/services/imageGenQuota.js b/server/services/imageGenQuota.js
index dc6ddcaf7c..2358efb43e 100644
--- a/server/services/imageGenQuota.js
+++ b/server/services/imageGenQuota.js
@@ -61,7 +61,7 @@ const UNKNOWN_BLOCK_TTL_MS = 60 * 60 * 1000;
// account, not drawn from a subscription quota window, so there is no reset to
// observe and its failures (content policy, bad input) are not quota blocks.
// Its spend is recorded per render instead (`estimatedCostUsd` in the sidecar).
-export const isQuotaTrackedImageMode = (mode) => CLOUD_IMAGE_GEN_MODES.includes(mode) && mode !== IMAGE_GEN_MODE.FAL;
+export const isQuotaTrackedImageMode = (mode) => CLOUD_IMAGE_GEN_MODES.includes(mode) && ![IMAGE_GEN_MODE.FAL, IMAGE_GEN_MODE.RUNWAY].includes(mode);
/** Card id for the image-gen quota card, in the same namespace as the provider
* family ids in providerUsage.js — a per-family read has to be able to name it. */
diff --git a/server/services/mediaJobQueue/index.js b/server/services/mediaJobQueue/index.js
index d82c6d4b9c..8bb18b0a57 100644
--- a/server/services/mediaJobQueue/index.js
+++ b/server/services/mediaJobQueue/index.js
@@ -243,6 +243,7 @@ const MEDIA_JOB_RUNTIME = Object.freeze({
[IMAGE_GEN_MODE.GROK]: () => import('../imageGen/grok.js'),
[IMAGE_GEN_MODE.AGY]: () => import('../imageGen/agy.js'),
[IMAGE_GEN_MODE.FAL]: () => import('../imageGen/fal.js'),
+ [IMAGE_GEN_MODE.RUNWAY]: () => import('../imageGen/runway.js'),
default: () => import('../imageGen/local.js'),
},
invoke: (mod, request) => mod.generateImage(request),
diff --git a/server/services/runwayApi.js b/server/services/runwayApi.js
index 2899dc56b6..e27e765092 100644
--- a/server/services/runwayApi.js
+++ b/server/services/runwayApi.js
@@ -1,5 +1,5 @@
/**
- * Runway developer API — the task transport for the Runway video backend.
+ * Runway developer API — the shared task transport for image and video backends.
*
* Runway runs every generation as a task: POST the input to
* `/v1/image_to_video` (or `/v1/text_to_video`), which answers `{ id }`; poll
@@ -78,7 +78,7 @@ export async function cancelRunwayTask(entry) {
if (!entry.remoteTerminal) maintenance.markCurrentUnsettled();
}
-/** Submit one paid generation to `endpoint` ('image_to_video' | 'text_to_video'). Resolves to the task id. */
+/** Submit one paid generation to a generation endpoint. Resolves to the task id. */
export async function submitRunwayTask({ apiKey, endpoint, body }) {
const res = await fetchWithTimeout(`${RUNWAY_API_BASE}/v1/${endpoint}`, {
method: 'POST', headers: headers(apiKey, true), body: JSON.stringify(body),
@@ -113,7 +113,7 @@ async function getRunwayTask({ apiKey, taskId }) {
* THROTTLED, RUNNING) for the caller's progress wording.
*/
export async function awaitRunwayTask({
- entry, apiKey, deadline, timeoutMs, onPoll = () => {}, onStatus = () => {}, pollIntervalMs = RUNWAY_POLL_INTERVAL_MS,
+ entry, apiKey, deadline, timeoutMs, onPoll = () => {}, onStatus = () => {}, pollIntervalMs = RUNWAY_POLL_INTERVAL_MS, verbatimFailure = false,
}) {
let statusFailures = 0;
// A cancel (entry.controller.abort()) ends the wait at once rather than after the next interval.
@@ -147,13 +147,13 @@ export async function awaitRunwayTask({
entry.remoteTerminal = true;
if (entry.aborted) return { outcome: 'canceled' };
const outputUrl = Array.isArray(task.output) ? task.output.find((url) => typeof url === 'string' && url.trim()) : null;
- return outputUrl ? { outcome: 'completed', outputUrl } : { outcome: 'failed', reason: 'Runway finished but returned no video URL' };
+ return outputUrl ? { outcome: 'completed', outputUrl } : { outcome: 'failed', reason: 'Runway finished but returned no output URL' };
}
if (task?.status === 'FAILED' || task?.status === 'CANCELLED' || task?.status === 'CANCELED') {
entry.remoteTerminal = true;
if (entry.aborted) return { outcome: 'canceled' };
const code = typeof task.failureCode === 'string' ? ` (${task.failureCode})` : '';
- return { outcome: 'failed', reason: `Runway render failed: ${task.failure || task.status.toLowerCase()}${code}` };
+ return { outcome: 'failed', reason: verbatimFailure && task.failure ? task.failure : `Runway render failed: ${task.failure || task.status.toLowerCase()}${code}` };
}
onStatus(task?.status, Number.isFinite(task?.progress) ? task.progress : null);
await wait();