Skip to content
Darkroom0.3.1
API reference

server

Import

Section titled “Import”
Import
import * as api from "@fungi.computer/darkroom/server";

Exports

Section titled “Exports”
Kind Export Description
class MediaExecutionError A bounded stage marker for failures that cross the Media HTTP boundary.
class MediaBillingRefusal A definitive billing refusal before dispatch; nothing was generated or charged.
class MediaOperationOwner Own exact replay, dispatch leases, retained output and save recovery in SQL and object storage.
type alias MediaFailureStage Execution stage at which a generation failed.
type alias MediaExecutionErrorOptions Private cause plus an independently decoded, safe provider diagnostic.
type alias MediaBillingRefusalCode Why the host’s billing owner refused to admit a new generation.
type alias MediaUnits What one generation bills: whole images, or seconds of video.
type alias MediaBindingGeneration Parsed generation command consumed by either host.
type alias MediaBindingCall Parsed call consumed by host admission and transport.
type alias MediaBindingRequest Relative service input after the host attaches its trusted Computer to references.
type alias MediaMetering The host’s billing owner for Media. Every call is keyed by the durable operation id and must be idempotent: a lost acknowledgement is retried with the same id and must never admit, hold, or charge twice.
type alias MediaOperation Local or RPC methods consumed by a replay-safe generation.
type alias MediaOperationRequest Normalized generation and its fixed destination, captured for exact replay.
type alias MediaOperationCoordinates Host-owned namespace and owner identity for one durable operation.
type alias MediaOperationState Durable generation, save and settlement states.
type alias MediaImage Byte length and encoding of generated or saved output.
type alias MediaOperationResult Settled generation receipt with the host-admitted customer price.
type alias MediaOperationProjection The only operation shape safe to return outside the owner.
type alias MediaOperationDecision An admission or claim decision with a safe operation projection.
type alias MediaErasurePreflight Scoped inactivity observation made before destructive erasure.
type alias MediaErasureReadback Evidence that retained output, SQL and alarms were erased.
type alias MediaRetentionResult Retained output projection, or a terminal spent format refusal.
type alias MediaOperationHooks Optional host facts that pin a namespace before operation admission.
type alias MediaOperationEnvironment Retained-output storage supplied by the host.
type alias MediaOperationStorage SQL rows stay untrusted until the owner decodes their stored representation.
type alias MediaOperationContext The identity, serialization and storage owned by one media operation.
type alias MediaOperationObject Object metadata consumed by retention and recovery; mirrors the native R2 fields used here.
type alias MediaOperationBucket Exact object operations needed for immutable media outputs and references.
type alias MediaScope Identity supplied by the admitting host, never selected by a request body.
type alias MediaRefusalMessages Customer-visible refusal text owned by a metered host.
type alias MediaServiceHost Host authority, durable operations, provider, metering and destination access.
type alias MediaGenerationRequest One Media generation request, already carrying its idempotency key.
type alias MediaGenerationOutcome The typed result of one generation, shared by the Hono route and the Agent path.
constant mediaImageBindingInputSchema Image settings and path references crossing a scoped MEDIA binding.
constant mediaVideoBindingInputSchema Video settings and path references crossing the same scoped binding.
constant mediaBindingGenerationSchema One generation identity, including the App-owned folder captured for replay.
constant mediaBindingCallSchema Maintained MEDIA method grammar; guest input carries no principal or Computer.
constant mediaPendingSchema Background-generation reply emitted by the durable service.
constant mediaResultSchema Decode a completed generation, destination path and estimated or settled price.
constant mediaOperationDestinationSchema Fixed generation destination captured before provider dispatch.
constant mediaOperationCoordinatesSchema Decode host namespace and owner identity.
constant mediaOperationStateSchema Decode durable generation, save and settlement states.
constant mediaImageSchema Decode retained or saved output size and encoding.
constant mediaOperationResultSchema Decode the settled receipt, including the host-admitted customer price.
constant mediaRequestSchema Decode relative service generation input. Identity comes from the host.
function mediaUnits() Billing units for validated settings; video bills its requested length.
function parseMediaBindingCall() Parsing and model refusal stay shared; authorization remains host-owned.
function mediaBindingRequest() Choose the same fixed filename on both hosts without a recursive App lookup.
function readMediaBindingReply() Decode bounded service replies once for both MEDIA host bindings.
function generateMedia() Generate through the Effect core with a Promise boundary preserving typed domain failures.
function createMediaService() Relative HTTP routes; the caller admits identity and supplies destination access.

MediaExecutionErrorclass

Section titled “MediaExecutionError”

A bounded stage marker for failures that cross the Media HTTP boundary.

Extends

Section titled “Extends”
  • Error

Constructors

Section titled “Constructors”

Constructor

Section titled “Constructor”
Signature
new MediaExecutionError(stage, options?): MediaExecutionError;
Parameters
Section titled “Parameters”
Parameter Type Description
stage MediaFailureStage Execution stage where the failure occurred.
options? MediaExecutionErrorOptions -
Returns
Section titled “Returns”

MediaExecutionError

Overrides
Section titled “Overrides”
Signature
Error.constructor;

Properties

Section titled “Properties”

provider

Section titled “provider”
Signature
readonly provider: MediaProviderDiagnostic | undefined;

Safe provider facts only; the original cause remains private.

stage

Section titled “stage”
Signature
readonly stage: MediaFailureStage;

Execution stage where the failure occurred.

MediaBillingRefusalclass

Section titled “MediaBillingRefusal”

A definitive billing refusal before dispatch; nothing was generated or charged.

Extends

Section titled “Extends”
  • Error

Constructors

Section titled “Constructors”

Constructor

Section titled “Constructor”
Signature
new MediaBillingRefusal(code): MediaBillingRefusal;
Parameters
Section titled “Parameters”
Parameter Type Description
code MediaBillingRefusalCode Bounded refusal or failure reason.
Returns
Section titled “Returns”

MediaBillingRefusal

Overrides
Section titled “Overrides”
Signature
Error.constructor;

Properties

Section titled “Properties”

code

Section titled “code”
Signature
readonly code: MediaBillingRefusalCode;

Bounded refusal or failure reason.

MediaOperationOwnerclass

Section titled “MediaOperationOwner”

Own exact replay, dispatch leases, retained output and save recovery in SQL and object storage.

Constructors

Section titled “Constructors”

Constructor

Section titled “Constructor”
Signature
new MediaOperationOwner(
   ctx,
   env,
   provider?,
   hooks?
): MediaOperationOwner;
Parameters
Section titled “Parameters”
Parameter Type
ctx MediaOperationContext
env MediaOperationEnvironment
provider? () => MediaProvider | undefined
hooks? MediaOperationHooks
Returns
Section titled “Returns”

MediaOperationOwner

Methods

Section titled “Methods”

read()

