@fungi.computer/darkroom 0.0.0-stage → 0.0.1

package/dist/browser.js

@@ -0,0 +1 @@
+export { mediaFailureSchema, readMediaFailure } from "./browser-failure.js";

package/dist/cloudflare/provider.d.ts

@@ -0,0 +1,13 @@
+import { type MediaAiResult, type MediaGenerationSettings, type MediaProvider, type MediaReferenceBytes } from "../index.js";
+/** Workers AI results vary by model; the provider decodes them at this boundary. */
+export type MediaAiPort = {
+    /** Dispatch to the native Workers AI binding. */
+    run(model: string, input: Parameters<Ai["run"]>[1], options?: AiOptions): Promise<MediaAiResult>;
+};
+export declare function estimate(settings: MediaGenerationSettings, references: readonly MediaReferenceBytes[]): number;
+export declare function generate(ai: MediaAiPort, settings: MediaGenerationSettings, references: readonly MediaReferenceBytes[], signal?: AbortSignal, options?: AiOptions, fetchResult?: typeof fetch, outputFormat?: "png" | "jpeg" | "webp"): Promise<{
+    bytes: Uint8Array;
+    format: string;
+}>;
+/** Media's provider port on the Workers AI binding, with fixed options such as the AI Gateway route. */
+export declare function createWorkersAiMediaProvider(ai: MediaAiPort, options?: AiOptions): MediaProvider;

package/dist/cloudflare/provider.js

