videoclaw 3.0.0-alpha.1

package/dist/video/gen-image-flow.js

@@ -0,0 +1,331 @@
+import { existsSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { validateFlowImageMarkers } from './flow-markers.js';
+import { FlowLibraryClient } from './flow-character-library.js';
+import { composeGenImagePrompt, defaultGenImageAspect, } 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 const FLOW_IMAGE_MODELS = ['imagen-4', 'nano-banana', 'nano-banana-pro'];
+/**
+ * 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 const FLOW_IMAGE_MODEL_REF_BUDGET = {
+    'imagen-4': 3,
+    'nano-banana': 10,
+    'nano-banana-pro': 10,
+};
+/** POST /google-flow/images slot caps. */
+export const FLOW_IMAGE_MAX_REFERENCES = 10;
+export const FLOW_IMAGE_MAX_CHARACTERS = 7;
+const FLOW_IMAGE_DEFAULT_BASE_URL = 'https://api.useapi.net/v1';
+/** Aspect ratios POST /google-flow/images accepts (landscape/portrait are legacy aliases). */
+export const FLOW_IMAGE_ASPECTS = ['16:9', '4:3', '1:1', '3:4', '9:16', 'auto', 'landscape', 'portrait'];
+/**
+ * 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 function resolveFlowImageModel(explicit, refCount) {
+    if (explicit !== undefined) {
+        if (!FLOW_IMAGE_MODELS.includes(explicit)) {
+            throw new Error(`gen-image (flow): model must be one of ${FLOW_IMAGE_MODELS.join(', ')}, got: ${explicit}`);
+        }
+        return explicit;
+    }
+    if (refCount <= 0)
+        return 'imagen-4';
+    if (refCount <= 3)
+        return 'nano-banana';
+    return 'nano-banana-pro';
+}
+/**
+ * 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 function flowCharacterRefImageCount(ref) {
+    const match = /-imgs:(\d+)(?=-|$)/.exec(ref);
+    if (!match)
+        return 1;
+    const n = Number.parseInt(match[1], 10);
+    return n >= 1 ? n : 1;
+}
+/**
+ * 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 function looksLikeFlowCharacterRef(value) {
+    return value.includes('-character:');
+}
+/**
+ * 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 function looksLikeFlowMediaRef(value) {
+    return value.startsWith('user:') || value.includes('-image:') || value.includes('mediaGenerationId');
+}
+/**
+ * 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 function buildFlowImageParams(opts) {
+    const references = opts.references ?? [];
+    const characterRefs = opts.characterRefs ?? [];
+    if (references.length > FLOW_IMAGE_MAX_REFERENCES) {
+        throw new Error(`gen-image (flow): at most ${FLOW_IMAGE_MAX_REFERENCES} references are supported (reference_1..${FLOW_IMAGE_MAX_REFERENCES}), got ${references.length}.`);
+    }
+    if (characterRefs.length > FLOW_IMAGE_MAX_CHARACTERS) {
+        throw new Error(`gen-image (flow): at most ${FLOW_IMAGE_MAX_CHARACTERS} characters are supported (character_1..${FLOW_IMAGE_MAX_CHARACTERS}), got ${characterRefs.length}.`);
+    }
+    const count = opts.count ?? 1;
+    if (!Number.isInteger(count) || count < 1 || count > 4) {
+        throw new Error(`gen-image (flow): count must be an integer between 1 and 4, got: ${opts.count}.`);
+    }
+    if (opts.seed !== undefined && (!Number.isInteger(opts.seed) || opts.seed < 0)) {
+        throw new Error(`gen-image (flow): seed must be a non-negative integer, got: ${opts.seed}.`);
+    }
+    // Character refs roll their per-character image counts into the SAME
+    // per-model budget as plain references.
+    const characterImageCount = characterRefs.reduce((sum, ref) => sum + flowCharacterRefImageCount(ref), 0);
+    const totalRefImages = references.length + characterImageCount;
+    const model = resolveFlowImageModel(opts.model, totalRefImages);
+    const budget = FLOW_IMAGE_MODEL_REF_BUDGET[model];
+    if (totalRefImages > budget) {
+        throw new Error(`gen-image (flow): ${model} accepts at most ${budget} reference images, got ${totalRefImages} ` +
+            `(${references.length} reference${references.length === 1 ? '' : 's'} + ${characterImageCount} character image${characterImageCount === 1 ? '' : 's'} — ` +
+            'character refs count toward the same per-model budget). ' +
+            'Use nano-banana-pro for up to 10, or drop references.');
+    }
+    const aspectRatio = opts.aspectRatio ?? defaultGenImageAspect(opts.kind);
+    if (!FLOW_IMAGE_ASPECTS.includes(aspectRatio)) {
+        throw new Error(`gen-image (flow): aspect ratio must be one of ${FLOW_IMAGE_ASPECTS.join(', ')}, got: ${aspectRatio}.`);
+    }
+    if (aspectRatio === 'auto' && (model === 'imagen-4' || totalRefImages === 0)) {
+        throw new Error('gen-image (flow): aspect ratio "auto" requires a nano-banana model and at least one reference image.');
+    }
+    const prompt = composeGenImagePrompt(opts.prompt, opts.kind);
+    const markerErrors = validateFlowImageMarkers(prompt, {
+        characterCount: characterRefs.length,
+        referenceCount: references.length,
+    });
+    if (markerErrors.length > 0) {
+        throw new Error(`gen-image (flow): invalid @-markers in prompt:\n- ${markerErrors.join('\n- ')}`);
+    }
+    const params = {
+        email: opts.email,
+        prompt,
+        model,
+        aspectRatio,
+        count,
+        ...(opts.seed !== undefined ? { seed: opts.seed } : {}),
+    };
+    const slots = params;
+    references.forEach((ref, i) => {
+        slots[`reference_${i + 1}`] = ref;
+    });
+    characterRefs.forEach((ref, i) => {
+        slots[`character_${i + 1}`] = ref;
+    });
+    return params;
+}
+/**
+ * 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 function flowOutputPathForIndex(outputPath, ordinal) {
+    if (ordinal <= 1)
+        return outputPath;
+    return /\.[^./\\]+$/.test(outputPath)
+        ? outputPath.replace(/(\.[^./\\]+)$/, `-${ordinal}$1`)
+        : `${outputPath}-${ordinal}`;
+}
+function normalizeFlowHttpError(label, status, bodyText) {
+    let detail = bodyText.slice(0, 300);
+    try {
+        // useapi Flow `POST /images` 429/403 bodies changed shape on 2026-06-15
+        // (https://useapi.net/docs/changelog): the top-level `error` is now a
+        // classification STRING (e.g. "captcha_quality: ..." /
+        // "PUBLIC_ERROR_USER_QUOTA_REACHED"), and Google's structured error body +
+        // captcha metadata moved into a nested `response` wrapper. Older bodies put
+        // the structured object directly at `error`. Read both so the message keeps
+        // the classification AND the underlying Google reason regardless of shape.
+        const parsed = JSON.parse(bodyText);
+        const classification = typeof parsed.error === 'string'
+            ? parsed.error
+            : parsed.error !== undefined
+                ? JSON.stringify(parsed.error)
+                : undefined;
+        const nested = parsed.response?.error;
+        const reason = (Array.isArray(nested?.details) && typeof nested?.details?.[0]?.reason === 'string'
+            ? nested.details?.[0]?.reason
+            : undefined)
+            ?? (typeof nested?.message === 'string' ? nested.message : undefined)
+            ?? (typeof nested?.code === 'string' ? nested.code : undefined);
+        const parts = [classification, reason].filter((p) => typeof p === 'string' && p.length > 0);
+        if (parts.length > 0)
+            detail = parts.join(' — ');
+    }
+    catch {
+        // non-JSON body — keep the truncated text
+    }
+    return new Error(`gen-image (flow) ${label} failed (HTTP ${status}): ${detail}`);
+}
+/**
+ * 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 async function generateViaFlow(opts) {
+    const apiToken = opts.apiToken ?? process.env.USEAPI_API_TOKEN;
+    if (!apiToken) {
+        throw new Error('gen-image --backend flow requires a useapi token (set USEAPI_API_TOKEN or pass apiToken).');
+    }
+    const accountEmail = opts.accountEmail ?? process.env.USEAPI_ACCOUNT_EMAIL;
+    if (!accountEmail) {
+        throw new Error('gen-image --backend flow requires the useapi account email (set USEAPI_ACCOUNT_EMAIL or pass accountEmail).');
+    }
+    const baseUrl = (opts.baseUrl ?? FLOW_IMAGE_DEFAULT_BASE_URL).replace(/\/$/, '');
+    const fetcher = opts.fetcher ?? fetch;
+    const refs = opts.refs ?? [];
+    const characterRefs = opts.characterRefs ?? [];
+    const buildOpts = {
+        prompt: opts.prompt,
+        kind: opts.kind,
+        email: accountEmail,
+        ...(opts.model !== undefined ? { model: opts.model } : {}),
+        ...(opts.aspectRatio !== undefined ? { aspectRatio: opts.aspectRatio } : {}),
+        ...(opts.count !== undefined ? { count: opts.count } : {}),
+        ...(opts.seed !== undefined ? { seed: opts.seed } : {}),
+        characterRefs,
+    };
+    // Fail-fast pass BEFORE any upload/spend: validation only depends on slot
+    // counts and the prompt, so raw (not-yet-uploaded) reference values suffice.
+    buildFlowImageParams({ ...buildOpts, references: refs });
+    // Classify every ref by SHAPE first (looksLikeFlowMediaRef): media-ref-shaped
+    // values pass through verbatim; everything else is a local image path and
+    // must exist. The existence scan runs BEFORE any upload so a typo'd path
+    // fails fast with zero network instead of shipping as a bogus
+    // mediaGenerationId after sibling refs were already uploaded (spend).
+    const missingLocalRefs = refs.filter((ref) => !looksLikeFlowMediaRef(ref) && !existsSync(ref));
+    if (missingLocalRefs.length > 0) {
+        throw new Error(`gen-image (flow): --ref local path${missingLocalRefs.length === 1 ? '' : 's'} not found: ${missingLocalRefs.join(', ')}. ` +
+            'Values not shaped like an uploaded Flow media ref (user:...) are treated as local image paths and must exist.');
+    }
+    const client = new FlowLibraryClient({ apiToken, accountEmail, baseUrl, fetchImpl: fetcher });
+    const uploadedReferenceIds = [];
+    const resolvedRefs = [];
+    for (const ref of refs) {
+        if (looksLikeFlowMediaRef(ref)) {
+            resolvedRefs.push(ref);
+        }
+        else {
+            const mediaId = await client.uploadImage(ref);
+            uploadedReferenceIds.push(mediaId);
+            resolvedRefs.push(mediaId);
+        }
+    }
+    const params = buildFlowImageParams({ ...buildOpts, references: resolvedRefs });
+    const response = await fetcher(`${baseUrl}/google-flow/images`, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${apiToken}`,
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+        },
+        body: JSON.stringify(params),
+    });
+    if (!response.ok) {
+        throw normalizeFlowHttpError('POST /google-flow/images', response.status, await response.text());
+    }
+    const raw = (await response.json());
+    const generated = (raw.media ?? [])
+        .map((item) => item.image?.generatedImage)
+        .filter((img) => !!img?.mediaGenerationId);
+    if (generated.length === 0) {
+        throw new Error(`gen-image (flow): POST /google-flow/images succeeded but returned no generated images${raw.error ? ` (${raw.error})` : ''}.`);
+    }
+    const paths = [];
+    const mediaGenerationIds = [];
+    let firstBytes = 0;
+    let firstUrl;
+    for (let i = 0; i < generated.length; i += 1) {
+        const image = generated[i];
+        mediaGenerationIds.push(image.mediaGenerationId);
+        const url = image.fifeUrl;
+        if (!url) {
+            throw new Error(`gen-image (flow): generated image ${i + 1} (${image.mediaGenerationId}) has no downloadable URL (fifeUrl missing).`);
+        }
+        const download = await fetcher(url, {});
+        if (!download.ok) {
+            throw new Error(`gen-image (flow): image download failed with HTTP ${download.status}: ${url}`);
+        }
+        const bytes = Buffer.from(await download.arrayBuffer());
+        const target = flowOutputPathForIndex(opts.outputPath, i + 1);
+        await mkdir(dirname(target), { recursive: true });
+        await writeFile(target, bytes);
+        paths.push(target);
+        if (i === 0) {
+            firstBytes = bytes.length;
+            firstUrl = url;
+        }
+    }
+    return {
+        path: paths[0],
+        kind: opts.kind,
+        backend: 'flow',
+        model: params.model,
+        aspectRatio: params.aspectRatio,
+        imageUrl: firstUrl,
+        sizeBytes: firstBytes,
+        paths,
+        mediaGenerationIds,
+        count: params.count,
+        ...(params.seed !== undefined ? { seed: params.seed } : {}),
+        uploadedReferenceIds,
+    };
+}
+//# sourceMappingURL=gen-image-flow.js.map

package/dist/video/gen-image-flow.js.map

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

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

@@ -0,0 +1,153 @@
+/**
+ * Diegetic still-asset generation for in-world UI graphics — props, on-screen
+ * dashboards, motion-graphic overlays — the kind the reference advert used (a
+ * "Settlement Report Dashboard", a "SYSTEM COMPROMISED" alert) inside shots.
+ * vclaw generates character frames and storyboard grids elsewhere; this module
+ * covers ARBITRARY prop / screen / overlay graphics.
+ *
+ * Three interchangeable backends, selected by `backend`:
+ *   - `gobananas` (DEFAULT): the same image API `character-auto-create.ts` uses
+ *     (`POST ${apiUrl}/images`, no OpenAI key). Reads the returned image URL and
+ *     downloads it to disk, honoring the served file's REAL extension.
+ *   - `openai`: the OpenAI Images API (`POST /v1/images/generations`, gpt-image-1 /
+ *     the "gpt-image-2" family), returning `{ data: [{ b64_json }] }` decoded to disk.
+ *   - `flow`: Google Flow via useapi.net (`POST /google-flow/images`, imagen-4 /
+ *     nano-banana / nano-banana-pro) with reference_1..10 + character_1..7 slots
+ *     and inline @-marker validation — see `gen-image-flow.ts`.
+ *
+ * The fetcher is injectable so request composition, URL/b64 extraction, and the
+ * download/decode are fully testable offline.
+ */
+export declare const GEN_IMAGE_KINDS: readonly ["prop", "screen", "overlay"];
+export type GenImageKind = typeof GEN_IMAGE_KINDS[number];
+export declare const GEN_IMAGE_BACKENDS: readonly ["gobananas", "openai", "flow"];
+export type GenImageBackend = typeof GEN_IMAGE_BACKENDS[number];
+/** The proven default backend (no OpenAI key required). */
+export declare const DEFAULT_GEN_IMAGE_BACKEND: GenImageBackend;
+export declare const DEFAULT_GO_BANANAS_API_URL = "https://gobananasai.com/api";
+export declare const DEFAULT_GEN_IMAGE_MODEL = "gemini-pro-image";
+export declare const DEFAULT_OPENAI_IMAGE_ENDPOINT = "https://api.openai.com/v1/images/generations";
+/** gpt-image-1 is the live API model id for the gpt-image ("gpt-image-2") family. */
+export declare const DEFAULT_OPENAI_IMAGE_MODEL = "gpt-image-1";
+/** Go Bananas `POST /images` request body. */
+export interface GoBananasGenImageRequest {
+    prompt: string;
+    aspect_ratio: string;
+    model_id: string;
+    enhance_prompt: boolean;
+    negative_prompt: string;
+    /** Lock the still to a managed Go Bananas character for identity consistency. */
+    character_id?: number;
+    /** Render via a Go Bananas style preset (e.g. the multi-view reference sheet). */
+    style_preset_id?: number;
+}
+/** OpenAI `POST /v1/images/generations` request body. */
+export interface OpenAiGenImageRequest {
+    model: string;
+    prompt: string;
+    size: string;
+    n: number;
+}
+export type GenImageRequest = GoBananasGenImageRequest | OpenAiGenImageRequest;
+export interface BuildGenImageRequestOptions {
+    prompt: string;
+    kind: GenImageKind;
+    /** Backend to compose for; defaults to `gobananas`. */
+    backend?: GenImageBackend;
+    /** Go Bananas aspect ratio override (ignored by the OpenAI backend). */
+    aspectRatio?: string;
+    /** OpenAI canvas size override (ignored by the Go Bananas backend). */
+    size?: string;
+    /** Model id override for the selected backend. */
+    model?: string;
+    /** Go Bananas only: lock the still to a managed character id for consistency. */
+    characterId?: number;
+    /** Go Bananas only: render via a style preset (e.g. the reference-sheet preset). */
+    stylePresetId?: number;
+}
+/**
+ * Weave the per-kind render directive into a prompt (PURE). Shared by every
+ * backend's request composer so the directive treatment never drifts.
+ */
+export declare function composeGenImagePrompt(prompt: string, kind: GenImageKind): string;
+/** Default aspect ratio for a kind (PURE; shared with the Flow backend). */
+export declare function defaultGenImageAspect(kind: GenImageKind): string;
+/**
+ * Compose the image request body for the selected backend (PURE). Weaves the
+ * per-kind render directive into the prompt. For Go Bananas it resolves the
+ * aspect ratio and a text-aware negative prompt; for OpenAI it resolves the
+ * canvas size. Exposed for tests and dry-run inspection. (The Flow backend has
+ * its own composer — `buildFlowImageParams` in `gen-image-flow.ts` — because
+ * its body carries reference/character slots and marker validation.)
+ */
+export declare function buildGenImageRequest(opts: BuildGenImageRequestOptions): GenImageRequest;
+/** Extract the image URL from the many shapes the Go Bananas /images endpoint
+ * may return (mirrors character-auto-create's fallback chain). */
+export declare function extractGenImageUrl(payload: unknown): string | undefined;
+export interface GenerateGenImageOptions {
+    prompt: string;
+    kind: GenImageKind;
+    /** Backend to use; defaults to `gobananas`. */
+    backend?: GenImageBackend;
+    /** Where the resulting image is written. */
+    outputPath: string;
+    /** Go Bananas aspect ratio override. */
+    aspectRatio?: string;
+    /** OpenAI canvas size override. */
+    size?: string;
+    /** Model id override for the selected backend. */
+    model?: string;
+    /** Go Bananas only: lock the still to a managed character id for consistency. */
+    characterId?: number;
+    /** Go Bananas only: render via a style preset (e.g. the reference-sheet preset). */
+    stylePresetId?: number;
+    /**
+     * API key. Go Bananas falls back to GO_BANANAS_API_KEY; OpenAI falls back to
+     * OPENAI_API_KEY.
+     */
+    apiKey?: string;
+    /** Go Bananas API base URL; falls back to GO_BANANAS_API_URL then the default. */
+    apiUrl?: string;
+    /** OpenAI endpoint override; falls back to VCLAW_OPENAI_IMAGE_ENDPOINT then the default. */
+    endpoint?: string;
+    /** Injectable fetch for tests; defaults to the global fetch. */
+    fetcher?: typeof fetch;
+    /** Flow backend: local image paths (uploaded first) or mediaGenerationIds for reference_1..10. */
+    refs?: string[];
+    /** Flow backend: saved Flow character refs for character_1..7. */
+    characterRefs?: string[];
+    /** Flow backend: images per generation (1-4, default 1). */
+    count?: number;
+    /** Flow backend: seed for reproducible results. */
+    seed?: number;
+    /** Flow backend: useapi token; falls back to USEAPI_API_TOKEN. */
+    apiToken?: string;
+    /** Flow backend: useapi account email; falls back to USEAPI_ACCOUNT_EMAIL. */
+    accountEmail?: string;
+}
+export interface GenImageResult {
+    path: string;
+    kind: GenImageKind;
+    backend: GenImageBackend;
+    model: string;
+    /** Present for the Go Bananas and Flow backends. */
+    aspectRatio?: string;
+    /** Present for the OpenAI backend. */
+    size?: string;
+    /** Present for the Go Bananas and Flow backends (the downloaded URL). */
+    imageUrl?: string;
+    sizeBytes: number;
+}
+/**
+ * Return `outputPath` with its extension replaced by the image format implied by
+ * `imageUrl` (jpg/jpeg→jpg, png, webp, gif, avif). When the URL carries no
+ * recognizable image extension, `outputPath` is returned unchanged. PURE.
+ */
+export declare function withImageExtension(outputPath: string, imageUrl: string): string;
+/**
+ * Generate a diegetic still and write it to disk via the selected backend.
+ * Throws a clear error when the key is missing, a request fails, or no image
+ * data/URL comes back.
+ */
+export declare function generateGenImage(opts: GenerateGenImageOptions): Promise<GenImageResult>;
+//# sourceMappingURL=gen-image.d.ts.map

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

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