Section titled “read()”
Signature
read():
  | Readonly<{
  operationId: string;
  requestId: string;
  namespace: string;
  owner: string;
  state:   | "admitted"
     | "estimating"
     | "generating"
     | "writing"
     | "charging"
     | "written"
     | "succeeded"
     | "interrupted";
  spentFailure: "output_format_mismatch" | null;
  providerFailure:   | Readonly<{
     stage: "provider" | "normalization";
     safetyRefused: boolean;
     provider?: MediaProviderDiagnostic;
   }>
     | null;
  estimatedCostMilliunits: number | null;
  image:   | {
     bytes: number;
     format: string;
   }
     | null;
  result:   | {
     generationId: string;
     bytes: number;
     format: string;
     costMilliunits: number;
   }
     | null;
  createdAt: number;
  updatedAt: number;
}>
  | null;

Read the safe persisted operation projection, or null before admission or after erasure.

Returns
Section titled “Returns”

| Readonly<{ operationId: string; requestId: string; namespace: string; owner: string; state: | "admitted" | "estimating" | "generating" | "writing" | "charging" | "written" | "succeeded" | "interrupted"; spentFailure: "output_format_mismatch" | null; providerFailure: | Readonly<{ stage: "provider" | "normalization"; safetyRefused: boolean; provider?: MediaProviderDiagnostic; }> | null; estimatedCostMilliunits: number | null; image: | { bytes: number; format: string; } | null; result: | { generationId: string; bytes: number; format: string; costMilliunits: number; } | null; createdAt: number; updatedAt: number; }> | null

preflightErasure()

Section titled “preflightErasure()”
Signature
preflightErasure(namespace, requestId): MediaErasurePreflight;

Check host namespace, request identity and inactivity before erasure.

Parameters
Section titled “Parameters”
Parameter Type
namespace string
requestId string
Returns
Section titled “Returns”

MediaErasurePreflight

erase()

Section titled “erase()”
Signature
erase(namespace, requestId): Promise<Readonly<{
  clear: boolean;
}>>;

Erase inactive output and local storage, then retain the durable erasure marker.

Parameters
Section titled “Parameters”
Parameter Type
namespace string
requestId string
Returns
Section titled “Returns”

Promise<Readonly<{ clear: boolean; }>>

readErasure()

Section titled “readErasure()”
Signature
readErasure(): Promise<Readonly<{
  clear: boolean;
}>>;

Read back empty SQL, alarm and retained output with the durable erasure marker.

Returns
Section titled “Returns”

Promise<Readonly<{ clear: boolean; }>>

admit()

Section titled “admit()”
Signature
admit(
   actorUserId,
   coordinatesInput,
   requestId,
   input
): MediaOperationDecision;

Capture immutable host identity and input, replaying exact requests and refusing changed input.

Parameters
Section titled “Parameters”
Parameter Type Description
actorUserId string -
coordinatesInput { namespace: string; owner: string; } -
coordinatesInput.namespace string Host isolation namespace.
coordinatesInput.owner string Host owner within the namespace.
requestId string -
input MediaOperationRequest -
Returns
Section titled “Returns”

MediaOperationDecision

claim()

Section titled “claim()”
Signature
claim(): Promise<Readonly<{
  kind:   | "admitted"
     | "succeeded"
     | "interrupted"
     | "conflict"
     | "replayed"
     | "claimed"
     | "pending";
  operation: MediaOperationProjection;
  leaseId?: string;
}>>;

Claim a safe dispatch or save lease, recovering retained output without redispatching inference.

Returns
Section titled “Returns”

Promise<Readonly<{ kind: | "admitted" | "succeeded" | "interrupted" | "conflict" | "replayed" | "claimed" | "pending"; operation: MediaOperationProjection; leaseId?: string; }>>

recordEstimate()

Section titled “recordEstimate()”
Signature
recordEstimate(leaseId, costMilliunits): Readonly<{
  operationId: string;
  requestId: string;
  namespace: string;
  owner: string;
  state:   | "admitted"
     | "estimating"
     | "generating"
     | "writing"
     | "charging"
     | "written"
     | "succeeded"
     | "interrupted";
  spentFailure: "output_format_mismatch" | null;
  providerFailure:   | Readonly<{
     stage: "provider" | "normalization";
     safetyRefused: boolean;
     provider?: MediaProviderDiagnostic;
   }>
     | null;
  estimatedCostMilliunits: number | null;
  image:   | {
     bytes: number;
     format: string;
   }
     | null;
  result:   | {
     generationId: string;
     bytes: number;
     format: string;
     costMilliunits: number;
   }
     | null;
  createdAt: number;
  updatedAt: number;
}>;

Pin the admitted price and begin the generation lease.

Parameters
Section titled “Parameters”
Parameter Type
leaseId string
costMilliunits number
Returns
Section titled “Returns”

Readonly<{ operationId: string; requestId: string; namespace: string; owner: string; state: | "admitted" | "estimating" | "generating" | "writing" | "charging" | "written" | "succeeded" | "interrupted"; spentFailure: "output_format_mismatch" | null; providerFailure: | Readonly<{ stage: "provider" | "normalization"; safetyRefused: boolean; provider?: MediaProviderDiagnostic; }> | null; estimatedCostMilliunits: number | null; image: | { bytes: number; format: string; } | null; result: | { generationId: string; bytes: number; format: string; costMilliunits: number; } | null; createdAt: number; updatedAt: number; }>

dispatchInBackground()

Section titled “dispatchInBackground()”
Signature
dispatchInBackground(leaseId, references): Promise<Readonly<{
  operationId: string;
  requestId: string;
  namespace: string;
  owner: string;
  state:   | "admitted"
     | "estimating"
     | "generating"
     | "writing"
     | "charging"
     | "written"
     | "succeeded"
     | "interrupted";
  spentFailure: "output_format_mismatch" | null;
  providerFailure:   | Readonly<{
     stage: "provider" | "normalization";
     safetyRefused: boolean;
     provider?: MediaProviderDiagnostic;
   }>
     | null;
  estimatedCostMilliunits: number | null;
  image:   | {
     bytes: number;
     format: string;
   }
     | null;
  result:   | {
     generationId: string;
     bytes: number;
     format: string;
     costMilliunits: number;
   }
     | null;
  createdAt: number;
  updatedAt: number;
}>>;

Hand a long (video) generation to this owner’s alarm. The caller’s request returns at once; the alarm dispatches the provider exactly once, retains the output, and releases the lease so a later retry saves and charges it.

Parameters
Section titled “Parameters”
Parameter Type
leaseId string
references readonly Readonly<{ bytes: Uint8Array; format: ImageFormat; width: number; height: number; filename?: string; }>[]
Returns
Section titled “Returns”

Promise<Readonly<{ operationId: string; requestId: string; namespace: string; owner: string; state: | "admitted" | "estimating" | "generating" | "writing" | "charging" | "written" | "succeeded" | "interrupted"; spentFailure: "output_format_mismatch" | null; providerFailure: | Readonly<{ stage: "provider" | "normalization"; safetyRefused: boolean; provider?: MediaProviderDiagnostic; }> | null; estimatedCostMilliunits: number | null; image: | { bytes: number; format: string; } | null; result: | { generationId: string; bytes: number; format: string; costMilliunits: number; } | null; createdAt: number; updatedAt: number; }>>