@@ -0,0 +1,140 @@
+import { z } from "zod";
+import * as Redacted from "effect/Redacted";
+import { buildProviderInput, getMediaModel, estimateImageMilliunits, normalizeMediaProviderOutput, mediaProviderWireSchema, } from "../index.js";
+import { MediaExecutionError, MediaSafetyFilterRefusal, } from "../execution-error.js";
+import { estimateGatewayMilliunits, gatewayInput, isGatewayModel, } from "../gateway-models.js";
+import { GATEWAY_VIDEO_MAX_BYTES, gatewayOutputSchema, isMp4, } from "../gateway-wire.js";
+import { videoProviderAdapters } from "../video-providers/index.js";
+import { readResponseBytes } from "../index.js";
+export function estimate(settings, references) {
+    const params = {
+        width: settings.width,
+        height: settings.height,
+        references: references.map(({ width, height }) => ({ width, height })),
+    };
+    if (settings.steps !== undefined)
+        params.steps = settings.steps;
+    try {
+        if (isGatewayModel(settings.model))
+            return estimateGatewayMilliunits(settings);
+        return estimateImageMilliunits(settings.model, params);
+    }
+    catch (cause) {
+        throw new MediaExecutionError("estimate", { cause });
+    }
+}
+// Workers AI prefixes upstream error messages with its numeric internal code.
+// Parse only that bounded identifier; the remaining message is never logged.
+const providerFailureCode = z
+    .string()
+    .regex(/^\d{4,5}: /u)
+    .transform((message) => Number(message.split(":", 1)[0]))
+    .nullable()
+    .catch(null);
+const providerFailureCategory = z
+    .enum([
+    "InferenceUpstreamError",
+    "AiInternalError",
+    "TypeError",
+    "AbortError",
+    "TimeoutError",
+    "Error",
+])
+    .catch("Error");
+// Recognize the refusal, not the generic Workers AI error number or prompt text.
+const safetyFilterMessage = z.union([
+    z
+        .string()
+        .regex(/(?:^|:\s)(?:AiError:\s)?Input prompt contains NSFW content\b/iu),
+    // Veo's documented input-policy refusal; keep its details private as well.
+    // https://docs.cloud.google.com/vertex-ai/generative-ai/docs/video/responsible-ai-and-usage-guidelines
+    z.string().regex(/\bit might violate our policies\b/iu),
+]);
+/** Encode multipart once with the platform's boundary, as required by AI.run. */
+function workersAiInput(payload) {
+    if (payload.transport === "json")
+        return { ...payload.body };
+    const encoded = new Response(payload.body);
+    return {
+        multipart: {
+            body: encoded.body,
+            contentType: encoded.headers.get("Content-Type"),
+        },
+    };
+}
+/** Retain the original provider failure alongside its bounded code and category. */
+function providerFailure(model, cause) {
+    // Workers correlates this structured event with the request trace. Never log
+    // the provider message/body: either can contain customer prompt content.
+    console.error("Media provider request failed", {
+        model,
+        providerCode: providerFailureCode.parse(cause instanceof Error ? cause.message : undefined),
+        category: providerFailureCategory.parse(cause instanceof Error ? cause.name : undefined),
+    }, Redacted.make(cause));
+    return cause instanceof Error &&
+        safetyFilterMessage.safeParse(cause.message).success
+        ? new MediaSafetyFilterRefusal({ cause })
+        : new MediaExecutionError("provider", { cause });
+}
+/** Run a gateway model and fetch its result URL within the byte bound. */
+async function generateThroughGateway(ai, settings, references, signal, options, fetchResult, outputFormat) {
+    let providerValue;
+    try {
+        const input = gatewayInput(settings, references, outputFormat);
+        providerValue = await ai.run(settings.model, input, signal === undefined ? options : { ...options, signal });
+    }
+    catch (cause) {
+        throw providerFailure(settings.model, cause);
+    }
+    const model = getMediaModel(settings.model);
+    const video = model?.kind === "video";
+    try {
+        if (video) {
+            if (model.video === null)
+                throw new Error("video model is missing its catalog video metadata");
+            const url = videoProviderAdapters[model.video.provider].decodeResultUrl(providerValue);
+            const response = await fetchResult(url, { signal: signal ?? null });
+            if (!response.ok)
+                throw new Error("gateway video result unavailable");
+            const bytes = await readResponseBytes(response, GATEWAY_VIDEO_MAX_BYTES);
+            if (!isMp4(bytes))
+                throw new Error("gateway video is not an MP4");
+            return { bytes, format: "mp4" };
+        }
+        const parsed = gatewayOutputSchema.parse(providerValue);
+        return await normalizeMediaProviderOutput(mediaProviderWireSchema.parse({
+            images: [{ url: parsed.result.image }],
+        }), { fetchUrl: (url) => fetchResult(url, { signal: signal ?? null }) });
+    }
+    catch (cause) {
+        throw new MediaExecutionError("normalization", { cause });
+    }
+}
+export async function generate(ai, settings, references, signal, options, fetchResult = (input, init) => fetch(input, init), outputFormat) {
+    if (isGatewayModel(settings.model))
+        return generateThroughGateway(ai, settings, references, signal, options, fetchResult, outputFormat);
+    let providerInput;
+    try {
+        providerInput = buildProviderInput(settings, references);
+    }
+    catch (cause) {
+        throw new MediaExecutionError("normalization", { cause });
+    }
+    let providerValue;
+    try {
+        providerValue = await ai.run(settings.model, workersAiInput(providerInput), signal === undefined ? options : { ...options, signal });
+    }
+    catch (cause) {
+        throw providerFailure(settings.model, cause);
+    }
+    try {
+        return await normalizeMediaProviderOutput(mediaProviderWireSchema.parse(providerValue));
+    }
+    catch (cause) {
+        throw new MediaExecutionError("normalization", { cause });
+    }
+}
+/** Media's provider port on the Workers AI binding, with fixed options such as the AI Gateway route. */
+export function createWorkersAiMediaProvider(ai, options) {
+    return (settings, references, signal, outputFormat) => generate(ai, settings, references, signal, options, undefined, outputFormat);
+}

package/dist/cloudflare/reference-images.d.ts

@@ -0,0 +1,42 @@
+import { type ImageViewFitter, type ReferenceImageFitter } from "../index.js";
+/** Only image metadata and the bounded resize chain are consumed by Media. */
+export type MediaImagePort = {
+    /** Read decoded image metadata through the Images binding. */
+    info(input: ReadableStream<Uint8Array>): ReturnType<ImagesBinding["info"]>;
+    /** Start the native resize and encode chain. */
+    input(input: ReadableStream<Uint8Array>): {
+        /** Apply the native scale-down transform. */
+        transform(options: {
+            /** Image width in pixels. */
+            width: number;
+            /** Image height in pixels. */
+            height: number;
+            fit: "scale-down";
+        }): {
+            /** Encode the transformed image through the native Images binding. */
+            output(options: {
+                /** Actual output encoding. */
+                format: "image/png";
+            } | {
+                /** Actual output encoding. */
+                format: "image/jpeg";
+                quality: number;
+            }): Promise<{
+                /** Provider response or encoded image response. */
+                response(): Response;
+            }>;
+        };
+    };
+};
+/**
+ * Media's reference preparation on the Images binding: decode the real bytes,
+ * scale an oversized image down to MAX_REFERENCE_DIMENSION as PNG, then decode
+ * the output so its metadata describes the bytes actually sent.
+ */
+export declare function createImagesReferenceFitter(images: MediaImagePort): ReferenceImageFitter;
+/**
+ * Fit one image for a model to look at on the Images binding: always
+ * re-encode it as JPEG (quality 80), scaled down within `maxDimension`, and
+ * decode the output so its metadata describes the bytes actually returned.
+ */
+export declare function createImagesViewFitter(images: MediaImagePort): ImageViewFitter;

