venice-video-harness 2.4.0

package/dist/venice/generate.js

@@ -0,0 +1,150 @@
+// ---------------------------------------------------------------------------
+// Image generation functions for the Venice AI API.
+//
+// - generateImage          -- thin wrapper around POST /api/v1/image/generate
+// - generateWithReferences -- builds a reference-augmented prompt for
+//                             character-consistent storyboard frames
+// ---------------------------------------------------------------------------
+import { assertNotSilentRejectImage, thresholdForResolution } from "./rejection.js";
+// ---- Constants ------------------------------------------------------------
+const GENERATE_PATH = "/api/v1/image/generate";
+// Safe low-level fallback when no caller supplies a model. `seedream-v5-lite`
+// is accepted by Seedance 2.0 regardless of whether the output contains a
+// face. High-level callers (mini-drama CLI, storyboard assembler) should
+// pick a model based on face presence — nano-banana-pro for faceless work,
+// seedream-v5-lite for face-bearing work.
+const DEFAULT_MODEL = "seedream-v5-lite";
+const DEFAULT_RESOLUTION = "1K";
+const DEFAULT_ASPECT_RATIO = "1:1";
+/** Venice supports up to 14 reference images per request. */
+const MAX_REFERENCE_IMAGES = 14;
+/** Maximum number of the 14 slots that may be used for face references. */
+const MAX_FACE_SLOTS = 5;
+// ---- generateImage --------------------------------------------------------
+/**
+ * Generate a single image from a text prompt.
+ *
+ * This is a straightforward 1:1 mapping to the Venice `/api/v1/image/generate`
+ * endpoint.  All request fields are forwarded as-is; only `model`, `resolution`,
+ * and `aspect_ratio` receive defaults when omitted.
+ *
+ * @param client  An authenticated {@link VeniceClient} instance.
+ * @param options Request parameters.  At minimum `prompt` is required.
+ * @returns       The full API response including the `images` array.
+ */
+export async function generateImage(client, options) {
+    const body = {
+        model: options.model ?? DEFAULT_MODEL,
+        resolution: options.resolution ?? DEFAULT_RESOLUTION,
+        aspect_ratio: options.aspect_ratio ?? DEFAULT_ASPECT_RATIO,
+        ...options,
+    };
+    const raw = await client.post(GENERATE_PATH, body);
+    // Venice may return images as raw base64 strings or as { b64_json } objects.
+    // Normalize to the { b64_json, seed } shape our codebase expects.
+    const rawImages = raw.images ?? [];
+    const normalized = {
+        images: rawImages.map((img) => {
+            if (typeof img === "string") {
+                return { b64_json: img };
+            }
+            return img;
+        }),
+    };
+    const threshold = thresholdForResolution(body.resolution);
+    for (const img of normalized.images) {
+        const decoded = Buffer.from(img.b64_json, "base64");
+        assertNotSilentRejectImage(decoded, {
+            model: body.model,
+            prompt: body.prompt,
+            threshold,
+        });
+    }
+    return normalized;
+}
+// ---- generateWithReferences -----------------------------------------------
+/**
+ * Generate a scene image while injecting character face references for
+ * identity consistency across storyboard frames.
+ *
+ * **How it works**
+ *
+ * 1. The caller supplies up to 14 {@link CharacterReference} entries via
+ *    `options.referenceImages`.
+ * 2. The first N entries (where N = `options.faceSlots`, default 5, max 5)
+ *    are treated as **face references**.  For each one a role-assignment line
+ *    is prepended to the prompt so the model knows which reference image
+ *    corresponds to which character:
+ *
+ *    ```
+ *    Image 1: face reference for MARCUS (the detective)
+ *    Image 2: face reference for LENA (the journalist)
+ *    ```
+ *
+ * 3. All reference images (face + non-face) are concatenated as a
+ *    comma-separated base-64 string in the `image` field, which Venice
+ *    interprets as a multi-reference input.
+ *
+ * 4. The fidelity is set to a moderate default (0.35) to allow creative
+ *    freedom while anchoring character likeness.
+ *
+ * @param client  An authenticated {@link VeniceClient} instance.
+ * @param options Generation parameters plus reference images.
+ * @returns       The generated image as base-64 and the seed used.
+ */
+export async function generateWithReferences(client, options) {
+    const { referenceImages, faceSlots: rawFaceSlots, prompt, negative_prompt, resolution = DEFAULT_RESOLUTION, aspect_ratio = DEFAULT_ASPECT_RATIO, model = DEFAULT_MODEL, steps, cfg_scale, seed, safe_mode, hide_watermark, } = options;
+    // ---- Validate reference counts ------------------------------------------
+    if (referenceImages.length > MAX_REFERENCE_IMAGES) {
+        throw new Error(`Venice supports at most ${MAX_REFERENCE_IMAGES} reference images per request, ` +
+            `but ${referenceImages.length} were provided.`);
+    }
+    const faceSlots = Math.min(Math.max(rawFaceSlots ?? MAX_FACE_SLOTS, 0), MAX_FACE_SLOTS);
+    // ---- Build augmented prompt ---------------------------------------------
+    const faceRefs = referenceImages.slice(0, faceSlots);
+    const roleLines = faceRefs.map((ref, i) => `Image ${i + 1}: face reference for ${ref.name} (${ref.role})`);
+    const augmentedPrompt = roleLines.length > 0
+        ? `${roleLines.join("\n")}\n\n${prompt}`
+        : prompt;
+    // ---- Assemble request body ----------------------------------------------
+    const body = {
+        model,
+        prompt: augmentedPrompt,
+        resolution,
+        aspect_ratio,
+    };
+    if (negative_prompt !== undefined)
+        body.negative_prompt = negative_prompt;
+    if (steps !== undefined)
+        body.steps = steps;
+    if (cfg_scale !== undefined)
+        body.cfg_scale = cfg_scale;
+    if (seed !== undefined)
+        body.seed = seed;
+    if (safe_mode !== undefined)
+        body.safe_mode = safe_mode;
+    if (hide_watermark !== undefined)
+        body.hide_watermark = hide_watermark;
+    // ---- Call API -----------------------------------------------------------
+    const raw = await client.post(GENERATE_PATH, body);
+    // Venice may return images as raw base64 strings or as { b64_json } objects.
+    const rawImages = raw.images ?? [];
+    const firstImage = rawImages[0];
+    if (!firstImage) {
+        throw new Error("Venice API returned an empty images array.");
+    }
+    const b64 = typeof firstImage === "string"
+        ? firstImage
+        : firstImage.b64_json;
+    const resultSeed = typeof firstImage === "object"
+        ? firstImage.seed
+        : undefined;
+    const decoded = Buffer.from(b64, "base64");
+    assertNotSilentRejectImage(decoded, {
+        model,
+        prompt: augmentedPrompt,
+        threshold: thresholdForResolution(resolution),
+    });
+    return { base64: b64, seed: resultSeed };
+}
+//# sourceMappingURL=generate.js.map