alarm()

Section titled “alarm()”
Signature
alarm(): Promise<void>;

Run a background generation once; a retried alarm never redispatches.

Returns
Section titled “Returns”

Promise<void>

interruptGeneration()

Section titled “interruptGeneration()”
Signature
interruptGeneration(leaseId, failureInput?): MediaOperationProjection;

An aborted in-flight provider call is terminal for this request ID.

Parameters
Section titled “Parameters”
Parameter Type
leaseId string
failureInput? Readonly<{ stage: "provider" | "normalization"; safetyRefused: boolean; provider?: MediaProviderDiagnostic; }>
Returns
Section titled “Returns”

MediaOperationProjection

recordGenerated()

Section titled “recordGenerated()”
Signature
recordGenerated(
   leaseId,
   bytes,
   formatInput
): Promise<MediaRetentionResult>;

Retain immutable provider output before making the save state visible.

Parameters
Section titled “Parameters”
Parameter Type
leaseId string
bytes Uint8Array
formatInput string
Returns
Section titled “Returns”

Promise<MediaRetentionResult>

readGenerated()

Section titled “readGenerated()”
Signature
readGenerated(leaseId): Promise<Uint8Array<ArrayBufferLike>>;

Read exact retained bytes under the current save lease.

Parameters
Section titled “Parameters”
Parameter Type
leaseId string
Returns
Section titled “Returns”

Promise<Uint8Array<ArrayBufferLike>>

releaseWrite()

Section titled “releaseWrite()”
Signature
releaseWrite(leaseId): MediaOperationProjection;

A fixed-path exact-byte save is safe to retry without repeating generation.

Parameters
Section titled “Parameters”
Parameter Type
leaseId string
Returns
Section titled “Returns”

MediaOperationProjection

recordWritten()

Section titled “recordWritten()”
Signature
recordWritten(
   leaseId,
   receipt,
   written
): Readonly<{
  operationId: string;
  requestId: string;
  namespace: string;
  owner: string;
  state:   | "admitted"
     | "estimating"
     | "generating"
     | "writing"
     | "charging"
     | "written"
     | "succeeded"
     | "interrupted";
  spentFailure: "output_format_mismatch" | null;
  providerFailure:   | Readonly<{
     stage: "provider" | "normalization";
     safetyRefused: boolean;
     provider?: MediaProviderDiagnostic;
   }>
     | null;
  estimatedCostMilliunits: number | null;
  image:   | {
     bytes: number;
     format: string;
   }
     | null;
  result:   | {
     generationId: string;
     bytes: number;
     format: string;
     costMilliunits: number;
   }
     | null;
  createdAt: number;
  updatedAt: number;
}>;

Record a destination write and move to idempotent settlement.

Parameters
Section titled “Parameters”
Parameter Type Description
leaseId string -
receipt string -
written { bytes: number; format: string; } -
written.bytes number Output byte length.
written.format string Actual output encoding.
Returns
Section titled “Returns”

Readonly<{ operationId: string; requestId: string; namespace: string; owner: string; state: | "admitted" | "estimating" | "generating" | "writing" | "charging" | "written" | "succeeded" | "interrupted"; spentFailure: "output_format_mismatch" | null; providerFailure: | Readonly<{ stage: "provider" | "normalization"; safetyRefused: boolean; provider?: MediaProviderDiagnostic; }> | null; estimatedCostMilliunits: number | null; image: | { bytes: number; format: string; } | null; result: | { generationId: string; bytes: number; format: string; costMilliunits: number; } | null; createdAt: number; updatedAt: number; }>

recordWrittenWithoutSettlement()

Section titled “recordWrittenWithoutSettlement()”
Signature
recordWrittenWithoutSettlement(
   leaseId,
   receipt,
   written
): Readonly<{
  operationId: string;
  requestId: string;
  namespace: string;
  owner: string;
  state:   | "admitted"
     | "estimating"
     | "generating"
     | "writing"
     | "charging"
     | "written"
     | "succeeded"
     | "interrupted";
  spentFailure: "output_format_mismatch" | null;
  providerFailure:   | Readonly<{
     stage: "provider" | "normalization";
     safetyRefused: boolean;
     provider?: MediaProviderDiagnostic;
   }>
     | null;
  estimatedCostMilliunits: number | null;
  image:   | {
     bytes: number;
     format: string;
   }
     | null;
  result:   | {
     generationId: string;
     bytes: number;
     format: string;
     costMilliunits: number;
   }
     | null;
  createdAt: number;
  updatedAt: number;
}>;

Persist a completed Computer write without claiming billing success. A lost receipt may replay the exact retained bytes to the captured path; it never repeats provider generation.

Parameters
Section titled “Parameters”
Parameter Type Description
leaseId string -
receipt string -
written { bytes: number; format: string; } -
written.bytes number Output byte length.
written.format string Actual output encoding.
Returns
Section titled “Returns”

Readonly<{ operationId: string; requestId: string; namespace: string; owner: string; state: | "admitted" | "estimating" | "generating" | "writing" | "charging" | "written" | "succeeded" | "interrupted"; spentFailure: "output_format_mismatch" | null; providerFailure: | Readonly<{ stage: "provider" | "normalization"; safetyRefused: boolean; provider?: MediaProviderDiagnostic; }> | null; estimatedCostMilliunits: number | null; image: | { bytes: number; format: string; } | null; result: | { generationId: string; bytes: number; format: string; costMilliunits: number; } | null; createdAt: number; updatedAt: number; }>

recordSucceeded()

Section titled “recordSucceeded()”
Signature
recordSucceeded(leaseId, resultInput): Readonly<{
  operationId: string;
  requestId: string;
  namespace: string;
  owner: string;
  state:   | "admitted"
     | "estimating"
     | "generating"
     | "writing"
     | "charging"
     | "written"
     | "succeeded"
     | "interrupted";
  spentFailure: "output_format_mismatch" | null;
  providerFailure:   | Readonly<{
     stage: "provider" | "normalization";
     safetyRefused: boolean;
     provider?: MediaProviderDiagnostic;
   }>
     | null;
  estimatedCostMilliunits: number | null;
  image:   | {
     bytes: number;
     format: string;
   }
     | null;
  result:   | {
     generationId: string;
     bytes: number;
     format: string;
     costMilliunits: number;
   }
     | null;
  createdAt: number;
  updatedAt: number;
}>;

Commit the settled receipt after verifying the saved output and admitted price.

Parameters
Section titled “Parameters”
Parameter Type Description
leaseId string -
resultInput { generationId: string; bytes: number; format: string; costMilliunits: number; } -
resultInput.generationId string Durable operation identifier.
resultInput.bytes number Output byte length.
resultInput.format string Actual output encoding.
resultInput.costMilliunits number Admitted price in milliunits, where 1 cent is 1,000 milliunits.
Returns
Section titled “Returns”