package/dist/cloudflare/reference-images.js

@@ -0,0 +1,102 @@
+import { z } from "zod";
+import { MAX_REFERENCE_BYTES, MAX_REFERENCE_DIMENSION, MediaSettingsError, viewDimensionSchema, } from "../index.js";
+/** The retained `read_image` encoding: JPEG at quality 80. */
+const VIEW_JPEG_QUALITY = 80;
+const metadata = z.object({
+    format: z.enum(["image/png", "image/jpeg", "image/gif", "image/webp"]),
+    width: z.number().int().positive(),
+    height: z.number().int().positive(),
+});
+const formats = {
+    "image/png": "png",
+    "image/jpeg": "jpeg",
+    "image/gif": "gif",
+    "image/webp": "webp",
+};
+const stream = (bytes) => new ReadableStream({
+    start(controller) {
+        controller.enqueue(bytes.slice());
+        controller.close();
+    },
+});
+/**
+ * Media's reference preparation on the Images binding: decode the real bytes,
+ * scale an oversized image down to MAX_REFERENCE_DIMENSION as PNG, then decode
+ * the output so its metadata describes the bytes actually sent.
+ */
+export function createImagesReferenceFitter(images) {
+    return async (input) => {
+        let bytes = input;
+        let info;
+        try {
+            info = metadata.parse(await images.info(stream(bytes)));
+        }
+        catch {
+            // The Images failure detail is never surfaced; the caller's bytes are.
+            throw new MediaSettingsError("reference image is not a supported image");
+        }
+        if (info.width > MAX_REFERENCE_DIMENSION ||
+            info.height > MAX_REFERENCE_DIMENSION) {
+            const output = await images
+                .input(stream(bytes))
+                .transform({
+                width: MAX_REFERENCE_DIMENSION,
+                height: MAX_REFERENCE_DIMENSION,
+                fit: "scale-down",
+            })
+                .output({
+                format: "image/png",
+            });
+            bytes = new Uint8Array(await output.response().arrayBuffer());
+            if (bytes.byteLength === 0 || bytes.byteLength > MAX_REFERENCE_BYTES)
+                throw new MediaSettingsError("reference image exceeds the byte limit");
+            info = metadata.parse(await images.info(stream(bytes)));
+        }
+        return {
+            bytes,
+            format: formats[info.format],
+            width: info.width,
+            height: info.height,
+        };
+    };
+}
+/**
+ * Fit one image for a model to look at on the Images binding: always
+ * re-encode it as JPEG (quality 80), scaled down within `maxDimension`, and
+ * decode the output so its metadata describes the bytes actually returned.
+ */
+export function createImagesViewFitter(images) {
+    return async (input, maxDimension) => {
+        const bound = viewDimensionSchema.safeParse(maxDimension);
+        if (!bound.success)
+            throw new MediaSettingsError("view dimension is out of bounds");
+        try {
+            metadata.parse(await images.info(stream(input)));
+        }
+        catch {
+            // The Images failure detail is never surfaced.
+            throw new MediaSettingsError("image is not a supported image");
+        }
+        const output = await images
+            .input(stream(input))
+            .transform({
+            width: bound.data,
+            height: bound.data,
+            fit: "scale-down",
+        })
+            .output({
+            format: "image/jpeg",
+            quality: VIEW_JPEG_QUALITY,
+        });
+        const bytes = new Uint8Array(await output.response().arrayBuffer());
+        if (bytes.byteLength === 0 || bytes.byteLength > MAX_REFERENCE_BYTES)
+            throw new MediaSettingsError("image exceeds the byte limit");
+        const info = metadata.parse(await images.info(stream(bytes)));
+        return {
+            bytes,
+            format: formats[info.format],
+            width: info.width,
+            height: info.height,
+        };
+    };
+}