package/dist/venice/generate.js.map

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

package/dist/venice/image-bytes.d.ts

@@ -0,0 +1,26 @@
+export type ImageFormat = 'png' | 'jpeg' | 'webp' | 'gif' | 'avif' | 'unknown';
+export interface SniffResult {
+    format: ImageFormat;
+    mime: string;
+    ext: string;
+}
+/**
+ * Inspect the leading bytes of `buf` and return the image format. Returns
+ * `{ format: 'unknown', mime: 'application/octet-stream', ext: '.bin' }` when
+ * no known magic matches.
+ */
+export declare function sniffImageFormat(buf: Uint8Array | Buffer): SniffResult;
+/**
+ * Write image bytes to disk, using the sniffed extension instead of the
+ * caller-supplied extension when they disagree.
+ *
+ * Returns the final on-disk path. When `requestedPath` says `.png` but the
+ * buffer is actually WebP, the file is written as `<base>.webp` and a
+ * `console.warn` records the mismatch. Pass `forceExt: true` to keep the
+ * caller's extension (useful when downstream tooling really does need a
+ * fixed name, even if the format is a lie — but transcode first when you can).
+ */
+export declare function writeImageBytesSmart(buf: Buffer, requestedPath: string, opts?: {
+    forceExt?: boolean;
+}): Promise<string>;
+//# sourceMappingURL=image-bytes.d.ts.map