Readonly<{ operationId: string; requestId: string; namespace: string; owner: string; state: | "admitted" | "estimating" | "generating" | "writing" | "charging" | "written" | "succeeded" | "interrupted"; spentFailure: "output_format_mismatch" | null; providerFailure: | Readonly<{ stage: "provider" | "normalization"; safetyRefused: boolean; provider?: MediaProviderDiagnostic; }> | null; estimatedCostMilliunits: number | null; image: | { bytes: number; format: string; } | null; result: | { generationId: string; bytes: number; format: string; costMilliunits: number; } | null; createdAt: number; updatedAt: number; }>

releaseEstimate()

Section titled “releaseEstimate()”
Signature
releaseEstimate(leaseId): MediaOperationProjection;

Release preparation or refused admission so the same request can retry.

Parameters
Section titled “Parameters”
Parameter Type
leaseId string
Returns
Section titled “Returns”

MediaOperationProjection

MediaFailureStagetype alias

Section titled “MediaFailureStage”
Signature
type MediaFailureStage = Exclude<
  z.output<typeof mediaFailureStageSchema>,
  "admission" | "settings"
>;

Execution stage at which a generation failed.

MediaExecutionErrorOptionstype alias

Section titled “MediaExecutionErrorOptions”
Signature
type MediaExecutionErrorOptions = ErrorOptions & object;

Private cause plus an independently decoded, safe provider diagnostic.

Type Declaration

Section titled “Type Declaration”
Name Type Description
provider? MediaProviderDiagnostic Safe provider facts, when the failure came from provider transport.

MediaBillingRefusalCodetype alias

Section titled “MediaBillingRefusalCode”
Signature
type MediaBillingRefusalCode =
  "insufficient_credits" | "daily_limit_reached" | "denied";

Why the host’s billing owner refused to admit a new generation.

MediaUnitstype alias

Section titled “MediaUnits”
Signature
type MediaUnits = Readonly<{
  unit: "image" | "video_second";
  units: number;
}>;

What one generation bills: whole images, or seconds of video.

MediaBindingGenerationtype alias

Section titled “MediaBindingGeneration”
Signature
type MediaBindingGeneration = z.output<typeof mediaBindingGenerationSchema>;

Parsed generation command consumed by either host.

MediaBindingCalltype alias

Section titled “MediaBindingCall”
Signature
type MediaBindingCall = z.output<typeof mediaBindingCallSchema>;

Parsed call consumed by host admission and transport.

MediaBindingRequesttype alias

Section titled “MediaBindingRequest”
Signature
type MediaBindingRequest = Readonly<{
  path: string;
  settings: MediaGenerationSettings;
  outputFormat?: z.output<typeof mediaRequestedImageFormatSchema>;
}>;

Relative service input after the host attaches its trusted Computer to references.

MediaMeteringtype alias

Section titled “MediaMetering”
Signature
type MediaMetering = Readonly<{
  admit: (input) => Promise<
    Readonly<{
      priceMilliunits: number;
    }>
  >;
  settle: (input) => Promise<void>;
}>;

The host’s billing owner for Media. Every call is keyed by the durable operation id and must be idempotent: a lost acknowledgement is retried with the same id and must never admit, hold, or charge twice.

MediaOperationtype alias

Section titled “MediaOperation”
Signature
type MediaOperation = {
  [
    Method in
      | "admit"
      | "claim"
      | "dispatchInBackground"
      | "interruptGeneration"
      | "readGenerated"
      | "recordEstimate"
      | "recordGenerated"
      | "recordSucceeded"
      | "recordWritten"
      | "recordWrittenWithoutSettlement"
      | "releaseEstimate"
      | "releaseWrite"
  ]: (
    input: Parameters<MediaOperationOwner[Method]>,
  ) =>
    | ReturnType<MediaOperationOwner[Method]>
    | Promise<Awaited<ReturnType<MediaOperationOwner[Method]>>>;
};

Local or RPC methods consumed by a replay-safe generation.

MediaOperationRequesttype alias

Section titled “MediaOperationRequest”
Signature
type MediaOperationRequest = MediaGenerationSettings &
  z.output<typeof mediaOperationDestinationSchema>;

Normalized generation and its fixed destination, captured for exact replay.

MediaOperationCoordinatestype alias

Section titled “MediaOperationCoordinates”
Signature
type MediaOperationCoordinates = z.output<
  typeof mediaOperationCoordinatesSchema
>;

Host-owned namespace and owner identity for one durable operation.

MediaOperationStatetype alias

Section titled “MediaOperationState”
Signature
type MediaOperationState = z.output<typeof mediaOperationStateSchema>;

Durable generation, save and settlement states.

MediaImagetype alias

Section titled “MediaImage”
Signature
type MediaImage = z.output<typeof mediaImageSchema>;

Byte length and encoding of generated or saved output.

MediaOperationResulttype alias

Section titled “MediaOperationResult”
Signature
type MediaOperationResult = z.output<typeof mediaOperationResultSchema>;

Settled generation receipt with the host-admitted customer price.

MediaOperationProjectiontype alias

Section titled “MediaOperationProjection”
Signature
type MediaOperationProjection = Readonly<{
  operationId: string;
  requestId: string;
  namespace: string;
  owner: string;
  state: MediaOperationState;
  spentFailure: "output_format_mismatch" | null;
  providerFailure: Readonly<{
    stage: Extract<MediaFailureStage, "provider" | "normalization">;
    safetyRefused: boolean;
    provider?: MediaProviderDiagnostic;
  }> | null;
  estimatedCostMilliunits: number | null;
  image: MediaImage | null;
  result: MediaOperationResult | null;
  createdAt: number;
  updatedAt: number;
}>;

The only operation shape safe to return outside the owner.

MediaOperationDecisiontype alias

Section titled “MediaOperationDecision”
Signature
type MediaOperationDecision = Readonly<{
  kind:
    | "admitted"
    | "conflict"
    | "replayed"
    | "claimed"
    | "pending"
    | "succeeded"
    | "interrupted";
  operation: MediaOperationProjection;
  leaseId?: string;
}>;

An admission or claim decision with a safe operation projection.

MediaErasurePreflighttype alias

Section titled “MediaErasurePreflight”
Signature
type MediaErasurePreflight = Readonly<{
  namespace: string;
  requestId: string;
  erased: boolean;
}>;

Scoped inactivity observation made before destructive erasure.

MediaErasureReadbacktype alias

Section titled “MediaErasureReadback”
Signature
type MediaErasureReadback = Readonly<{
  clear: boolean;
}>;

Evidence that retained output, SQL and alarms were erased.

MediaRetentionResulttype alias

Section titled “MediaRetentionResult”
Signature
type MediaRetentionResult =
  | MediaOperationProjection
  | Readonly<{
      kind: "refused";
      code: "output_format_mismatch";
    }>;