package/dist/cloudflare.d.ts

@@ -0,0 +1,6 @@
+export { MediaOperationDO, type MediaOperationCloudflareEnvironment, type MediaOperationCoordinates, type MediaOperationRequest, } from "./media-operation-do.js";
+export { createWorkersAiMediaProvider, type MediaAiPort, } from "./cloudflare/provider.js";
+export type { MediaAiResult } from "./index.js";
+export { createImagesReferenceFitter, createImagesViewFitter, type MediaImagePort, } from "./cloudflare/reference-images.js";
+export { MediaOperationOwner } from "./media-operation-owner.js";
+export type { MediaOperationContext, MediaOperationStorage, MediaOperationBucket, MediaOperationObject, } from "./media-operation-storage.js";

package/dist/cloudflare.js

@@ -0,0 +1,4 @@
+export { MediaOperationDO, } from "./media-operation-do.js";
+export { createWorkersAiMediaProvider, } from "./cloudflare/provider.js";
+export { createImagesReferenceFitter, createImagesViewFitter, } from "./cloudflare/reference-images.js";
+export { MediaOperationOwner } from "./media-operation-owner.js";

package/dist/cost-estimate.d.ts

@@ -0,0 +1,22 @@
+/** Dimensions and optional settings used by the deterministic image quote. */
+export type ImageParams = {
+    /** Output height in pixels. */
+    readonly height: number;
+    /** Reference dimensions counted in the quote. */
+    readonly references?: readonly ImageReference[];
+    /** Inference steps, using catalog defaults when omitted. */
+    readonly steps?: number;
+    /** Output width in pixels. */
+    readonly width: number;
+};
+/** Reference-image dimensions used to estimate provider work. */
+export type ImageReference = {
+    /** Reference height in pixels. */
+    readonly height: number;
+    /** Reference width in pixels. */
+    readonly width: number;
+};
+/** Estimate Workers AI neurons from a validated image request. */
+export declare const estimateImageNeurons: (modelId: string, params: ImageParams) => number;
+/** Quote the same estimate in milliunits (1 cent = 1,000 milliunits). */
+export declare const estimateImageMilliunits: (modelId: string, params: ImageParams) => number;

package/dist/cost-estimate.js