package/dist/venice/image-bytes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-bytes.d.ts","sourceRoot":"","sources":["../../src/venice/image-bytes.ts"],"names":[],"mappings":"AAqBA,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,SAAS,CAAC;AAE/E,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,WAAW,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb;AA+CD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,GAAG,WAAW,CAKtE;AAED;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,MAAM,EACX,aAAa,EAAE,MAAM,EACrB,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GAC5B,OAAO,CAAC,MAAM,CAAC,CAgBjB"}

package/dist/venice/image-bytes.js

@@ -0,0 +1,101 @@
+// ---------------------------------------------------------------------------
+// Image-format byte sniffing.
+//
+// Seedream sometimes returns WebP bytes when callers asked for PNG. The
+// harness used to write them with a `.png` extension anyway, which confuses
+// downstream consumers (older ffmpeg, macOS Preview, image-tag thumbnailers,
+// and the silent-reject heuristic that uses byte-size thresholds calibrated
+// for PNG at 1K).
+//
+// `sniffImageFormat` inspects the leading magic bytes and returns the real
+// MIME type plus a canonical file extension. `writeImageBytesSmart` writes
+// the buffer to disk using the sniffed extension; if a `forceExt` is
+// provided, the buffer is written under the requested name AND a sibling
+// file with the sniffed extension is written too — so callers that hardcode
+// `front.png` get the file at `front.png` AND know the real format via
+// `front.webp` if a transcode is needed.
+// ---------------------------------------------------------------------------
+import { writeFile } from 'node:fs/promises';
+import { extname, join, dirname, basename } from 'node:path';
+const SNIFFERS = [
+    {
+        format: 'png',
+        mime: 'image/png',
+        ext: '.png',
+        // 89 50 4E 47 0D 0A 1A 0A
+        match: b => b.length >= 8 &&
+            b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4E && b[3] === 0x47 &&
+            b[4] === 0x0D && b[5] === 0x0A && b[6] === 0x1A && b[7] === 0x0A,
+    },
+    {
+        format: 'jpeg',
+        mime: 'image/jpeg',
+        ext: '.jpg',
+        // FF D8 FF
+        match: b => b.length >= 3 && b[0] === 0xFF && b[1] === 0xD8 && b[2] === 0xFF,
+    },
+    {
+        format: 'webp',
+        mime: 'image/webp',
+        ext: '.webp',
+        // 52 49 46 46  XX XX XX XX  57 45 42 50  -> "RIFF....WEBP"
+        match: b => b.length >= 12 &&
+            b[0] === 0x52 && b[1] === 0x49 && b[2] === 0x46 && b[3] === 0x46 &&
+            b[8] === 0x57 && b[9] === 0x45 && b[10] === 0x42 && b[11] === 0x50,
+    },
+    {
+        format: 'gif',
+        mime: 'image/gif',
+        ext: '.gif',
+        // 47 49 46 38 (37|39) 61   "GIF87a" or "GIF89a"
+        match: b => b.length >= 6 && b[0] === 0x47 && b[1] === 0x49 && b[2] === 0x46 && b[3] === 0x38 &&
+            (b[4] === 0x37 || b[4] === 0x39) && b[5] === 0x61,
+    },
+    {
+        format: 'avif',
+        mime: 'image/avif',
+        ext: '.avif',
+        // ftyp box at offset 4: 'ftyp' then major brand 'avif'/'avis'
+        match: b => b.length >= 12 &&
+            b[4] === 0x66 && b[5] === 0x74 && b[6] === 0x79 && b[7] === 0x70 &&
+            b[8] === 0x61 && b[9] === 0x76 && b[10] === 0x69 && (b[11] === 0x66 || b[11] === 0x73),
+    },
+];
+/**
+ * Inspect the leading bytes of `buf` and return the image format. Returns
+ * `{ format: 'unknown', mime: 'application/octet-stream', ext: '.bin' }` when
+ * no known magic matches.
+ */
+export function sniffImageFormat(buf) {
+    for (const s of SNIFFERS) {
+        if (s.match(buf))
+            return { format: s.format, mime: s.mime, ext: s.ext };
+    }
+    return { format: 'unknown', mime: 'application/octet-stream', ext: '.bin' };
+}
+/**
+ * Write image bytes to disk, using the sniffed extension instead of the
+ * caller-supplied extension when they disagree.
+ *
+ * Returns the final on-disk path. When `requestedPath` says `.png` but the
+ * buffer is actually WebP, the file is written as `<base>.webp` and a
+ * `console.warn` records the mismatch. Pass `forceExt: true` to keep the
+ * caller's extension (useful when downstream tooling really does need a
+ * fixed name, even if the format is a lie — but transcode first when you can).
+ */
+export async function writeImageBytesSmart(buf, requestedPath, opts) {
+    const sniff = sniffImageFormat(buf);
+    const requestedExt = extname(requestedPath).toLowerCase();
+    const expected = sniff.ext.toLowerCase();
+    if (sniff.format === 'unknown' || opts?.forceExt || requestedExt === expected) {
+        await writeFile(requestedPath, buf);
+        return requestedPath;
+    }
+    const dir = dirname(requestedPath);
+    const base = basename(requestedPath, requestedExt);
+    const correctedPath = join(dir, `${base}${sniff.ext}`);
+    await writeFile(correctedPath, buf);
+    console.warn(`  image-bytes: requested ${requestedPath} (${requestedExt || '<no ext>'}) but bytes are ${sniff.format}; wrote ${correctedPath} instead.`);
+    return correctedPath;
+}
+//# sourceMappingURL=image-bytes.js.map