Retained output projection, or a terminal spent format refusal.

MediaOperationHookstype alias

Section titled “MediaOperationHooks”
Signature
type MediaOperationHooks = Readonly<{
  namespace?: () => string | null;
}>;

Optional host facts that pin a namespace before operation admission.

MediaOperationEnvironmenttype alias

Section titled “MediaOperationEnvironment”
Signature
type MediaOperationEnvironment = Readonly<{
  APP_ARTIFACTS: MediaOperationBucket;
}>;

Retained-output storage supplied by the host.

MediaOperationStoragetype alias

Section titled “MediaOperationStorage”
Signature
type MediaOperationStorage = object;

SQL rows stay untrusted until the owner decodes their stored representation.

Properties

Section titled “Properties”

sql

Section titled “sql”
Signature
sql: object;

Native synchronous SQL interface.

exec()
Section titled “exec()”
Signature
exec(query, ...bindings): object;

Execute a native SQL statement with positional bindings.

Parameters
Section titled “Parameters”
Parameter Type
query string
…bindings (string | number | null)[]
Returns
Section titled “Returns”
Name Type Description
toArray() () => readonly object[] Read the native SQL rows as objects for boundary decoding.

Methods

Section titled “Methods”

transactionSync()

Section titled “transactionSync()”
Signature
transactionSync<T>(body): T;

Run one atomic synchronous local mutation.

Type Parameters
Section titled “Type Parameters”
Type Parameter
T
Parameters
Section titled “Parameters”
Parameter Type
body () => T
Returns
Section titled “Returns”

T

isErased()

Section titled “isErased()”
Signature
isErased(): Promise<boolean>;

Read the durable erasure marker.

Returns
Section titled “Returns”

Promise<boolean>

markErased()

Section titled “markErased()”
Signature
markErased(): Promise<void>;

Persist the durable erasure marker.

Returns
Section titled “Returns”

Promise<void>

listKeys()

Section titled “listKeys()”
Signature
listKeys(): Promise<readonly string[]>;

List local key-value storage keys for erasure readback.

Returns
Section titled “Returns”

Promise<readonly string[]>

deleteAlarm()

Section titled “deleteAlarm()”
Signature
deleteAlarm(): Promise<void>;

Remove any scheduled background alarm.

Returns
Section titled “Returns”

Promise<void>

deleteAll()

Section titled “deleteAll()”
Signature
deleteAll(): Promise<void>;

Remove local SQL and key-value storage.

Returns
Section titled “Returns”

Promise<void>

getAlarm()

Section titled “getAlarm()”
Signature
getAlarm(): Promise<number | null>;

Read the current background alarm, or null.

Returns
Section titled “Returns”

Promise<number | null>

setAlarm()

Section titled “setAlarm()”
Signature
setAlarm(timestamp): Promise<void>;

Schedule background generation at the given timestamp.

Parameters
Section titled “Parameters”
Parameter Type
timestamp number
Returns
Section titled “Returns”

Promise<void>

MediaOperationContexttype alias

Section titled “MediaOperationContext”
Signature
type MediaOperationContext = object;

The identity, serialization and storage owned by one media operation.

Properties

Section titled “Properties”

id

Section titled “id”
Signature
id: object;

Durable operation identity selected by the host.

name
Section titled “name”
Signature
name: string | undefined;

Stable error name or durable object name.

storage

Section titled “storage”
Signature
storage: MediaOperationStorage;

Host-owned SQL, key-value storage and alarms.

Methods

Section titled “Methods”

blockConcurrencyWhile()

Section titled “blockConcurrencyWhile()”
Signature
blockConcurrencyWhile<T>(body): Promise<T>;

Serialize asynchronous owner initialization with requests.

Type Parameters
Section titled “Type Parameters”
Type Parameter
T
Parameters
Section titled “Parameters”
Parameter Type
body () => Promise<T>
Returns
Section titled “Returns”

Promise<T>

MediaOperationObjecttype alias

Section titled “MediaOperationObject”
Signature
type MediaOperationObject = Readonly<{
  key: string;
  version: string;
  size: number;
  httpMetadata?: Readonly<{
    contentType?: string;
  }>;
}>;

Object metadata consumed by retention and recovery; mirrors the native R2 fields used here.

MediaOperationBuckettype alias

Section titled “MediaOperationBucket”
Signature
type MediaOperationBucket = object;

Exact object operations needed for immutable media outputs and references.

Methods

Section titled “Methods”

put()

Section titled “put()”
Signature
put(
   key,
   bytes,
   options?
): Promise<
  | Readonly<{
  version: string;
}>
| null>;

Conditionally retain immutable provider bytes or background reference bytes.

Parameters
Section titled “Parameters”
Parameter Type
key string
bytes Uint8Array
options? Readonly<{ onlyIf?: Readonly<{ etagDoesNotMatch: string; }>; httpMetadata?: Readonly<{ contentType: string; }>; customMetadata?: Readonly<Record<string, string>>; }>
Returns
Section titled “Returns”

Promise< | Readonly<{ version: string; }> | null>

Section titled “head()”
Signature
head(key): Promise<
  | Readonly<{
  key: string;
  version: string;
  size: number;
  httpMetadata?: Readonly<{
     contentType?: string;
  }>;
}>
| null>;

Read immutable object metadata without loading bytes.

Parameters
Section titled “Parameters”
Parameter Type
key string
Returns
Section titled “Returns”

Promise< | Readonly<{ key: string; version: string; size: number; httpMetadata?: Readonly<{ contentType?: string; }>; }> | null>

get()

Section titled “get()”
Signature
get(key): Promise<
  | Omit<Readonly<{
  key: string;
  version: string;
  size: number;
  httpMetadata?: Readonly<{
     contentType?: string;
  }>;
}>, "httpMetadata"> & Readonly<{
  customMetadata?: Readonly<Record<string, string>>;
  arrayBuffer: () => Promise<ArrayBuffer>;
}>
| null>;

Read retained object bytes and metadata.

Parameters
Section titled “Parameters”
Parameter Type
key string
Returns
Section titled “Returns”

Promise< | Omit<Readonly<{ key: string; version: string; size: number; httpMetadata?: Readonly<{ contentType?: string; }>; }>, "httpMetadata"> & Readonly<{ customMetadata?: Readonly<Record<string, string>>; arrayBuffer: () => Promise<ArrayBuffer>; }> | null>

delete()

Section titled “delete()”
Signature
delete(key): Promise<void>;

Delete the owner-selected object key.

Parameters
Section titled “Parameters”
Parameter Type
key string
Returns
Section titled “Returns”

Promise<void>

MediaScopetype alias

Section titled “MediaScope”
Signature
type MediaScope = Readonly<{
  actorId: string;
  namespace: string;
  owner: string;
  destinationId: string;
}>;

Identity supplied by the admitting host, never selected by a request body.

MediaRefusalMessagestype alias

Section titled “MediaRefusalMessages”
Signature
type MediaRefusalMessages = Readonly<Record<MediaBillingRefusalCode, string>>;