@@ -0,0 +1,76 @@
+import { getMediaModel, MediaSettingsError } from "./model-catalog.js";
+import { neuronsToMilliunits } from "./neurons.js";
+import * as z from "zod";
+const TILE = 512;
+const MAX_DIMENSION = 4_096;
+const MAX_REFERENCES = 4;
+const imageParamsSchema = z
+    .object({
+    width: z.number().int().min(1).max(MAX_DIMENSION),
+    height: z.number().int().min(1).max(MAX_DIMENSION),
+    steps: z.number().int().min(1).optional(),
+    references: z
+        .array(z
+        .object({
+        width: z.number().int().min(1).max(MAX_DIMENSION),
+        height: z.number().int().min(1).max(MAX_DIMENSION),
+    })
+        .strict())
+        .max(MAX_REFERENCES)
+        .optional(),
+})
+    .strict();
+const invalid = (message) => {
+    throw new MediaSettingsError(`image cost parameters are invalid: ${message}`);
+};
+const tiles = (width, height) => Math.ceil(width / TILE) * Math.ceil(height / TILE);
+const checked = (modelId, params) => {
+    const parsed = imageParamsSchema.safeParse(params);
+    if (!parsed.success)
+        return invalid("dimensions, steps, or references are invalid");
+    const candidate = parsed.data;
+    const references = candidate.references ?? [];
+    const model = getMediaModel(modelId);
+    if (model === undefined)
+        throw new MediaSettingsError(`Image cost unknown for model "${modelId}"`);
+    if (references.length > model.input.maxReferences)
+        return invalid(`${modelId} does not accept references`);
+    const normalized = {
+        width: candidate.width,
+        height: candidate.height,
+        references,
+    };
+    if (candidate.steps !== undefined)
+        return { ...normalized, steps: candidate.steps };
+    return normalized;
+};
+/** Estimate Workers AI neurons from a validated image request. */
+export const estimateImageNeurons = (modelId, params) => {
+    const p = checked(modelId, params);
+    const outputTiles = tiles(p.width, p.height);
+    const inputTiles = (p.references ?? []).reduce((sum, reference) => sum + tiles(reference.width, reference.height), 0);
+    switch (modelId) {
+        case "@cf/black-forest-labs/flux-1-schnell":
+            return outputTiles * 4.8 + (p.steps ?? 4) * 9.6;
+        case "@cf/black-forest-labs/flux-2-klein-4b":
+            return inputTiles * 5.37 + outputTiles * 26.05;
+        case "@cf/black-forest-labs/flux-2-dev":
+            return (inputTiles * (p.steps ?? 20) * 19.09 +
+                outputTiles * (p.steps ?? 20) * 37.27);
+        case "@cf/black-forest-labs/flux-2-klein-9b": {
+            const outputMp = (p.width / 1024) * (p.height / 1024);
+            const outputCost = Math.min(outputMp, 1) * 1363.64 + Math.max(0, outputMp - 1) * 181.82;
+            const inputMp = (p.references ?? []).reduce((sum, reference) => sum + (reference.width / 1024) * (reference.height / 1024), 0);
+            return (outputMp < 1 ? 1363.64 : outputCost) + inputMp * 181.82;
+        }
+        case "@cf/leonardo/lucid-origin":
+            return outputTiles * 636 + (p.steps ?? 20) * 12;
+        case "@cf/leonardo/phoenix-1.0":
+            return outputTiles * 530 + (p.steps ?? 25) * 10;
+        default:
+            // checked() owns this rejection; keep the switch exhaustive at runtime.
+            throw new MediaSettingsError(`Image cost unknown for model "${modelId}"`);
+    }
+};
+/** Quote the same estimate in milliunits (1 cent = 1,000 milliunits). */
+export const estimateImageMilliunits = (modelId, params) => neuronsToMilliunits(estimateImageNeurons(modelId, params));

package/dist/effect.d.ts

@@ -0,0 +1,2 @@
+/** Advanced Effect port; ordinary native consumers use the Promise and HTTP server boundary. */
+export { runMediaGeneration } from "./media-generation.js";

package/dist/effect.js

@@ -0,0 +1,2 @@
+/** Advanced Effect port; ordinary native consumers use the Promise and HTTP server boundary. */
+export { runMediaGeneration } from "./media-generation.js";

package/dist/execution-error.d.ts

@@ -0,0 +1,54 @@
+import * as z from "zod";
+/** Public diagnostic labels only; never provider messages or request data. */
+export declare const mediaFailureStageSchema: z.ZodEnum<{
+    /** Host admission before operation creation. */
+    readonly admission: "admission";
+    /** Host authority check before dispatch. */
+    readonly "generation-authorization": "generation-authorization";
+    /** Generation settings validation. */
+    readonly settings: "settings";
+    /** Reference preparation and cost estimation. */
+    readonly estimate: "estimate";
+    /** Host price admission or settlement. */
+    readonly billing: "billing";
+    /** Durable operation transition. */
+    readonly operation: "operation";
+    /** Provider dispatch. */
+    readonly provider: "provider";
+    /** Provider output decoding. */
+    readonly normalization: "normalization";
+    /** Retained output storage. */
+    readonly artifact: "artifact";
+    /** Host permission check before saving. */
+    readonly "destination-authorization": "destination-authorization";
+    /** Host destination write. */
+    readonly "destination-write": "destination-write";
+}>;
+/** Execution stage at which a generation failed. */
+export type MediaFailureStage = Exclude<z.output<typeof mediaFailureStageSchema>, "admission" | "settings">;
+/** A bounded stage marker for failures that cross the Media HTTP boundary. */
+export declare class MediaExecutionError extends Error {
+    /** Execution stage where the failure occurred. */
+    readonly stage: MediaFailureStage;
+    constructor(
+    /** Execution stage where the failure occurred. */
+    stage: MediaFailureStage, options?: ErrorOptions);
+}
+/** A provider safety filter refused generation; no output was delivered. */
+export declare class MediaSafetyFilterRefusal extends MediaExecutionError {
+    constructor(options?: ErrorOptions);
+}
+/** Why the host's billing owner refused to admit a new generation. */
+export type MediaBillingRefusalCode = "insufficient_credits" | "daily_limit_reached" | "denied";
+/** A definitive billing refusal before dispatch; nothing was generated or charged. */
+export declare class MediaBillingRefusal extends Error {
+    /** Bounded refusal or failure reason. */
+    readonly code: MediaBillingRefusalCode;
+    constructor(
+    /** Bounded refusal or failure reason. */
+    code: MediaBillingRefusalCode);
+}
+/** The durable format pin prevents a mismatched file extension or retained output. */
+export declare class MediaOutputFormatMismatch extends Error {
+    constructor();
+}