package/dist/venice/image-bytes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-bytes.js","sourceRoot":"","sources":["../../src/venice/image-bytes.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,8BAA8B;AAC9B,EAAE;AACF,wEAAwE;AACxE,4EAA4E;AAC5E,6EAA6E;AAC7E,4EAA4E;AAC5E,kBAAkB;AAClB,EAAE;AACF,2EAA2E;AAC3E,2EAA2E;AAC3E,qEAAqE;AACrE,yEAAyE;AACzE,4EAA4E;AAC5E,uEAAuE;AACvE,yCAAyC;AACzC,8EAA8E;AAE9E,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAU7D,MAAM,QAAQ,GAAiG;IAC7G;QACE,MAAM,EAAE,KAAK;QACb,IAAI,EAAE,WAAW;QACjB,GAAG,EAAE,MAAM;QACX,0BAA0B;QAC1B,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC;YACvB,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI;YAChE,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI;KACnE;IACD;QACE,MAAM,EAAE,MAAM;QACd,IAAI,EAAE,YAAY;QAClB,GAAG,EAAE,MAAM;QACX,WAAW;QACX,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI;KAC7E;IACD;QACE,MAAM,EAAE,MAAM;QACd,IAAI,EAAE,YAAY;QAClB,GAAG,EAAE,OAAO;QACZ,2DAA2D;QAC3D,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,EAAE;YACxB,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI;YAChE,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC,KAAK,IAAI;KACrE;IACD;QACE,MAAM,EAAE,KAAK;QACb,IAAI,EAAE,WAAW;QACjB,GAAG,EAAE,MAAM;QACX,gDAAgD;QAChD,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI;YAC3F,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI;KACpD;IACD;QACE,MAAM,EAAE,MAAM;QACd,IAAI,EAAE,YAAY;QAClB,GAAG,EAAE,OAAO;QACZ,8DAA8D;QAC9D,KAAK,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,EAAE;YACxB,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI;YAChE,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC,KAAK,IAAI,CAAC;KACzF;CACF,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAwB;IACvD,KAAK,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QACzB,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC;YAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC;IAC1E,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,0BAA0B,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC;AAC9E,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,GAAW,EACX,aAAqB,EACrB,IAA6B;IAE7B,MAAM,KAAK,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACpC,MAAM,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC,WAAW,EAAE,CAAC;IAC1D,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC;IACzC,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,IAAI,EAAE,QAAQ,IAAI,YAAY,KAAK,QAAQ,EAAE,CAAC;QAC9E,MAAM,SAAS,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC;QACpC,OAAO,aAAa,CAAC;IACvB,CAAC;IACD,MAAM,GAAG,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACnC,MAAM,IAAI,GAAG,QAAQ,CAAC,aAAa,EAAE,YAAY,CAAC,CAAC;IACnD,MAAM,aAAa,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,GAAG,KAAK,CAAC,GAAG,EAAE,CAAC,CAAC;IACvD,MAAM,SAAS,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC;IACpC,OAAO,CAAC,IAAI,CACV,4BAA4B,aAAa,KAAK,YAAY,IAAI,UAAU,mBAAmB,KAAK,CAAC,MAAM,WAAW,aAAa,WAAW,CAC3I,CAAC;IACF,OAAO,aAAa,CAAC;AACvB,CAAC"}