Customer-visible refusal text owned by a metered host.

MediaServiceHosttype alias

Section titled “MediaServiceHost”
Signature
type MediaServiceHost = Readonly<{
  scope: MediaScope;
  operations: {
     getByName: MediaOperation;
  };
  provider: MediaProvider;
  beforeAdmit?: (requestId) => Promise<void>;
  authorizeGeneration?: () => Promise<void>;
  destination: Readonly<{
     authorize: (path) => Promise<void>;
     write: (path, bytes) => Promise<void>;
     readReference?: (reference) => Promise<MediaReferenceBytes>;
  }>;
  onFailure?: (error) => Response | undefined;
}> &
  | Readonly<{
  metering: "unmetered";
  refusalMessages?: never;
}>
  | Readonly<{
  metering: MediaMetering;
  refusalMessages: MediaRefusalMessages;
}>;

Host authority, durable operations, provider, metering and destination access.

MediaGenerationRequesttype alias

Section titled “MediaGenerationRequest”
Signature
type MediaGenerationRequest = Readonly<{
  requestId: string;
  path: string;
  settings: Parameters<typeof validateMediaGenerationSettings>[0];
  outputFormat?: z.output<typeof mediaRequestSchema>["outputFormat"];
}>;

One Media generation request, already carrying its idempotency key.

MediaGenerationOutcometype alias

Section titled “MediaGenerationOutcome”
Signature
type MediaGenerationOutcome =
  | Readonly<{
      kind: "succeeded";
      path: string;
      bytes: number;
      costMilliunits: number;
      format: "png" | "jpeg" | "gif" | "webp" | "mp4";
      height: number;
      model: string;
      width: number;
    }>
  | Readonly<{
      kind: "pending";
      background: boolean;
      retryAfterSeconds: number;
    }>
  | Readonly<{
      kind: "conflict";
    }>
  | Readonly<{
      kind: "interrupted";
    }>
  | Readonly<{
      kind: "unavailable";
    }>;

The typed result of one generation, shared by the Hono route and the Agent path.

mediaImageBindingInputSchemaconstant

Section titled “mediaImageBindingInputSchema”
Signature
const mediaImageBindingInputSchema: ZodObject<{
  kind: ZodLiteral<"image">;
  requestId: ZodLazy<ZodString>;
  libraryPath: ZodString & ZodType<string, string, $ZodTypeInternals<string, string>>;
  settings: ZodObject<{
     model: ZodString;
     prompt: ZodString;
     width: ZodNumber;
     height: ZodNumber;
     resolution: ZodOptional<ZodEnum<{
        p480: "480p";
        p720: "720p";
        p768: "768p";
        p1080: "1080p";
        p4k: "4k";
     }>>;
     aspectRatio: ZodOptional<ZodEnum<{
        wide: "16:9";
        landscape: "4:3";
        square: "1:1";
        portrait: "3:4";
        tall: "9:16";
        ultrawide: "21:9";
        ultratall: "9:21";
     }>>;
     generateAudio: ZodOptional<ZodBoolean>;
     references: ZodOptional<ZodArray<ZodObject<{
        path: ZodString;
        role: ZodOptional<ZodEnum<{
           first: ...;
           last: ...;
           reference: ...;
        }>>;
     }, $strict>>>;
     steps: ZodOptional<ZodNumber>;
  }, $strict>;
  outputFormat: ZodOptional<ZodEnum<{
     png: "png";
     jpeg: "jpeg";
     webp: "webp";
  }>>;
}, $strict>;

Image settings and path references crossing a scoped MEDIA binding.

mediaVideoBindingInputSchemaconstant

Section titled “mediaVideoBindingInputSchema”
Signature
const mediaVideoBindingInputSchema: ZodObject<{
  kind: ZodLiteral<"video">;
  requestId: ZodLazy<ZodString>;
  libraryPath: ZodString & ZodType<string, string, $ZodTypeInternals<string, string>>;
  settings: ZodLazy<ZodObject<{
     model: ZodEnum<{
        seedance: "bytedance/seedance-2.0";
        seedanceFast: "bytedance/seedance-2.0-fast";
        seedanceMini: "bytedance/seedance-2.0-mini";
        veo: "google/veo-3.1";
        veoFast: "google/veo-3.1-fast";
        minimaxH3Max: "minimax/h3-max";
     }>;
     prompt: ZodString;
     resolution: ZodOptional<ZodEnum<{
        p480: "480p";
        p720: "720p";
        p768: "768p";
        p1080: "1080p";
        p4k: "4k";
     }>>;
     aspectRatio: ZodOptional<ZodEnum<{
        wide: "16:9";
        landscape: "4:3";
        square: "1:1";
        portrait: "3:4";
        tall: "9:16";
        ultrawide: "21:9";
        ultratall: "9:21";
     }>>;
     durationSeconds: ZodOptional<ZodNumber>;
     generateAudio: ZodOptional<ZodBoolean>;
     references: ZodOptional<ZodArray<ZodLazy<ZodObject<{
        path: ZodString;
        role: ZodEnum<...>;
     }, $strict>>>>;
  }, $strict>>;
}, $strict>;

Video settings and path references crossing the same scoped binding.

mediaBindingGenerationSchemaconstant

Section titled “mediaBindingGenerationSchema”
Signature
const mediaBindingGenerationSchema: ZodDiscriminatedUnion<[ZodObject<{
  kind: ZodLiteral<"image">;
  requestId: ZodLazy<ZodString>;
  libraryPath: ZodString & ZodType<string, string, $ZodTypeInternals<string, string>>;
  settings: ZodObject<{
     model: ZodString;
     prompt: ZodString;
     width: ZodNumber;
     height: ZodNumber;
     resolution: ZodOptional<ZodEnum<{
        p480: "480p";
        p720: "720p";
        p768: "768p";
        p1080: "1080p";
        p4k: "4k";
     }>>;
     aspectRatio: ZodOptional<ZodEnum<{
        wide: "16:9";
        landscape: "4:3";
        square: "1:1";
        portrait: "3:4";
        tall: "9:16";
        ultrawide: "21:9";
        ultratall: "9:21";
     }>>;
     generateAudio: ZodOptional<ZodBoolean>;
     references: ZodOptional<ZodArray<ZodObject<{
        path: ZodString;
        role: ZodOptional<...>;
     }, $strict>>>;
     steps: ZodOptional<ZodNumber>;
  }, $strict>;
  outputFormat: ZodOptional<ZodEnum<{
     png: "png";
     jpeg: "jpeg";
     webp: "webp";
  }>>;
}, $strict>, ZodObject<{
  kind: ZodLiteral<"video">;
  requestId: ZodLazy<ZodString>;
  libraryPath: ZodString & ZodType<string, string, $ZodTypeInternals<string, string>>;
  settings: ZodLazy<ZodObject<{
     model: ZodEnum<{
        seedance: "bytedance/seedance-2.0";
        seedanceFast: "bytedance/seedance-2.0-fast";
        seedanceMini: "bytedance/seedance-2.0-mini";
        veo: "google/veo-3.1";
        veoFast: "google/veo-3.1-fast";
        minimaxH3Max: "minimax/h3-max";
     }>;
     prompt: ZodString;
     resolution: ZodOptional<ZodEnum<{
        p480: "480p";
        p720: "720p";
        p768: "768p";
        p1080: "1080p";
        p4k: "4k";
     }>>;
     aspectRatio: ZodOptional<ZodEnum<{
        wide: "16:9";
        landscape: "4:3";
        square: "1:1";
        portrait: "3:4";
        tall: "9:16";
        ultrawide: "21:9";
        ultratall: "9:21";
     }>>;
     durationSeconds: ZodOptional<ZodNumber>;
     generateAudio: ZodOptional<ZodBoolean>;
     references: ZodOptional<ZodArray<ZodLazy<ZodObject<..., ...>>>>;
  }, $strict>>;
}, $strict>], "kind">;

