videoclaw 3.0.0-alpha.1

package/dist/video/gemini-judge.js

@@ -0,0 +1,218 @@
+import { readFile } from 'node:fs/promises';
+import { extname } from 'node:path';
+import { fetchGeminiWithPool } from './gemini-key-pool.js';
+const DEFAULT_GEMINI_JUDGE_ENDPOINT = 'https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent';
+/**
+ * Maximum total inline-image payload (sum of base64 byte lengths) we will send
+ * to Gemini in a single judge request. Gemini's hard per-request ceiling is
+ * ~20 MB; we stay comfortably under it so the surrounding JSON/prompt text and
+ * transport overhead never push the request over the edge. Configurable via
+ * VCLAW_GEMINI_JUDGE_MAX_INLINE_BYTES (bytes). When the budget is exhausted,
+ * further images are dropped (with a per-image stderr warning) rather than
+ * silently producing an oversized request that the API rejects.
+ */
+const DEFAULT_MAX_INLINE_BYTES = 15 * 1024 * 1024;
+function maxInlineBytes() {
+    const raw = process.env.VCLAW_GEMINI_JUDGE_MAX_INLINE_BYTES;
+    if (raw === undefined)
+        return DEFAULT_MAX_INLINE_BYTES;
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : DEFAULT_MAX_INLINE_BYTES;
+}
+function inlinePartByteLength(part) {
+    return part.inlineData.data.length;
+}
+function imageMimeType(imagePath) {
+    switch (extname(imagePath).toLowerCase()) {
+        case '.jpg':
+        case '.jpeg':
+            return 'image/jpeg';
+        case '.webp':
+            return 'image/webp';
+        case '.png':
+        default:
+            return 'image/png';
+    }
+}
+// Mirrors parseGeminiTextResponse in gemini-analyze.ts: unwrap
+// candidates[0].content.parts[].text. Returns '' rather than throwing so the
+// caller can omit an unparseable scene instead of failing the whole batch.
+function extractGeminiText(payload) {
+    const candidates = payload.candidates;
+    return (candidates?.[0]?.content?.parts
+        ?.map((part) => part.text ?? '')
+        .join('\n')
+        .trim() ?? '');
+}
+function stripJsonFences(text) {
+    return text
+        .replace(/^```json\s*/i, '')
+        .replace(/^```\s*/i, '')
+        .replace(/\s*```$/i, '')
+        .trim();
+}
+async function readInlineImagePart(imagePath) {
+    try {
+        const bytes = await readFile(imagePath);
+        return {
+            inlineData: {
+                mimeType: imageMimeType(imagePath),
+                data: bytes.toString('base64'),
+            },
+        };
+    }
+    catch {
+        // Missing/unreadable file: skip the attachment, never crash.
+        return null;
+    }
+}
+function buildJudgePromptText(scene) {
+    const lines = [
+        'You are a film director selecting the single best candidate render for one scene of a video.',
+        '',
+    ];
+    if (scene.intendedPrompt) {
+        lines.push(`Intended scene prompt:\n${scene.intendedPrompt}`, '');
+    }
+    lines.push('Candidates (each may have an attached image below, in order):');
+    for (const candidate of scene.candidates) {
+        lines.push(`- id "${candidate.id}"${candidate.prompt ? `: ${candidate.prompt}` : ''}`);
+    }
+    lines.push('', 'Pick the candidate that best matches the intended scene prompt with the highest', 'visual quality, character/style consistency, and absence of artifacts.', 'Return ONLY valid JSON of the exact shape:', '{ "bestCandidateId": "<one of the candidate ids above>", "reasoning": "<short explanation>" }', 'The bestCandidateId MUST be exactly one of the listed candidate ids.', 'Do not wrap the JSON in markdown fences.');
+    return lines.join('\n');
+}
+async function judgeOneScene(scene, referenceParts, endpoint, fetcher) {
+    const knownIds = new Set(scene.candidates.map((candidate) => candidate.id));
+    const parts = [];
+    // Pre-flight inline-image budget. Each base64-encoded image is large; with
+    // many candidates plus reference images a single request can blow past
+    // Gemini's ~20 MB ceiling, which surfaces as a non-OK response that silently
+    // drops the scene. We instead drop images once the budget is exhausted and
+    // log each skip, so the failure mode is observable and the scene can still be
+    // judged on whatever images (and the prompt text) fit.
+    const budget = maxInlineBytes();
+    let usedBytes = 0;
+    if (referenceParts.length > 0) {
+        const fittedRefs = [];
+        let droppedRefs = 0;
+        for (const part of referenceParts) {
+            const size = inlinePartByteLength(part);
+            if (usedBytes + size > budget) {
+                droppedRefs += 1;
+                continue;
+            }
+            usedBytes += size;
+            fittedRefs.push(part);
+        }
+        if (droppedRefs > 0) {
+            process.stderr.write(`[judge/gemini] scene=${scene.sceneIndex} dropped ${droppedRefs} reference image(s) to stay under the ${budget}-byte inline payload budget\n`);
+        }
+        if (fittedRefs.length > 0) {
+            parts.push({ text: 'Reference images (the look/identity to match):' });
+            parts.push(...fittedRefs);
+        }
+    }
+    // Attach each candidate's image (if present and readable), labeled so the
+    // model can align image -> id. Candidates with no image are judged by prompt
+    // text alone. Images beyond the remaining byte budget are skipped (logged),
+    // so an oversized scene degrades gracefully instead of failing the request.
+    for (const candidate of scene.candidates) {
+        if (!candidate.imagePath)
+            continue;
+        const part = await readInlineImagePart(candidate.imagePath);
+        if (!part)
+            continue;
+        const size = inlinePartByteLength(part);
+        if (usedBytes + size > budget) {
+            process.stderr.write(`[judge/gemini] scene=${scene.sceneIndex} candidate "${candidate.id}" image skipped: exceeds the ${budget}-byte inline payload budget; judging it by prompt text only\n`);
+            continue;
+        }
+        usedBytes += size;
+        parts.push({ text: `Candidate "${candidate.id}" image:` });
+        parts.push(part);
+    }
+    parts.push({ text: buildJudgePromptText(scene) });
+    let response;
+    try {
+        response = await fetchGeminiWithPool((key) => `${endpoint}${endpoint.includes('?') ? '&' : '?'}key=${encodeURIComponent(key)}`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', Connection: 'close' },
+            body: JSON.stringify({
+                contents: [{ parts }],
+                generationConfig: {
+                    temperature: 0.2,
+                    maxOutputTokens: 600,
+                    responseMimeType: 'application/json',
+                },
+            }),
+        }, {
+            fetcher,
+            onRetry: (label, status) => {
+                process.stderr.write(`[judge/gemini] scene=${scene.sceneIndex} ${label} returned HTTP ${status}; rotating key\n`);
+            },
+        });
+    }
+    catch (error) {
+        process.stderr.write(`[judge/gemini] scene=${scene.sceneIndex} request error: ${error instanceof Error ? error.message : String(error)}; leaving to human\n`);
+        return null;
+    }
+    if (!response.ok) {
+        process.stderr.write(`[judge/gemini] scene=${scene.sceneIndex} HTTP ${response.status}; leaving to human\n`);
+        return null;
+    }
+    let payload;
+    try {
+        payload = await response.json();
+    }
+    catch {
+        return null;
+    }
+    const text = extractGeminiText(payload);
+    if (!text)
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(stripJsonFences(text));
+    }
+    catch {
+        process.stderr.write(`[judge/gemini] scene=${scene.sceneIndex} unparseable JSON; leaving to human\n`);
+        return null;
+    }
+    const bestCandidateId = typeof parsed.bestCandidateId === 'string' ? parsed.bestCandidateId : '';
+    if (!bestCandidateId || !knownIds.has(bestCandidateId)) {
+        process.stderr.write(`[judge/gemini] scene=${scene.sceneIndex} returned unknown candidate id "${bestCandidateId}"; leaving to human\n`);
+        return null;
+    }
+    const reasoning = typeof parsed.reasoning === 'string' ? parsed.reasoning : '';
+    return { sceneIndex: scene.sceneIndex, bestCandidateId, reasoning };
+}
+/**
+ * LLM-as-judge auto-select. For each scene, asks Gemini to pick the best
+ * candidate, conditioned on the intended prompt, each candidate's image (when
+ * available on disk), and any shared reference images.
+ *
+ * Defensive by design: a scene whose response can't be parsed, returns an
+ * unknown candidate id, or errors at the network layer is OMITTED from the
+ * result (never throws the whole batch) — the caller treats omitted scenes as
+ * "leave to human". The network is only ever touched through the injected
+ * `fetcher` (via fetchGeminiWithPool), so this is unit-testable without keys.
+ */
+export async function judgeBestCandidates(input) {
+    const endpoint = input.endpoint ?? process.env.VCLAW_GEMINI_API_ENDPOINT ?? DEFAULT_GEMINI_JUDGE_ENDPOINT;
+    const referenceParts = [];
+    for (const refPath of input.referenceImagePaths ?? []) {
+        const part = await readInlineImagePart(refPath);
+        if (part)
+            referenceParts.push(part);
+    }
+    const results = [];
+    for (const scene of input.scenes) {
+        if (scene.candidates.length === 0)
+            continue;
+        const result = await judgeOneScene(scene, referenceParts, endpoint, input.fetcher);
+        if (result)
+            results.push(result);
+    }
+    return results;
+}
+//# sourceMappingURL=gemini-judge.js.map

package/dist/video/gemini-judge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gemini-judge.js","sourceRoot":"","sources":["../../src/video/gemini-judge.ts"],"names":[],"mappings":"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"}

package/dist/video/gemini-key-pool.d.ts

@@ -0,0 +1,23 @@
+export declare function getPoolSize(): number;
+export declare function getPoolLabels(): string[];
+export declare function nextAvailableKey(): Promise<{
+    key: string;
+    label: string;
+} | undefined>;
+export declare function markKeyRateLimited(key: string, durationMs?: number): void;
+export declare function fetchGeminiWithPool(buildUrl: (key: string) => string, init: RequestInit, options?: {
+    maxAttempts?: number;
+    onRetry?: (label: string, status: number) => void;
+    fetcher?: typeof fetch;
+    /**
+     * Explicit API key to use instead of the process.env-backed round-robin
+     * pool. When set (non-empty), the global pool is bypassed entirely: every
+     * attempt uses this key and no cooldown bookkeeping is applied. This lets a
+     * library caller inject a key resolved from its own env (e.g. a backend's
+     * `input.env`) without mutating process.env. Falls back to the pool when
+     * absent.
+     */
+    keyOverride?: string;
+}): Promise<Response>;
+export declare function _resetPoolForTests(): void;
+//# sourceMappingURL=gemini-key-pool.d.ts.map

package/dist/video/gemini-key-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gemini-key-pool.d.ts","sourceRoot":"","sources":["../../src/video/gemini-key-pool.ts"],"names":[],"mappings":"AA8CA,wBAAgB,WAAW,IAAI,MAAM,CAEpC;AAED,wBAAgB,aAAa,IAAI,MAAM,EAAE,CAExC;AAED,wBAAsB,gBAAgB,IAAI,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAAC,CA0B5F;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,GAAE,MAA4B,GAAG,IAAI,CAQ9F;AAED,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,EACjC,IAAI,EAAE,WAAW,EACjB,OAAO,GAAE;IACP,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAClD,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACjB,GACL,OAAO,CAAC,QAAQ,CAAC,CAsCnB;AAED,wBAAgB,kBAAkB,IAAI,IAAI,CAGzC"}

package/dist/video/gemini-key-pool.js

@@ -0,0 +1,107 @@
+const DEFAULT_COOLDOWN_MS = 60_000;
+let pool = null;
+let roundRobinIndex = 0;
+function loadPool() {
+    if (pool !== null)
+        return pool;
+    const sources = [
+        process.env.GEMINI_API_KEYS,
+        process.env.GOOGLE_API_KEYS,
+        process.env.GOOGLE_API_KEY,
+    ].filter((value) => typeof value === 'string' && value.length > 0);
+    const seen = new Set();
+    const keys = [];
+    for (const source of sources) {
+        for (const raw of source.split(/[,;\n\s]+/)) {
+            const key = raw.trim();
+            if (!key || seen.has(key))
+                continue;
+            seen.add(key);
+            keys.push(key);
+        }
+    }
+    pool = keys.map((key, index) => ({
+        key,
+        cooldownUntil: 0,
+        label: `k${index + 1}[${key.slice(0, 6)}…]`,
+    }));
+    if (pool.length > 1) {
+        process.stderr.write(`[gemini-pool] Loaded ${pool.length} keys: ${pool.map((entry) => entry.label).join(', ')}\n`);
+    }
+    return pool;
+}
+export function getPoolSize() {
+    return loadPool().length;
+}
+export function getPoolLabels() {
+    return loadPool().map((entry) => entry.label);
+}
+export async function nextAvailableKey() {
+    const entries = loadPool();
+    if (entries.length === 0)
+        return undefined;
+    const now = Date.now();
+    for (let offset = 0; offset < entries.length; offset += 1) {
+        const index = (roundRobinIndex + offset) % entries.length;
+        const entry = entries[index];
+        if (entry.cooldownUntil <= now) {
+            roundRobinIndex = (index + 1) % entries.length;
+            return { key: entry.key, label: entry.label };
+        }
+    }
+    const soonest = entries.reduce((current, candidate) => candidate.cooldownUntil < current.cooldownUntil ? candidate : current);
+    const waitMs = Math.max(0, soonest.cooldownUntil - now);
+    if (waitMs > 0) {
+        process.stderr.write(`[gemini-pool] All ${entries.length} keys cooling; waiting ${Math.round(waitMs / 1000)}s for ${soonest.label}\n`);
+        await new Promise((resolve) => setTimeout(resolve, waitMs + 100));
+    }
+    soonest.cooldownUntil = 0;
+    return { key: soonest.key, label: soonest.label };
+}
+export function markKeyRateLimited(key, durationMs = DEFAULT_COOLDOWN_MS) {
+    const entries = loadPool();
+    const entry = entries.find((candidate) => candidate.key === key);
+    if (!entry)
+        return;
+    entry.cooldownUntil = Date.now() + durationMs;
+    process.stderr.write(`[gemini-pool] ${entry.label} rate-limited — cooling for ${Math.round(durationMs / 1000)}s\n`);
+}
+export async function fetchGeminiWithPool(buildUrl, init, options = {}) {
+    const keyOverride = typeof options.keyOverride === 'string' && options.keyOverride.trim() !== ''
+        ? options.keyOverride.trim()
+        : undefined;
+    const maxAttempts = options.maxAttempts ?? Math.max(4, (keyOverride ? 1 : getPoolSize()) + 2);
+    const fetcher = options.fetcher ?? fetch;
+    let lastStatus = 0;
+    let lastBody = '';
+    for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+        const picked = keyOverride
+            ? { key: keyOverride, label: `override[${keyOverride.slice(0, 6)}…]` }
+            : await nextAvailableKey();
+        if (!picked) {
+            throw new Error('No Gemini API keys configured (set GEMINI_API_KEYS or GOOGLE_API_KEY)');
+        }
+        const response = await fetcher(buildUrl(picked.key), init);
+        if (response.ok)
+            return response;
+        const retryable = response.status === 429 || response.status === 503 || response.status >= 500;
+        if (retryable && attempt < maxAttempts - 1) {
+            const retryAfter = Number(response.headers.get('retry-after'));
+            const cooldownMs = Number.isFinite(retryAfter) && retryAfter > 0
+                ? retryAfter * 1000
+                : DEFAULT_COOLDOWN_MS;
+            markKeyRateLimited(picked.key, cooldownMs);
+            options.onRetry?.(picked.label, response.status);
+            lastStatus = response.status;
+            lastBody = await response.text().catch(() => '');
+            continue;
+        }
+        return response;
+    }
+    return new Response(lastBody, { status: lastStatus, statusText: 'Retries exhausted' });
+}
+export function _resetPoolForTests() {
+    pool = null;
+    roundRobinIndex = 0;
+}
+//# sourceMappingURL=gemini-key-pool.js.map

package/dist/video/gemini-key-pool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gemini-key-pool.js","sourceRoot":"","sources":["../../src/video/gemini-key-pool.ts"],"names":[],"mappings":"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"}

package/dist/video/gen-image-flow.d.ts

@@ -0,0 +1,187 @@
+import { type GenImageKind, type GenImageResult } from './gen-image.js';
+/**
+ * Google Flow image backend for `gen-image` (useapi.net Google Flow API v1,
+ * POST /google-flow/images). Direct useapi REST from Node — the same precedent
+ * as `native-runway.ts` / `native-dreamina.ts`; it does NOT shell out to the
+ * Bun `vclaw-cli` sidecar.
+ *
+ * Models: imagen-4 (text-to-image), nano-banana (character consistency),
+ * nano-banana-pro (max references, upscale-able). Reference images are
+ * `reference_1..10` mediaGenerationId slots; saved characters are
+ * `character_1..7` slots (June-2026 useapi update). Inline @-markers
+ * (`@reference_N` / `@character_N`, case-insensitive) anchor a slot to a
+ * position in the prompt — each marker MUST have a matching body slot or the
+ * API 400s, so `validateFlowImageMarkers` runs BEFORE any upload or spend.
+ */
+export declare const FLOW_IMAGE_MODELS: readonly ["imagen-4", "nano-banana", "nano-banana-pro"];
+export type FlowImageModel = typeof FLOW_IMAGE_MODELS[number];
+/**
+ * Per-model TOTAL reference-image budget — references AND character images
+ * share it (verified against the live useapi docs, 2026-06-11): imagen-4
+ * accepts at most 3, nano-banana and nano-banana-pro at most 10. This is the
+ * hard request budget, distinct from the auto-selection heuristic below.
+ */
+export declare const FLOW_IMAGE_MODEL_REF_BUDGET: Record<FlowImageModel, number>;
+/** POST /google-flow/images slot caps. */
+export declare const FLOW_IMAGE_MAX_REFERENCES = 10;
+export declare const FLOW_IMAGE_MAX_CHARACTERS = 7;
+/** Aspect ratios POST /google-flow/images accepts (landscape/portrait are legacy aliases). */
+export declare const FLOW_IMAGE_ASPECTS: string[];
+/**
+ * Resolve the Flow image model: an explicit id wins (validated against
+ * FLOW_IMAGE_MODELS); otherwise auto-select from the total reference-image
+ * count — 0 refs → imagen-4 (best pure text-to-image), 1-3 → nano-banana
+ * (character consistency), 4+ → nano-banana-pro (max references).
+ */
+export declare function resolveFlowImageModel(explicit: string | undefined, refCount: number): FlowImageModel;
+/**
+ * How many reference images a saved-character ref contributes to the per-model
+ * budget. Character refs look like `user:1-character:<id>-imgs:N-voice:<v>`;
+ * the `-imgs:N-` segment carries the character's image count. Refs without the
+ * hint count as 1.
+ */
+export declare function flowCharacterRefImageCount(ref: string): number;
+/**
+ * True when a string looks like a saved Flow character ref (the
+ * `flow-characters.json` `characterRef` format, e.g.
+ * `user:1-character:claw-imgs:1-voice:puck`) rather than a character name.
+ * The `-character:` segment is REQUIRED: mediaGenerationIds share the `user:`
+ * prefix, so a bare-prefix check would let a `--ref` value pasted into
+ * `--character` ship to the API instead of failing fast as character_not_found.
+ */
+export declare function looksLikeFlowCharacterRef(value: string): boolean;
+/**
+ * True when a `--ref` value is SHAPED like an already-uploaded Flow media
+ * reference (a mediaGenerationId) rather than a local image path. Aligned with
+ * `flow-character-library.ts`'s `isMediaRef` so both modules classify the same
+ * way. Anything NOT media-shaped is treated as a local path and must exist —
+ * classifying by shape (instead of `existsSync` polarity) means a typo'd local
+ * path fails fast up front rather than shipping to the provider as a bogus
+ * mediaGenerationId after other refs were already uploaded (spend).
+ */
+export declare function looksLikeFlowMediaRef(value: string): boolean;
+/**
+ * POST /google-flow/images request body (mirrors the useapi wire shape).
+ * `reference_1..10` are mediaGenerationId values; `character_1..7` are saved
+ * Flow character refs.
+ */
+export interface FlowImageParams {
+    email: string;
+    prompt: string;
+    model: FlowImageModel;
+    aspectRatio: string;
+    count: number;
+    seed?: number;
+    reference_1?: string;
+    reference_2?: string;
+    reference_3?: string;
+    reference_4?: string;
+    reference_5?: string;
+    reference_6?: string;
+    reference_7?: string;
+    reference_8?: string;
+    reference_9?: string;
+    reference_10?: string;
+    character_1?: string;
+    character_2?: string;
+    character_3?: string;
+    character_4?: string;
+    character_5?: string;
+    character_6?: string;
+    character_7?: string;
+}
+export interface BuildFlowImageParamsOptions {
+    prompt: string;
+    kind: GenImageKind;
+    /** useapi account email carried in the request body. */
+    email: string;
+    /** Explicit model id; omitted → auto-selected from the total reference count. */
+    model?: string;
+    /** Defaults per kind (16:9 for screen, 1:1 otherwise). */
+    aspectRatio?: string;
+    /** Images per generation, 1-4. Defaults to 1 (the API default of 4 would 4x the spend). */
+    count?: number;
+    /** Seed for reproducible results (non-negative integer). */
+    seed?: number;
+    /**
+     * Values for reference_1..N in order. Validation only depends on the COUNT,
+     * so callers may pass not-yet-uploaded local paths for fail-fast/dry-run
+     * composition and rebuild with resolved mediaGenerationIds before the POST.
+     */
+    references?: string[];
+    /** Saved Flow character refs for character_1..N in order. */
+    characterRefs?: string[];
+}
+/**
+ * Compose the POST /google-flow/images body (PURE — no I/O, no env). Weaves
+ * the gen-image per-kind render directive into the prompt (consistent with
+ * `buildGenImageRequest`), assigns `reference_1..N` / `character_1..N` slots in
+ * input order, and enforces the hard request contract as errors:
+ *
+ * - ≤10 references, ≤7 characters (slot caps);
+ * - model × reference budget (imagen-4 ≤3, nano-banana(-pro) ≤10) where
+ *   character refs COUNT TOWARD the same budget (each contributes its
+ *   `-imgs:N-` image count, default 1);
+ * - count 1-4, seed ≥0, aspect ratio membership (`auto` needs a nano-banana
+ *   model and at least one reference);
+ * - every inline @-marker has a matching slot (`validateFlowImageMarkers`).
+ */
+export declare function buildFlowImageParams(opts: BuildFlowImageParamsOptions): FlowImageParams;
+/**
+ * Output path for the Nth generated image (1-based): the first goes to
+ * `outputPath` verbatim, extras get a `-2`/`-3`/`-4` suffix before the
+ * extension. PURE.
+ */
+export declare function flowOutputPathForIndex(outputPath: string, ordinal: number): string;
+export interface FlowGenImageOptions {
+    prompt: string;
+    kind: GenImageKind;
+    /** Where the first resulting image is written (extras get -2/-3/-4 suffixes). */
+    outputPath: string;
+    /** Explicit model id; omitted → auto-selected from the reference count. */
+    model?: string;
+    aspectRatio?: string;
+    /** Images per generation (1-4, default 1). */
+    count?: number;
+    seed?: number;
+    /**
+     * Already-uploaded mediaGenerationIds (media-ref-shaped, passed through) or
+     * local image paths (anything else; must exist, uploaded first).
+     */
+    refs?: string[];
+    /** Character names already resolved to saved Flow character refs. */
+    characterRefs?: string[];
+    /** useapi token; falls back to USEAPI_API_TOKEN. */
+    apiToken?: string;
+    /** useapi account email; falls back to USEAPI_ACCOUNT_EMAIL. */
+    accountEmail?: string;
+    /** useapi base URL override (default https://api.useapi.net/v1). */
+    baseUrl?: string;
+    /** Injectable fetch for tests; defaults to the global fetch. */
+    fetcher?: typeof fetch;
+}
+export interface FlowGenImageResult extends GenImageResult {
+    /** Every written file in order (paths[0] === path). */
+    paths: string[];
+    /** mediaGenerationIds of the generated image(s), reusable as reference_N inputs downstream. */
+    mediaGenerationIds: string[];
+    /** Images requested per generation. */
+    count: number;
+    /** Seed echoed when one was requested. */
+    seed?: number;
+    /** mediaGenerationIds minted for uploaded local reference paths (in --ref order). */
+    uploadedReferenceIds: string[];
+}
+/**
+ * Generate image(s) via Google Flow and write them to disk. Sequence:
+ * validate markers + the model×reference matrix FIRST (zero network on
+ * validation failure) → classify refs by shape and fail fast on any
+ * non-media-shaped ref whose local path is missing (still zero network) →
+ * upload the local reference paths via the existing
+ * `FlowLibraryClient.uploadImage` → POST /google-flow/images → download every
+ * generated image (first to `outputPath`, extras suffixed -2/-3/-4). Returns
+ * the gen-image result shape with `backend: 'flow'` plus the generated
+ * `mediaGenerationIds` for downstream reuse.
+ */
+export declare function generateViaFlow(opts: FlowGenImageOptions): Promise<FlowGenImageResult>;
+//# sourceMappingURL=gen-image-flow.d.ts.map

package/dist/video/gen-image-flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gen-image-flow.d.ts","sourceRoot":"","sources":["../../src/video/gen-image-flow.ts"],"names":[],"mappings":"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"}