package/dist/venice/models.d.ts

@@ -0,0 +1,143 @@
+export type VideoModelType = 'image-to-video' | 'text-to-video';
+export interface VideoModelSpec {
+    id: string;
+    name: string;
+    type: VideoModelType;
+    durations: string[];
+    resolutions: string[];
+    aspectRatios: string[];
+    audio: boolean;
+    audioConfigurable: boolean;
+    audioInput: boolean;
+    videoInput: boolean;
+    /** Supports structured `elements` with @Element1/@Element2 prompt refs */
+    supportsElements: boolean;
+    /** Supports flat `reference_image_urls` array */
+    supportsReferenceImages: boolean;
+    /** Supports `scene_image_urls` for environment/style anchoring */
+    supportsSceneImages: boolean;
+    /** Supports `end_image_url` for targeted ending composition */
+    supportsEndImage: boolean;
+    /** Max duration in seconds */
+    maxDurationSec: number;
+    /**
+     * Supports per-reference audio (Wan 2.7 R2V): each `elements[].audio_url`
+     * can drive a different speaker's lip-sync inside a single render.
+     */
+    perReferenceAudio?: boolean;
+    /**
+     * Supports `reference_audio_urls` — voice-donor clips (up to 3, 2-15s each,
+     * ≤15s aggregate, wav/mp3, ≤15MB per file) bound in-prompt as @Audio1,
+     * @Audio2, … so a character's voice (timbre / accent / pacing) stays
+     * consistent across shots. Must be paired with ≥1 reference image (Venice
+     * rejects audio-only requests at validation). Distinct from `audioInput`
+     * (lip-sync `audio_url`): these four R2V models accept reference audio but
+     * do NOT set `audio_input: true` in GET /models. Confirmed live via
+     * /video/quote (HTTP 200) 2026-07-23.
+     */
+    supportsReferenceAudio?: boolean;
+    /**
+     * Minimum allowed duration (seconds) for `audio_url` input.
+     * Wan 2.7 rejects audio shorter than 3 seconds. Use the pre-flight
+     * helper in `src/venice/audio-preflight.ts` to pad shorter clips.
+     */
+    minAudioInputSec?: number;
+    privacy: 'private' | 'anonymized';
+    offline: boolean;
+}
+/**
+ * Per-image-model positive-prompt length caps.
+ *
+ * Venice silently rejects requests with overly long positive prompts on
+ * certain models (observed at ~1800-2200 chars on seedream-v5-lite; the
+ * mini-drama character-reference builder used to emit 2400+ char prompts).
+ *
+ * Default cap is intentionally conservative (300 chars). Callers should
+ * keep the most-important style cue + character anchor inline and move
+ * everything else to negative_prompt.
+ */
+export declare const DEFAULT_MAX_POSITIVE_PROMPT_CHARS = 300;
+export declare const MAX_POSITIVE_PROMPT_CHARS: Record<string, number>;
+/**
+ * Look up the positive-prompt cap for an image-generation model.
+ * Falls back to DEFAULT_MAX_POSITIVE_PROMPT_CHARS when unspecified.
+ */
+export declare function getMaxPositivePromptChars(modelId: string): number;
+export declare const VIDEO_MODELS: VideoModelSpec[];
+export interface ImageModelSpec {
+    id: string;
+    name: string;
+    type: 'generation' | 'edit' | 'upscale' | 'background-remove';
+    offline: boolean;
+}
+export declare const IMAGE_GENERATION_MODELS: ImageModelSpec[];
+export declare const MULTI_EDIT_MODELS: readonly ["qwen-edit", "qwen-image-2-edit", "qwen-image-2-pro-edit", "flux-2-max-edit", "gpt-image-1-5-edit", "gpt-image-2-edit", "grok-imagine-edit", "nano-banana-2-edit", "nano-banana-pro-edit", "seedream-v4-edit", "seedream-v5-lite-edit"];
+export type MultiEditModelId = typeof MULTI_EDIT_MODELS[number];
+export interface MusicModelSpec {
+    id: string;
+    name: string;
+    type: 'music' | 'sound-effects' | 'tts';
+    offline: boolean;
+    /** Selectable voices (voice-enabled models). `default_voice` first if known. */
+    voices?: string[];
+    /** Default voice id. For seed-audio this is the sentinel "Describe in prompt". */
+    defaultVoice?: string;
+    /** `speed` param support + bounds. */
+    supportsSpeed?: boolean;
+    minSpeed?: number;
+    maxSpeed?: number;
+    defaultSpeed?: number;
+    /** Lyrics / instrumental behaviour. */
+    supportsLyrics?: boolean;
+    lyricsRequired?: boolean;
+    supportsForceInstrumental?: boolean;
+    supportsLanguageCode?: boolean;
+    /** Output containers the model can emit (`response_format` on retrieve). */
+    supportedFormats?: string[];
+    defaultFormat?: string;
+    /** Prompt length bounds, in characters. */
+    promptCharacterLimit?: number;
+    minPromptLength?: number;
+    /** Default generation length in seconds. */
+    defaultDurationSec?: number;
+    /** Per-second price in USD (for budgeting without a `/audio/quote` round-trip). */
+    pricingPerSecondUsd?: number;
+    /** One-line human summary. */
+    description?: string;
+}
+export declare const MUSIC_MODELS: MusicModelSpec[];
+export declare const TTS_MODELS: readonly ["tts-kokoro", "tts-qwen3-0-6b", "tts-qwen3-1-7b"];
+export type TTSModelId = typeof TTS_MODELS[number];
+export declare function getVideoModel(id: string): VideoModelSpec | undefined;
+export declare function getMusicModel(id: string): MusicModelSpec | undefined;
+export declare function listMusicModels(filter?: {
+    type?: MusicModelSpec['type'];
+}): MusicModelSpec[];
+export declare function listVideoModels(filter?: {
+    type?: VideoModelType;
+    audio?: boolean;
+    minDurationSec?: number;
+    supportsElements?: boolean;
+    supportsReferenceImages?: boolean;
+    supportsEndImage?: boolean;
+    imageToVideo?: boolean;
+}): VideoModelSpec[];
+/**
+ * Check if a model supports a given duration string (e.g. "8s").
+ * Falls back to checking max duration if the duration is within range.
+ */
+export declare function modelSupportsDuration(modelId: string, duration: string): boolean;
+/**
+ * For a given model, return the closest valid duration to the requested one.
+ */
+export declare function closestValidDuration(modelId: string, requestedSec: number): string | undefined;
+/**
+ * Build the model-specific parameters for a video queue request.
+ * Handles resolution, aspect_ratio, and end_image_url based on model capabilities.
+ */
+export declare function buildModelParams(modelId: string, opts: {
+    aspectRatio?: string;
+    resolution?: string;
+    endImageUrl?: string;
+}): Record<string, unknown>;
+//# sourceMappingURL=models.d.ts.map

package/dist/venice/models.d.ts.map

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