One generation identity, including the App-owned folder captured for replay.

mediaBindingCallSchemaconstant

Section titled “mediaBindingCallSchema”
Signature
const mediaBindingCallSchema: ZodDiscriminatedUnion<[ZodObject<{
  operation: ZodLiteral<"models">;
  input: ZodObject<{
  }, $strict>;
}, $strict>, ZodObject<{
  operation: ZodLiteral<"generate">;
  input: ZodDiscriminatedUnion<[ZodObject<{
     kind: ZodLiteral<"image">;
     requestId: ZodLazy<ZodString>;
     libraryPath: ZodString & ZodType<string, string, $ZodTypeInternals<..., ...>>;
     settings: ZodObject<{
        model: ZodString;
        prompt: ZodString;
        width: ZodNumber;
        height: ZodNumber;
        resolution: ZodOptional<...>;
        aspectRatio: ZodOptional<...>;
        generateAudio: ZodOptional<...>;
        references: ZodOptional<...>;
        steps: ZodOptional<...>;
     }, $strict>;
     outputFormat: ZodOptional<ZodEnum<{
        png: ...;
        jpeg: ...;
        webp: ...;
     }>>;
   }, $strict>, ZodObject<{
     kind: ZodLiteral<"video">;
     requestId: ZodLazy<ZodString>;
     libraryPath: ZodString & ZodType<string, string, $ZodTypeInternals<..., ...>>;
     settings: ZodLazy<ZodObject<{
        model: ...;
        prompt: ...;
        resolution: ...;
        aspectRatio: ...;
        durationSeconds: ...;
        generateAudio: ...;
        references: ...;
     }, $strict>>;
  }, $strict>], "kind">;
}, $strict>], "operation">;

Maintained MEDIA method grammar; guest input carries no principal or Computer.

mediaPendingSchemaconstant

Section titled “mediaPendingSchema”
Signature
const mediaPendingSchema: ZodLazy<
  ZodObject<
    {
      status: ZodLiteral<"pending">;
      retryAfterSeconds: ZodNumber;
    },
    $strict
  >
>;

Background-generation reply emitted by the durable service.

mediaResultSchemaconstant

Section titled “mediaResultSchema”
Signature
const mediaResultSchema: ZodObject<
  {
    bytes: ZodNumber;
    costMilliunits: ZodNumber;
    path: ZodString;
    format: ZodEnum<{
      png: "png";
      jpeg: "jpeg";
      gif: "gif";
      webp: "webp";
      mp4: "mp4";
    }>;
    height: ZodNumber;
    model: ZodString;
    width: ZodNumber;
  },
  $strict
>;

Decode a completed generation, destination path and estimated or settled price.

mediaOperationDestinationSchemaconstant

Section titled “mediaOperationDestinationSchema”
Signature
const mediaOperationDestinationSchema: ZodLazy<
  ZodObject<
    {
      computerId: ZodString;
      path: ZodString;
      outputFormat: ZodOptional<
        ZodEnum<{
          png: "png";
          jpeg: "jpeg";
          webp: "webp";
        }>
      >;
    },
    $strict
  >
>;

Fixed generation destination captured before provider dispatch.

mediaOperationCoordinatesSchemaconstant

Section titled “mediaOperationCoordinatesSchema”
Signature
const mediaOperationCoordinatesSchema: ZodObject<
  {
    namespace: ZodString;
    owner: ZodString;
  },
  $strict
>;

Decode host namespace and owner identity.

mediaOperationStateSchemaconstant

Section titled “mediaOperationStateSchema”
Signature
const mediaOperationStateSchema: ZodEnum<{
  admitted: "admitted";
  estimating: "estimating";
  generating: "generating";
  writing: "writing";
  charging: "charging";
  written: "written";
  succeeded: "succeeded";
  interrupted: "interrupted";
}>;

Decode durable generation, save and settlement states.

mediaImageSchemaconstant

Section titled “mediaImageSchema”
Signature
const mediaImageSchema: ZodLazy<
  ZodObject<
    {
      bytes: ZodNumber;
      format: ZodString;
    },
    $strict
  >
>;

Decode retained or saved output size and encoding.

mediaOperationResultSchemaconstant

Section titled “mediaOperationResultSchema”
Signature
const mediaOperationResultSchema: ZodLazy<
  ZodObject<
    {
      generationId: ZodString;
      bytes: ZodNumber;
      format: ZodString;
      costMilliunits: ZodNumber;
    },
    $strict
  >
>;

Decode the settled receipt, including the host-admitted customer price.

mediaRequestSchemaconstant

Section titled “mediaRequestSchema”
Signature
const mediaRequestSchema: ZodObject<{
  path: ZodString;
  settings: ZodObject<{
     model: ZodString;
     prompt: ZodString;
     width: ZodNumber;
     height: ZodNumber;
     steps: ZodOptional<ZodNumber>;
     durationSeconds: ZodOptional<ZodNumber>;
     resolution: ZodOptional<ZodEnum<{
        p480: "480p";
        p720: "720p";
        p768: "768p";
        p1080: "1080p";
        p4k: "4k";
     }>>;
     aspectRatio: ZodOptional<ZodEnum<{
        wide: "16:9";
        landscape: "4:3";
        square: "1:1";
        portrait: "3:4";
        tall: "9:16";
        ultrawide: "21:9";
        ultratall: "9:21";
     }>>;
     generateAudio: ZodOptional<ZodBoolean>;
     references: ZodOptional<ZodArray<ZodObject<{
        computerId: ZodString;
        path: ZodString;
        role: ZodOptional<ZodEnum<{
           first: ...;
           last: ...;
           reference: ...;
        }>>;
     }, $strict>>>;
  }, $strict>;
  outputFormat: ZodOptional<ZodEnum<{
     png: "png";
     jpeg: "jpeg";
     webp: "webp";
  }>>;
}, $strict>;

Decode relative service generation input. Identity comes from the host.

mediaUnits()function

