@opencode/ai 0.0.0-dev-20035 → 0.0.0-dev-20039

package/README.md

@@ -602,6 +602,86 @@ const program = Effect.gen(function* () {
 
 The hosted result is represented as a provider-executed tool call and tool result, and the generated image is also emitted as a first-class `media` `LLMEvent` (`response.message` then carries a `media` part). Gemini image-capable models emit the same `media` event for inline image output. Retaining `response.message` preserves the generated image for continuation on both routes.
 
+## Video generation
+
+Video mirrors `Image` with one difference: every provider is asynchronous, so the route is a submit-then-poll
+`Generation`. Models come from `.video(...)` selectors on the `Google` (Veo), `XAI`, `Fal`, and `Runway` facades.
+Common fields (`frames`, `references`, `video`, `durationSeconds`, `aspectRatio`, `resolution`, `audio`, `n`, `seed`,
+`negativePrompt`) lower natively or fail with a typed `AIError` before any network call; provider-native controls live
+under `providerOptions`, inferred from the selected model.
+
+```ts
+import { Video, VideoClient } from "@opencode/ai"
+import { Google } from "@opencode/ai/providers"
+
+const google = Google.configure({ apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY })
+
+// Simple: submit and wait.
+const program = Effect.gen(function* () {
+  const response = yield* Video.generate(
+    {
+      model: google.video("veo-3.1-generate-preview"),
+      prompt: "Panning wide shot of a calico kitten sleeping in the sunshine",
+      aspectRatio: "16:9",
+      resolution: "1080p",
+      durationSeconds: 8,
+      providerOptions: { personGeneration: "allow_adult" },
+    },
+    { poll: { interval: "10 seconds", timeout: "10 minutes" } },
+  )
+  // Veo serves files for two days behind the API key. The asset knows the deadline (`expiresAt`) and carries the
+  // download credentials only on the live instance (`asset.headers`), never in `source` or JSON: materialize
+  // before persisting, or the persisted URL cannot be fetched again.
+  return yield* response.video.materialize()
+})
+
+// Explicit control: keep the handle, persist the token, resume elsewhere.
+const controlled = Effect.gen(function* () {
+  const generation = yield* Video.start({ model: google.video("veo-3.1-generate-preview"), prompt })
+  generation.id // provider operation / task / request id
+  generation.status // "queued" | "running" | "completed" | "failed" | "cancelled" | "expired"
+  generation.token // route-owned JSON: `{ operation }`, `{ requestID }`, `{ taskID }`, or fal's follow-up URLs
+  const saved = JSON.stringify(generation.token)
+
+  const resumed = yield* Video.resume(google.video("veo-3.1-generate-preview"), JSON.parse(saved))
+  return yield* resumed.await({ poll: { interval: "10 seconds" } })
+})
+
+// Progress as a stream: generation-queued | generation-progress | video | finish.
+const events = Video.stream({ model: Runway.configure({ apiKey }).video("gen4.5"), prompt }, { poll })
+```
+
+`VideoClient.layer` needs `RequestExecutor.Service`, and status polls, result fetches, cancels, and asset downloads
+all run through the same executor with the route's auth. `Generation.await` and `Generation.events` fail with a
+`Timeout` reason when `poll.timeout` (default 10 minutes) elapses. Failed,
+cancelled, and expired generations fail typed with the provider's terminal document on `reason.body`; moderation
+outcomes (Veo `raiMediaFilteredReasons`, xAI `respect_moderation`, Runway `SAFETY.*` codes) surface as `notices` when
+a video is still returned and as a `ContentPolicy` reason when nothing is.
+
+Provider notes:
+
+- **Google Veo** takes inline bytes only (materialize `url` assets first); `frames.last` requires `frames.first`;
+  audio is always on, so `audio: false` fails typed; one video per request. Output URLs need the API key to
+  download, which the returned asset holds transiently (see above).
+- **xAI** sends a `video` input to `/videos/edits`, or `/videos/extensions` with `providerOptions.mode: "extend"`.
+  `seed` and `negativePrompt` are not supported.
+- **fal** endpoints are model-specific: `durationSeconds`, `references`, and `frames.last` fail typed and belong in
+  `providerOptions` under the model's own names (`duration: "8s"`, `end_image_url`, …). Auth is
+  `Authorization: Key <FAL_KEY>`.
+- **Runway** expects pixel ratios in `aspectRatio` for most models (`"1280:720"`), pins `X-Runway-Version`, reports
+  `usage: { type: "credits" }`, and its output URLs expire after 24–48 hours.
+
+The promise client exposes the same surface: `ai.video.start(...)` resolves to a handle with `await`, `refresh`,
+`cancel`, and `token`; `ai.video.generate`, `ai.video.resume(model, token)`, and `ai.video.stream` mirror the Effect
+API.
+
+```ts
+import { ai } from "@opencode/ai/promise"
+
+const generation = await ai.video.start({ model, prompt })
+const video = await generation.await({ poll: { interval: 10_000 }, signal })
+```
+
 ## Public API
 
 - **`LLM.request({...})`** — build a provider-neutral `LLMRequest`. Accepts ergonomic inputs (`system: string`, `prompt: string`) that normalize into the canonical Schema classes.

package/dist/generation.d.ts

@@ -12,13 +12,13 @@ export interface Snapshot {
     readonly expiresAt?: number;
 }
 /**
- * Route-owned generation operations. `token` is the route's serializable handle (operation name, task id, response URL)
- * so a generation can be resumed from another process; its shape is opaque to `Generation`.
+ * Route-owned generation operations for one generation. The media route decodes its serializable token once (from the
+ * submission response or a `resume` input) and closes over it, so `Generation` never sees the token's shape.
  */
 export interface Route<Response> {
-    readonly status: (token: unknown) => Effect.Effect<Snapshot, AIError>;
-    readonly result: (token: unknown) => Effect.Effect<Response, AIError>;
-    readonly cancel?: (token: unknown) => Effect.Effect<void, AIError>;
+    readonly status: Effect.Effect<Snapshot, AIError>;
+    readonly result: Effect.Effect<Response, AIError>;
+    readonly cancel?: Effect.Effect<void, AIError>;
     /** Provider polling hint (e.g. `openai-poll-after-ms`) that overrides the default interval for the next poll. */
     readonly pollHint?: (snapshot: Snapshot) => Duration.Duration | undefined;
 }
@@ -28,6 +28,9 @@ export interface Poll {
     /** Full override of the polling schedule; `interval` and `pollHint` are ignored when supplied. */
     readonly schedule?: Schedule.Schedule<unknown, Snapshot>;
 }
+export interface AwaitOptions {
+    readonly poll?: Poll;
+}
 export declare const DEFAULT_POLL_INTERVAL: Duration.Duration;
 export declare const DEFAULT_POLL_TIMEOUT: Duration.Duration;
 export type Event = {
@@ -45,25 +48,32 @@ export type Event = {
 };
 export declare class Generation<Response> {
     readonly route: Route<Response>;
+    /** Route-owned serializable JSON; pass it to the modality's `resume` from another process. */
     readonly token: unknown;
     readonly id: string;
     readonly status: Status;
     readonly progress?: number;
     readonly position?: number;
     readonly expiresAt?: number;
-    constructor(route: Route<Response>, token: unknown, snapshot: Snapshot);
+    constructor(route: Route<Response>, 
+    /** Route-owned serializable JSON; pass it to the modality's `resume` from another process. */
+    token: unknown, snapshot: Snapshot);
     get snapshot(): Snapshot;
     get terminal(): boolean;
     refresh(): Effect.Effect<Generation<Response>, AIError>;
+    /** Fetch the result without polling; non-completed terminal generations fail with the provider's terminal body. */
+    result(): Effect.Effect<Response, AIError>;
     /** Poll until the generation reaches a terminal status, then fetch the result. Fails with a `Timeout` reason on deadline. */
-    await(options?: {
-        readonly poll?: Poll;
-    }): Effect.Effect<Response, AIError>;
+    await(options?: AwaitOptions): Effect.Effect<Response, AIError>;
     cancel(): Effect.Effect<void, AIError>;
-    /** Status observations as a stream, ending after the first terminal observation. */
-    events(options?: {
-        readonly poll?: Poll;
-    }): Stream.Stream<Event, AIError>;
+    /**
+     * Status observations as a stream, ending after the first terminal observation. Each poll is bounded by the time
+     * remaining until `poll.timeout`, so a hung status request fails the stream instead of stalling it. (`Stream.interruptWhen`
+     * would express this directly but deadlocks under `TestClock` when the source completes while the timer sleeps.)
+     */
+    events(options?: AwaitOptions): Stream.Stream<Event, AIError>;
+    private event;
+    private timeoutError;
     private poll;
     private schedule;
 }

package/dist/generation.js

@@ -1,4 +1,4 @@
-import { Duration, Effect, Schedule, Schema, Stream } from "effect";
+import { Clock, Duration, Effect, Schedule, Schema, Stream } from "effect";
 import { AIError, TimeoutError } from "./schema/errors.js";
 export const Status = Schema.Literals(["queued", "running", "completed", "failed", "cancelled", "expired"]);
 export const DEFAULT_POLL_INTERVAL = Duration.seconds(5);
@@ -12,7 +12,9 @@ export class Generation {
     progress;
     position;
     expiresAt;
-    constructor(route, token, snapshot) {
+    constructor(route, 
+    /** Route-owned serializable JSON; pass it to the modality's `resume` from another process. */
+    token, snapshot) {
         this.route = route;
         this.token = token;
         this.id = snapshot.id;
@@ -34,7 +36,11 @@ export class Generation {
         return TERMINAL.has(this.status);
     }
     refresh() {
-        return this.route.status(this.token).pipe(Effect.map((snapshot) => new Generation(this.route, this.token, snapshot)));
+        return this.route.status.pipe(Effect.map((snapshot) => new Generation(this.route, this.token, snapshot)));
+    }
+    /** Fetch the result without polling; non-completed terminal generations fail with the provider's terminal body. */
+    result() {
+        return this.route.result;
     }
     /** Poll until the generation reaches a terminal status, then fetch the result. Fails with a `Timeout` reason on deadline. */
     await(options) {
@@ -42,31 +48,43 @@ export class Generation {
         const settled = this.terminal ? Effect.succeed(this) : this.poll(options?.poll);
         return settled.pipe(
         // Non-completed terminal states also go through `result` so the route can surface its provider failure body.
-        Effect.flatMap((generation) => generation.route.result(generation.token)), Effect.timeoutOrElse({
-            duration: timeout,
-            orElse: () => new AIError({
-                reason: new TimeoutError({
-                    message: `Generation ${this.id} did not finish within ${Duration.format(timeout)}`,
-                    timeoutMs: Duration.toMillis(timeout),
-                }),
-            }),
-        }));
+        Effect.flatMap((generation) => generation.result()), Effect.timeoutOrElse({ duration: timeout, orElse: () => this.timeoutError(timeout) }));
     }
     cancel() {
-        return this.route.cancel?.(this.token) ?? Effect.void;
+        return this.route.cancel ?? Effect.void;
     }
-    /** Status observations as a stream, ending after the first terminal observation. */
+    /**
+     * Status observations as a stream, ending after the first terminal observation. Each poll is bounded by the time
+     * remaining until `poll.timeout`, so a hung status request fails the stream instead of stalling it. (`Stream.interruptWhen`
+     * would express this directly but deadlocks under `TestClock` when the source completes while the timer sleeps.)
+     */
     events(options) {
-        const observations = this.terminal
-            ? Stream.make(this)
-            : Stream.fromEffectSchedule(this.refresh(), this.schedule(options?.poll)).pipe(Stream.takeUntil((generation) => generation.terminal));
-        return observations.pipe(Stream.map((generation) => {
-            if (generation.terminal)
-                return { type: "generation-finished", id: generation.id, status: generation.status };
-            if (generation.status === "queued")
-                return { type: "generation-queued", id: generation.id, position: generation.position };
-            return { type: "generation-progress", id: generation.id, progress: generation.progress };
-        }));
+        if (this.terminal)
+            return Stream.make(this.event());
+        const timeout = Duration.fromInputUnsafe(options?.poll?.timeout ?? DEFAULT_POLL_TIMEOUT);
+        return Stream.unwrap(Clock.currentTimeMillis.pipe(Effect.map((start) => {
+            const deadline = start + Duration.toMillis(timeout);
+            const refresh = Clock.currentTimeMillis.pipe(Effect.flatMap((now) => this.refresh().pipe(Effect.timeoutOrElse({
+                duration: Duration.millis(Math.max(0, deadline - now)),
+                orElse: () => this.timeoutError(timeout),
+            }))));
+            return Stream.fromEffectSchedule(refresh, this.schedule(options?.poll)).pipe(Stream.takeUntil((generation) => generation.terminal), Stream.map((generation) => generation.event()));
+        })));
+    }
+    event() {
+        if (this.terminal)
+            return { type: "generation-finished", id: this.id, status: this.status };
+        if (this.status === "queued")
+            return { type: "generation-queued", id: this.id, position: this.position };
+        return { type: "generation-progress", id: this.id, progress: this.progress };
+    }
+    timeoutError(timeout) {
+        return new AIError({
+            reason: new TimeoutError({
+                message: `Generation ${this.id} did not finish within ${Duration.format(timeout)}`,
+                timeoutMs: Duration.toMillis(timeout),
+            }),
+        });
     }
     poll(poll) {
         return this.refresh().pipe(Effect.repeat({ schedule: this.schedule(poll), until: (generation) => generation.terminal }));

package/dist/image-client.js

@@ -17,7 +17,7 @@ export const layer = Layer.effect(Service, Effect.gen(function* () {
     return Service.of({
         generate,
         // Inline routes have no partial frames yet; the stream is the completed response expanded into events.
-        stream: (request) => Stream.unwrap(generate(request).pipe(Effect.map((response) => Stream.fromIterable(responseEvents(response))))),
+        stream: (request) => Stream.fromIterableEffect(Effect.map(generate(request), responseEvents)),
     });
 }));
 export const ImageClient = {

package/dist/image.d.ts

@@ -1,47 +1,25 @@
 import { Effect, Schema, Stream } from "effect";
 import { Media } from "./media.js";
-import { Endpoint } from "./route/endpoint.js";
+import { MediaModel } from "./media-model.js";
 import { MediaRoute } from "./route/media.js";
 import type { MediaProtocol } from "./route/media-protocol.js";
-import { AIError, HttpOptions, ModelID, ProviderID } from "./schema/index.js";
+import { AIError, HttpOptions } from "./schema/index.js";
 import { Service } from "./image-client.js";
 export type ImageOptions = Record<string, unknown>;
 export type ImageRoute<Options extends ImageOptions = ImageOptions> = MediaRoute.Route<ImageRequestFor<Options>, ImageResponse>;
-export declare class ImageModel<Options extends ImageOptions = ImageOptions> {
-    protected readonly _Options: (options: Options) => Options;
-    readonly id: ModelID;
-    readonly provider: ProviderID;
-    readonly route: ImageRoute<Options>;
-    readonly http?: HttpOptions;
-    constructor(input: ImageModel.Input<Options>);
-    static make<Options extends ImageOptions = ImageOptions>(input: ImageModel.MakeInput<Options>): ImageModel<Options>;
+export declare class ImageModel<Options extends ImageOptions = ImageOptions> extends MediaModel<ImageRoute<Options>, Options> {
+    protected readonly _ImageModel: void;
+    static make<Options extends ImageOptions = ImageOptions>(input: MediaModel.Input<ImageRoute<Options>>): ImageModel<Options>;
     /** Compose an inline image protocol with its canonical path into a model for one deployment. */
     static fromRoute<Options extends ImageOptions = ImageOptions>(route: ImageModel.RouteInput<Options>, input: MediaRoute.ModelInput): ImageModel<Options>;
 }
 export declare namespace ImageModel {
-    interface Input<Options extends ImageOptions = ImageOptions> {
-        readonly id: ModelID;
-        readonly provider: ProviderID;
-        readonly route: ImageRoute<Options>;
-        readonly http?: HttpOptions;
-    }
-    interface MakeInput<Options extends ImageOptions = ImageOptions> extends Omit<Input<Options>, "id" | "provider"> {
-        readonly id: string | ModelID;
-        readonly provider: string | ProviderID;
-    }
-    interface RouteInput<Options extends ImageOptions = ImageOptions> {
-        readonly id: string;
-        readonly provider: string | ProviderID;
-        readonly protocol: MediaProtocol.Inline<ImageRequestFor<Options>, ImageResponse>;
-        readonly path: Endpoint.EndpointPart<MediaProtocol.Body, ImageRequestFor<Options>>;
-        /** Canonical base URL; `ModelInput.baseURL` overrides it per deployment. */
-        readonly baseURL?: string;
-    }
+    type RouteInput<Options extends ImageOptions = ImageOptions> = MediaModel.RouteInput<ImageRequestFor<Options>, MediaProtocol.Inline<ImageRequestFor<Options>, ImageResponse>>;
 }
 export declare const ImageModelSchema: Schema.declare<ImageModel<ImageOptions>, ImageModel<ImageOptions>>;
 export type ImageSize = `${number}x${number}`;
 export declare const ImageSize: Schema.declare<`${number}x${number}`, `${number}x${number}`>;
-export type ImageAspectRatio = `${number}:${number}`;
+export type ImageAspectRatio = Media.AspectRatio;
 export declare const ImageAspectRatio: Schema.declare<`${number}:${number}`, `${number}:${number}`>;
 export type ImageFormat = "png" | "jpeg" | "webp" | (string & {});
 declare const ImageRequest_base: Schema.Class<ImageRequest, Schema.Struct<{
@@ -62,7 +40,6 @@ declare const ImageRequest_base: Schema.Class<ImageRequest, Schema.Struct<{
             readonly url: Schema.String;
             readonly mediaType: Schema.optional<Schema.String>;
             readonly expiresAt: Schema.optional<Schema.Number>;
-            readonly headers: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
         }>, Schema.Struct<{
             readonly type: Schema.Literal<"ref">;
             readonly provider: Schema.brand<Schema.String, "AI.ProviderID">;
@@ -95,7 +72,6 @@ declare const ImageRequest_base: Schema.Class<ImageRequest, Schema.Struct<{
             readonly url: Schema.String;
             readonly mediaType: Schema.optional<Schema.String>;
             readonly expiresAt: Schema.optional<Schema.Number>;
-            readonly headers: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
         }>, Schema.Struct<{
             readonly type: Schema.Literal<"ref">;
             readonly provider: Schema.brand<Schema.String, "AI.ProviderID">;
@@ -150,7 +126,6 @@ declare const ImageResponse_base: Schema.Class<ImageResponse, Schema.Struct<{
             readonly url: Schema.String;
             readonly mediaType: Schema.optional<Schema.String>;
             readonly expiresAt: Schema.optional<Schema.Number>;
-            readonly headers: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
         }>, Schema.Struct<{
             readonly type: Schema.Literal<"ref">;
             readonly provider: Schema.brand<Schema.String, "AI.ProviderID">;
@@ -214,7 +189,6 @@ export declare const ImageOutputEvent: Schema.Struct<{
             readonly url: Schema.String;
             readonly mediaType: Schema.optional<Schema.String>;
             readonly expiresAt: Schema.optional<Schema.Number>;
-            readonly headers: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
         }>, Schema.Struct<{
             readonly type: Schema.Literal<"ref">;
             readonly provider: Schema.brand<Schema.String, "AI.ProviderID">;
@@ -278,7 +252,6 @@ declare const imageEventTagged: Schema.toTaggedUnion<"type", readonly [Schema.St
             readonly url: Schema.String;
             readonly mediaType: Schema.optional<Schema.String>;
             readonly expiresAt: Schema.optional<Schema.Number>;
-            readonly headers: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
         }>, Schema.Struct<{
             readonly type: Schema.Literal<"ref">;
             readonly provider: Schema.brand<Schema.String, "AI.ProviderID">;
@@ -341,7 +314,6 @@ export declare const ImageEvent: Schema.Union<readonly [Schema.Struct<{
             readonly url: Schema.String;
             readonly mediaType: Schema.optional<Schema.String>;
             readonly expiresAt: Schema.optional<Schema.Number>;
-            readonly headers: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
         }>, Schema.Struct<{
             readonly type: Schema.Literal<"ref">;
             readonly provider: Schema.brand<Schema.String, "AI.ProviderID">;
@@ -406,7 +378,6 @@ export declare const ImageEvent: Schema.Union<readonly [Schema.Struct<{
                     readonly url: Schema.String;
                     readonly mediaType: Schema.optional<Schema.String>;
                     readonly expiresAt: Schema.optional<Schema.Number>;
-                    readonly headers: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
                 }>, Schema.Struct<{
                     readonly type: Schema.Literal<"ref">;
                     readonly provider: Schema.brand<Schema.String, "AI.ProviderID">;

package/dist/image.js

@@ -1,42 +1,20 @@
 import { Effect, Schema, Stream } from "effect";
 import { Media } from "./media.js";
-import { Endpoint } from "./route/endpoint.js";
+import { MediaModel, composeRoute, tryRequest } from "./media-model.js";
 import { MediaRoute } from "./route/media.js";
-import { AIError, HttpOptions, InvalidRequestError, MediaUsage, ModelID, ProviderID, ProviderMetadata, } from "./schema/index.js";
+import { AIError, HttpOptions, MediaUsage, ProviderMetadata } from "./schema/index.js";
 import { ImageClient, Service } from "./image-client.js";
-export class ImageModel {
-    id;
-    provider;
-    route;
-    http;
-    constructor(input) {
-        this.id = input.id;
-        this.provider = input.provider;
-        this.route = input.route;
-        this.http = input.http;
-    }
+export class ImageModel extends MediaModel {
     static make(input) {
-        return new ImageModel({
-            id: ModelID.make(input.id),
-            provider: ProviderID.make(input.provider),
-            route: input.route,
-            http: input.http,
-        });
+        return new ImageModel(input);
     }
     /** Compose an inline image protocol with its canonical path into a model for one deployment. */
     static fromRoute(route, input) {
-        return ImageModel.make({
+        return new ImageModel({
             id: input.id,
             provider: route.provider,
             http: input.http,
-            route: MediaRoute.make({
-                id: route.id,
-                provider: route.provider,
-                protocol: route.protocol,
-                endpoint: Endpoint.path(route.path, { baseURL: input.baseURL ?? route.baseURL }),
-                auth: input.auth,
-                headers: input.headers,
-            }),
+            route: composeRoute(MediaRoute.inline, route, input),
         });
     }
 }
@@ -44,7 +22,7 @@ export const ImageModelSchema = Schema.declare((value) => value instanceof Image
     expected: "Image.Model",
 });
 export const ImageSize = Schema.declare((value) => typeof value === "string" && /^\d+x\d+$/.test(value), { title: "ImageSize" });
-export const ImageAspectRatio = Schema.declare((value) => typeof value === "string" && /^\d+(?:\.\d+)?:\d+(?:\.\d+)?$/.test(value), { title: "ImageAspectRatio" });
+export const ImageAspectRatio = Media.AspectRatio;
 export class ImageRequest extends Schema.Class("Image.Request")({
     model: ImageModelSchema,
     prompt: Schema.String,
@@ -109,15 +87,7 @@ export function request(input) {
         http: input.http === undefined ? undefined : HttpOptions.make(input.http),
     });
 }
-const requestEffect = (input) => Effect.try({
-    try: () => request(input),
-    catch: (error) => new AIError({
-        reason: new InvalidRequestError({
-            message: error instanceof Error ? error.message : String(error),
-            cause: error,
-        }),
-    }),
-});
+const requestEffect = (input) => tryRequest(() => request(input));
 export function generate(input) {
     return requestEffect(input).pipe(Effect.flatMap((request) => ImageClient.generate(request)));
 }

package/dist/index.d.ts

@@ -9,9 +9,13 @@ export * from "./schema/index.js";
 export { ImageAspectRatio, ImageEvent, ImageModel, ImageModelSchema, ImageRequest, ImageResponse, ImageSize, } from "./image.js";
 export type { ImageFormat, ImageModelOptions, ImageOptions, ImageRequestFor, ImageRequestInput, ImageRoute, } from "./image.js";
 export { Image } from "./image.js";
+export { VideoClient } from "./video-client.js";
+export { VideoAspectRatio, VideoEvent, VideoFrames, VideoModel, VideoModelSchema, VideoRequest, VideoResponse, } from "./video.js";
+export type { VideoModelOptions, VideoOptions, VideoRequestFor, VideoRequestInput, VideoResolution, VideoRoute, } from "./video.js";
+export { Video } from "./video.js";
 export { Media } from "./media.js";
 export { Generation } from "./generation.js";
-export type { Event as GenerationEvent, Poll, Route as GenerationRoute, Snapshot as GenerationSnapshot, Status as GenerationStatus } from "./generation.js";
+export type { AwaitOptions as GenerationAwaitOptions, Event as GenerationEvent, Poll, Route as GenerationRoute, Snapshot as GenerationSnapshot, Status as GenerationStatus, } from "./generation.js";
 export { Tool, ToolFailure, toDefinitions } from "./tool.js";
 export { ToolRuntime } from "./tool-runtime.js";
 export type { DispatchResult as ToolDispatchResult, ToolSettlement } from "./tool-runtime.js";

package/dist/index.js

@@ -7,6 +7,9 @@ export { isContextOverflow, isContextOverflowFailure } from "./provider-error.js
 export * from "./schema/index.js";
 export { ImageAspectRatio, ImageEvent, ImageModel, ImageModelSchema, ImageRequest, ImageResponse, ImageSize, } from "./image.js";
 export { Image } from "./image.js";
+export { VideoClient } from "./video-client.js";
+export { VideoAspectRatio, VideoEvent, VideoFrames, VideoModel, VideoModelSchema, VideoRequest, VideoResponse, } from "./video.js";
+export { Video } from "./video.js";
 export { Media } from "./media.js";
 export { Generation } from "./generation.js";
 export { Tool, ToolFailure, toDefinitions } from "./tool.js";

package/dist/media-model.d.ts

@@ -0,0 +1,42 @@
+import { Effect } from "effect";
+import { Endpoint } from "./route/endpoint.js";
+import type { MediaRoute } from "./route/media.js";
+import type { MediaProtocol } from "./route/media-protocol.js";
+import { AIError, HttpOptions, ModelID, ProviderID } from "./schema/index.js";
+/**
+ * What every media model carries: ids, the configured route, and deployment `http` overlays. Modality classes
+ * (`ImageModel`, `VideoModel`) extend it with their route type and a nominal marker so one cannot stand in for the
+ * other in requests.
+ */
+export declare class MediaModel<Route, Options> {
+    protected readonly _Options: (options: Options) => Options;
+    readonly id: ModelID;
+    readonly provider: ProviderID;
+    readonly route: Route;
+    readonly http?: HttpOptions;
+    constructor(input: MediaModel.Input<Route>);
+}
+export declare namespace MediaModel {
+    interface Input<Route> {
+        readonly id: string | ModelID;
+        readonly provider: string | ProviderID;
+        readonly route: Route;
+        readonly http?: HttpOptions;
+    }
+    /** A protocol plus its canonical start path; `ModelInput.baseURL` overrides `baseURL` per deployment. */
+    interface RouteInput<Request extends MediaRoute.MediaRequest, Protocol> {
+        readonly id: string;
+        readonly provider: string | ProviderID;
+        readonly protocol: Protocol;
+        readonly path: Endpoint.EndpointPart<MediaProtocol.Body, Request>;
+        readonly baseURL?: string;
+        /** Headers the protocol requires on every call, such as a pinned API version; deployment headers win. */
+        readonly headers?: Record<string, string>;
+    }
+}
+/** Compose a protocol route input with one deployment through `MediaRoute.inline` or `MediaRoute.queued`. */
+export declare const composeRoute: <Request extends MediaRoute.MediaRequest, Protocol, Route>(compose: (input: MediaRoute.Composition<Request> & {
+    readonly protocol: Protocol;
+}) => Route, route: MediaModel.RouteInput<Request, Protocol>, input: MediaRoute.ModelInput) => Route;
+/** Lift a synchronous Schema-class constructor into a typed `InvalidRequest` failure. */
+export declare const tryRequest: <A>(make: () => A) => Effect.Effect<A, AIError>;

package/dist/media-model.js

@@ -0,0 +1,39 @@
+import { Effect } from "effect";
+import { Endpoint } from "./route/endpoint.js";
+import { AIError, HttpOptions, InvalidRequestError, ModelID, ProviderID } from "./schema/index.js";
+/**
+ * What every media model carries: ids, the configured route, and deployment `http` overlays. Modality classes
+ * (`ImageModel`, `VideoModel`) extend it with their route type and a nominal marker so one cannot stand in for the
+ * other in requests.
+ */
+export class MediaModel {
+    id;
+    provider;
+    route;
+    http;
+    constructor(input) {
+        this.id = ModelID.make(input.id);
+        this.provider = ProviderID.make(input.provider);
+        this.route = input.route;
+        this.http = input.http;
+    }
+}
+/** Compose a protocol route input with one deployment through `MediaRoute.inline` or `MediaRoute.queued`. */
+export const composeRoute = (compose, route, input) => compose({
+    id: route.id,
+    provider: route.provider,
+    protocol: route.protocol,
+    endpoint: Endpoint.path(route.path, { baseURL: input.baseURL ?? route.baseURL }),
+    auth: input.auth,
+    headers: route.headers === undefined && input.headers === undefined ? undefined : { ...route.headers, ...input.headers },
+});
+/** Lift a synchronous Schema-class constructor into a typed `InvalidRequest` failure. */
+export const tryRequest = (make) => Effect.try({
+    try: make,
+    catch: (error) => new AIError({
+        reason: new InvalidRequestError({
+            message: error instanceof Error ? error.message : String(error),
+            cause: error,
+        }),
+    }),
+});

package/dist/media.d.ts

@@ -19,8 +19,6 @@ export declare const Source: Schema.Union<readonly [Schema.Struct<{
     readonly mediaType: Schema.optional<Schema.String>;
     /** Epoch milliseconds after which the provider no longer serves the URL. */
     readonly expiresAt: Schema.optional<Schema.Number>;
-    /** Headers required to fetch the URL, such as provider auth for Veo downloads. */
-    readonly headers: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
 }>, Schema.Struct<{
     readonly type: Schema.Literal<"ref">;
     readonly provider: Schema.brand<Schema.String, "AI.ProviderID">;
@@ -28,6 +26,8 @@ export declare const Source: Schema.Union<readonly [Schema.Struct<{
     readonly mediaType: Schema.optional<Schema.String>;
 }>]>;
 export type Source = Schema.Schema.Type<typeof Source>;
+export type AspectRatio = `${number}:${number}`;
+export declare const AspectRatio: Schema.declare<`${number}:${number}`, `${number}:${number}`>;
 export declare const Kind: Schema.Literals<readonly ["image", "video", "audio", "document", "other"]>;
 export type Kind = Schema.Schema.Type<typeof Kind>;
 export declare const kindOf: (mediaType: string) => Kind;
@@ -65,6 +65,8 @@ export declare class Asset {
     /** Epoch milliseconds after which a `url` source stops resolving. */
     readonly expiresAt?: number;
     readonly providerMetadata?: ProviderMetadata;
+    /** Transient download credentials for `url` sources; see `Asset.Input.headers`. */
+    readonly headers?: Record<string, string>;
     constructor(input: Asset.Input);
     /** Inline payload without effects, for protocols that embed base64 or data URLs directly. */
     inline(): Inline | undefined;
@@ -84,9 +86,6 @@ export declare class Asset {
         } | {
             readonly type: "url";
             readonly url: string;
-            readonly headers?: {
-                readonly [x: string]: string;
-            } | undefined;
             readonly mediaType?: string | undefined;
             readonly expiresAt?: number | undefined;
         } | {
@@ -122,6 +121,12 @@ export declare namespace Asset {
         readonly source: Source;
         readonly info?: Info;
         readonly providerMetadata?: ProviderMetadata;
+        /**
+         * Headers required to download a `url` source, such as the provider API key Veo demands for its file URIs.
+         * They are runtime-only: never part of `source`, `toJSON()`, or `AssetSchema`, so a persisted asset cannot leak
+         * credentials and cannot be downloaded again after a round-trip. Call `materialize()` before persisting.
+         */
+        readonly headers?: Record<string, string>;
     }
 }
 /** JSON form of an asset: the serializable `Source` plus caller-supplied metadata. `bytes` sources encode as base64. */
@@ -140,8 +145,6 @@ export declare const AssetEncoded: Schema.Struct<{
         readonly mediaType: Schema.optional<Schema.String>;
         /** Epoch milliseconds after which the provider no longer serves the URL. */
         readonly expiresAt: Schema.optional<Schema.Number>;
-        /** Headers required to fetch the URL, such as provider auth for Veo downloads. */
-        readonly headers: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
     }>, Schema.Struct<{
         readonly type: Schema.Literal<"ref">;
         readonly provider: Schema.brand<Schema.String, "AI.ProviderID">;
@@ -175,8 +178,6 @@ export declare const AssetSchema: Schema.decodeTo<Schema.declare<Asset, Asset>,
         readonly mediaType: Schema.optional<Schema.String>;
         /** Epoch milliseconds after which the provider no longer serves the URL. */
         readonly expiresAt: Schema.optional<Schema.Number>;
-        /** Headers required to fetch the URL, such as provider auth for Veo downloads. */
-        readonly headers: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
     }>, Schema.Struct<{
         readonly type: Schema.Literal<"ref">;
         readonly provider: Schema.brand<Schema.String, "AI.ProviderID">;