package/dist/execution-error.js

@@ -0,0 +1,62 @@
+import * as z from "zod";
+/** Public diagnostic labels only; never provider messages or request data. */
+export const mediaFailureStageSchema = z.enum({
+    /** Host admission before operation creation. */
+    admission: "admission",
+    /** Host authority check before dispatch. */
+    "generation-authorization": "generation-authorization",
+    /** Generation settings validation. */
+    settings: "settings",
+    /** Reference preparation and cost estimation. */
+    estimate: "estimate",
+    /** Host price admission or settlement. */
+    billing: "billing",
+    /** Durable operation transition. */
+    operation: "operation",
+    /** Provider dispatch. */
+    provider: "provider",
+    /** Provider output decoding. */
+    normalization: "normalization",
+    /** Retained output storage. */
+    artifact: "artifact",
+    /** Host permission check before saving. */
+    "destination-authorization": "destination-authorization",
+    /** Host destination write. */
+    "destination-write": "destination-write",
+});
+/** A bounded stage marker for failures that cross the Media HTTP boundary. */
+export class MediaExecutionError extends Error {
+    stage;
+    constructor(
+    /** Execution stage where the failure occurred. */
+    stage, options) {
+        super(`Media ${stage} failed`, options);
+        this.stage = stage;
+        this.name = "MediaExecutionError";
+    }
+}
+/** A provider safety filter refused generation; no output was delivered. */
+export class MediaSafetyFilterRefusal extends MediaExecutionError {
+    constructor(options) {
+        super("provider", options);
+        this.name = "MediaSafetyFilterRefusal";
+    }
+}
+/** A definitive billing refusal before dispatch; nothing was generated or charged. */
+export class MediaBillingRefusal extends Error {
+    code;
+    constructor(
+    /** Bounded refusal or failure reason. */
+    code) {
+        super(`Media billing refused: ${code}`);
+        this.code = code;
+        this.name = "MediaBillingRefusal";
+    }
+}
+/** The durable format pin prevents a mismatched file extension or retained output. */
+export class MediaOutputFormatMismatch extends Error {
+    constructor() {
+        super("Media provider did not return the requested image format");
+        this.name = "MediaOutputFormatMismatch";
+    }
+}

package/dist/failure.d.ts

@@ -0,0 +1,2 @@
+/** Retain the original failure without printing provider or customer data. */
+export declare function reportCatchFailure(operation: string, cause: unknown): void;

package/dist/failure.js

@@ -0,0 +1,8 @@
+import * as Redacted from "effect/Redacted";
+/** Retain the original failure without printing provider or customer data. */
+export function reportCatchFailure(operation, cause) {
+    console.error("Media service operation failed", {
+        operation,
+        errorKind: cause instanceof Error ? "error" : "non-error",
+    }, Redacted.make(cause));
+}

package/dist/gateway-models.d.ts

@@ -0,0 +1,23 @@
+import { type MediaGenerationSettings, type MediaReferenceBytes } from "./index.js";
+import type { MediaVideoModelId } from "./model-catalog.js";
+/** Gateway images and the verified catalog's video families share Unified billing. */
+export type GatewayModelId = "openai/gpt-image-2" | MediaVideoModelId;
+export declare const isGatewayModel: (id: string) => id is GatewayModelId;
+/** What one generation bills: whole images, or seconds of video. */
+export type MediaUnits = Readonly<{
+    /** One image or one whole video second. */
+    unit: "image" | "video_second";
+    /** Number of delivered or admitted units. */
+    units: number;
+}>;
+/** Billing units for validated settings; video bills its requested length. */
+export declare function mediaUnits(settings: MediaGenerationSettings): MediaUnits;
+/** Milliunits (1 cent = 1,000) of provider cost, rounded up. */
+export declare function estimateGatewayMilliunits(settings: MediaGenerationSettings): number;
+/** The provider JSON body for one validated gateway generation. */
+export declare function gatewayInput(settings: MediaGenerationSettings, references?: readonly MediaReferenceBytes[], outputFormat?: "png" | "jpeg" | "webp"): import("./video-providers/minimax.js").MinimaxGatewayInput | import("./video-providers/unified.js").UnifiedGatewayInput | {
+    prompt: string;
+    size: string;
+    quality: string;
+    output_format: "png" | "jpeg" | "webp";
+};