Section titled “mediaUnits()”
Signature
function mediaUnits(settings): MediaUnits;

Billing units for validated settings; video bills its requested length.

Parameters

Section titled “Parameters”
Parameter Type
settings MediaGenerationSettings

Returns

Section titled “Returns”

MediaUnits

parseMediaBindingCall()function

Section titled “parseMediaBindingCall()”
Signature
function parseMediaBindingCall(raw):
  | Readonly<{
      kind: "parsed";
      call:
        | {
            operation: "models";
            input: Record<string, never>;
          }
        | {
            operation: "generate";
            input:
              | {
                  kind: "image";
                  requestId: string;
                  libraryPath: string;
                  settings: {
                    model: string;
                    prompt: string;
                    width: number;
                    height: number;
                    resolution?: "480p" | "720p" | "768p" | "1080p" | "4k";
                    aspectRatio?:
                      "16:9" | "4:3" | "1:1" | "3:4" | "9:16" | "21:9" | "9:21";
                    generateAudio?: boolean;
                    references?: object[];
                    steps?: number;
                  };
                  outputFormat?: "png" | "jpeg" | "webp";
                }
              | {
                  kind: "video";
                  requestId: string;
                  libraryPath: string;
                  settings: {
                    model:
                      | "bytedance/seedance-2.0"
                      | "bytedance/seedance-2.0-fast"
                      | "bytedance/seedance-2.0-mini"
                      | "google/veo-3.1"
                      | "google/veo-3.1-fast"
                      | "minimax/h3-max";
                    prompt: string;
                    resolution?: "480p" | "720p" | "768p" | "1080p" | "4k";
                    aspectRatio?:
                      "16:9" | "4:3" | "1:1" | "3:4" | "9:16" | "21:9" | "9:21";
                    durationSeconds?: number;
                    generateAudio?: boolean;
                    references?: object[];
                  };
                };
          };
    }>
  | Readonly<{
      kind: "refused";
      result: JSONType;
    }>;

Parsing and model refusal stay shared; authorization remains host-owned.

Parameters

Section titled “Parameters”
Parameter Type
raw JSONType

Returns

Section titled “Returns”

| Readonly<{ kind: "parsed"; call: | { operation: "models"; input: Record<string, never>; } | { operation: "generate"; input: | { kind: "image"; requestId: string; libraryPath: string; settings: { model: string; prompt: string; width: number; height: number; resolution?: "480p" | "720p" | "768p" | "1080p" | "4k"; aspectRatio?: "16:9" | "4:3" | "1:1" | "3:4" | "9:16" | "21:9" | "9:21"; generateAudio?: boolean; references?: object[]; steps?: number; }; outputFormat?: "png" | "jpeg" | "webp"; } | { kind: "video"; requestId: string; libraryPath: string; settings: { model: | "bytedance/seedance-2.0" | "bytedance/seedance-2.0-fast" | "bytedance/seedance-2.0-mini" | "google/veo-3.1" | "google/veo-3.1-fast" | "minimax/h3-max"; prompt: string; resolution?: "480p" | "720p" | "768p" | "1080p" | "4k"; aspectRatio?: "16:9" | "4:3" | "1:1" | "3:4" | "9:16" | "21:9" | "9:21"; durationSeconds?: number; generateAudio?: boolean; references?: object[]; }; }; }; }> | Readonly<{ kind: "refused"; result: JSONType; }>

mediaBindingRequest()function

Section titled “mediaBindingRequest()”
Signature
function mediaBindingRequest(input, computerId): MediaBindingRequest;

Choose the same fixed filename on both hosts without a recursive App lookup.

Parameters

Section titled “Parameters”
Parameter Type
input | { kind: "image"; requestId: string; libraryPath: string; settings: { model: string; prompt: string; width: number; height: number; resolution?: "480p" | "720p" | "768p" | "1080p" | "4k"; aspectRatio?: "16:9" | "4:3" | "1:1" | "3:4" | "9:16" | "21:9" | "9:21"; generateAudio?: boolean; references?: object[]; steps?: number; }; outputFormat?: "png" | "jpeg" | "webp"; } | { kind: "video"; requestId: string; libraryPath: string; settings: { model: | "bytedance/seedance-2.0" | "bytedance/seedance-2.0-fast" | "bytedance/seedance-2.0-mini" | "google/veo-3.1" | "google/veo-3.1-fast" | "minimax/h3-max"; prompt: string; resolution?: "480p" | "720p" | "768p" | "1080p" | "4k"; aspectRatio?: "16:9" | "4:3" | "1:1" | "3:4" | "9:16" | "21:9" | "9:21"; durationSeconds?: number; generateAudio?: boolean; references?: object[]; }; }
computerId string

Returns

Section titled “Returns”

MediaBindingRequest

readMediaBindingReply()function

Section titled “readMediaBindingReply()”
Signature
function readMediaBindingReply(input, computerId, response): Promise<JSONType>;

Decode bounded service replies once for both MEDIA host bindings.

Parameters

Section titled “Parameters”
Parameter Type
input | { operation: "models"; input: Record<string, never>; } | { operation: "generate"; input: | { kind: "image"; requestId: string; libraryPath: string; settings: { model: string; prompt: string; width: number; height: number; resolution?: "480p" | "720p" | "768p" | "1080p" | "4k"; aspectRatio?: "16:9" | "4:3" | "1:1" | "3:4" | "9:16" | "21:9" | "9:21"; generateAudio?: boolean; references?: object[]; steps?: number; }; outputFormat?: "png" | "jpeg" | "webp"; } | { kind: "video"; requestId: string; libraryPath: string; settings: { model: | "bytedance/seedance-2.0" | "bytedance/seedance-2.0-fast" | "bytedance/seedance-2.0-mini" | "google/veo-3.1" | "google/veo-3.1-fast" | "minimax/h3-max"; prompt: string; resolution?: "480p" | "720p" | "768p" | "1080p" | "4k"; aspectRatio?: "16:9" | "4:3" | "1:1" | "3:4" | "9:16" | "21:9" | "9:21"; durationSeconds?: number; generateAudio?: boolean; references?: object[]; }; }; }
computerId string
response Response

Returns

Section titled “Returns”

Promise<JSONType>

generateMedia()function

Section titled “generateMedia()”
Signature
function generateMedia(host, request, signal?): Promise<MediaGenerationOutcome>;

Generate through the Effect core with a Promise boundary preserving typed domain failures.

Parameters

Section titled “Parameters”
Parameter Type
host MediaServiceHost
request MediaGenerationRequest
signal? AbortSignal

Returns

Section titled “Returns”

Promise<MediaGenerationOutcome>

createMediaService()function

Section titled “createMediaService()”
Signature
function createMediaService(host): Hono<BlankEnv, BlankSchema, "/">;

Relative HTTP routes; the caller admits identity and supplies destination access.

Parameters

Section titled “Parameters”
Parameter Type
host MediaServiceHost

Returns

Section titled “Returns”

Hono<BlankEnv, BlankSchema, "/">