package/dist/gateway-models.js

@@ -0,0 +1,77 @@
+import { getMediaModel, MediaSettingsError } from "./model-catalog.js";
+import { validateMediaGenerationSettings, estimateVideoMilliunits, } from "./index.js";
+import { videoProviderAdapters, } from "./video-providers/index.js";
+export const isGatewayModel = (id) => id === "openai/gpt-image-2" || getMediaModel(id)?.kind === "video";
+/** Billing units for validated settings; video bills its requested length. */
+export function mediaUnits(settings) {
+    const model = getMediaModel(settings.model);
+    if (model === undefined)
+        throw new MediaSettingsError("billing units require a known Media model");
+    if (model.kind === "video") {
+        const checked = validateMediaGenerationSettings({
+            ...settings,
+            references: settings.references?.map((reference) => ({ ...reference })),
+        });
+        if (checked.durationSeconds === undefined)
+            throw new MediaSettingsError("video settings need a duration");
+        return { unit: "video_second", units: checked.durationSeconds };
+    }
+    return { unit: "image", units: 1 };
+}
+/**
+ * GPT Image 2 output tokens per image at `medium` quality. OpenAI publishes
+ * this table for its gpt-image models; PRICE DECISION PENDING (Levi): confirm
+ * against the first live gateway logs, which carry the real token counts.
+ */
+const gptImageOutputTokens = new Map([
+    ["1024x1024", 1_056],
+    ["1024x1536", 1_584],
+    ["1536x1024", 1_568],
+]);
+/** USD per million tokens: text input and image output. */
+const gptImageRates = { input: 5, outputImage: 30 };
+const sizeOf = (settings) => `${String(settings.width)}x${String(settings.height)}`;
+/** Milliunits (1 cent = 1,000) of provider cost, rounded up. */
+export function estimateGatewayMilliunits(settings) {
+    if (settings.model === "openai/gpt-image-2") {
+        const output = gptImageOutputTokens.get(sizeOf(settings));
+        if (output === undefined)
+            throw new MediaSettingsError("unsupported GPT Image 2 size");
+        // A bound on prompt tokens: at most one token per character.
+        const input = settings.prompt.length;
+        // tokens * USD/M * 100,000 milliunits/USD / 1,000,000 = tokens * rate / 10
+        return Math.ceil((output * gptImageRates.outputImage + input * gptImageRates.input) / 10);
+    }
+    if (getMediaModel(settings.model)?.kind === "video")
+        return estimateVideoMilliunits(settings);
+    throw new MediaSettingsError(`${settings.model} is not a gateway model`);
+}
+/** The provider JSON body for one validated gateway generation. */
+export function gatewayInput(settings, references = [], outputFormat = "png") {
+    if (settings.model === "openai/gpt-image-2")
+        return {
+            prompt: settings.prompt,
+            size: sizeOf(settings),
+            quality: "medium",
+            output_format: outputFormat,
+        };
+    const checked = validateMediaGenerationSettings({
+        ...settings,
+        references: settings.references?.map((reference) => ({ ...reference })),
+    });
+    const model = getMediaModel(checked.model);
+    if (model?.video == null ||
+        checked.resolution === undefined ||
+        checked.aspectRatio === undefined ||
+        checked.durationSeconds === undefined)
+        throw new MediaSettingsError("not a video gateway model");
+    if (references.length !== (checked.references?.length ?? 0))
+        throw new MediaSettingsError("resolved video references must match every admitted reference");
+    const videoSettings = {
+        ...checked,
+        resolution: checked.resolution,
+        aspectRatio: checked.aspectRatio,
+        durationSeconds: checked.durationSeconds,
+    };
+    return videoProviderAdapters[model.video.provider].buildInput(videoSettings, references, model);
+}