@opencode-ai/ai 0.0.0-next-15910 → 0.0.0-next-15911

package/README.md

@@ -29,7 +29,7 @@ Run `LLMClient.stream(request)` instead of `generate` when you want incremental
 Use `Image.generate` with an image model for direct asset generation:
 
 ```ts
-import { Image } from "@opencode-ai/ai"
+import { Image, ImageInput } from "@opencode-ai/ai"
 import { OpenAI } from "@opencode-ai/ai/providers"
 
 const program = Effect.gen(function* () {
@@ -49,6 +49,48 @@ const program = Effect.gen(function* () {
 })
 ```
 
+Pass ordered image inputs to the same method for editing, composition, or image-conditioned generation:
+
+```ts
+const response =
+  yield *
+  Image.generate({
+    model,
+    prompt: "Combine these product photos into one studio scene",
+    images: [
+      ImageInput.bytes(firstBytes, "image/png"),
+      ImageInput.url("https://example.com/second.webp"),
+      ImageInput.file("file_123"),
+    ],
+    options,
+    http,
+  })
+```
+
+`ImageInput.fileUri(uri, mediaType)` represents provider file URIs such as Gemini Files. Raw strings are not
+accepted as image inputs, avoiding ambiguity between base64, URLs, and provider IDs. Empty or omitted `images`
+uses text-to-image generation; a non-empty array selects the provider's edit behavior without enforcing provider
+image-count limits locally. `images` is the only common image-editing field. OpenAI uses multipart for byte/data-URL
+edits and its JSON reference body for URL or file-ID edits. Its provider-specific `options.mask` accepts an
+`ImageInput` for inpainting:
+
+```ts
+yield *
+  Image.generate({
+    model: OpenAI.configure({ apiKey }).image("gpt-image-2"),
+    prompt,
+    images: [ImageInput.bytes(sourceBytes, "image/png")],
+    options: { mask: ImageInput.bytes(maskBytes, "image/png") },
+  })
+```
+
+The OpenAI adapter extracts this helper value into the edit request's native `mask` field rather than passing the
+tagged `ImageInput` object through as an ordinary option. On multipart requests, `http.body` can override option
+fields but not structural `model`, `prompt`, `image[]`, or `mask` fields, and the transport owns the multipart
+`Content-Type` boundary. For JSON requests, `http.body` remains the final raw-native overlay. Gemini does not fetch
+public HTTP URLs, and hosted Z.ai image generation does not accept image inputs. These cases fail with
+`InvalidRequest` before network I/O.
+
 Provider-native image options belong to each request. Raw `http.body` fields have final precedence over them:
 
 ```ts

package/dist/image.d.ts

@@ -28,9 +28,46 @@ export declare namespace ImageModel {
     }
 }
 export declare const ImageModelSchema: Schema.declare<ImageModel<ImageOptions>, ImageModel<ImageOptions>>;
+export declare const ImageInputSchema: Schema.toTaggedUnion<"type", readonly [Schema.Struct<{
+    readonly type: Schema.Literal<"bytes">;
+    readonly data: Schema.Uint8Array;
+    readonly mediaType: Schema.String;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"url">;
+    readonly url: Schema.String;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"file-id">;
+    readonly id: Schema.String;
+}>, Schema.Struct<{
+    readonly type: Schema.Literal<"file-uri">;
+    readonly uri: Schema.String;
+    readonly mediaType: Schema.String;
+}>]>;
+export type ImageInput = Schema.Schema.Type<typeof ImageInputSchema>;
+export declare const ImageInput: {
+    readonly bytes: (data: Uint8Array, mediaType: string) => ImageInput;
+    readonly url: (url: string) => ImageInput;
+    readonly file: (id: string) => ImageInput;
+    readonly fileUri: (uri: string, mediaType: string) => ImageInput;
+};
 declare const ImageRequest_base: Schema.Class<ImageRequest, Schema.Struct<{
     readonly model: Schema.declare<ImageModel<ImageOptions>, ImageModel<ImageOptions>>;
     readonly prompt: Schema.String;
+    readonly images: Schema.optional<Schema.$Array<Schema.toTaggedUnion<"type", readonly [Schema.Struct<{
+        readonly type: Schema.Literal<"bytes">;
+        readonly data: Schema.Uint8Array;
+        readonly mediaType: Schema.String;
+    }>, Schema.Struct<{
+        readonly type: Schema.Literal<"url">;
+        readonly url: Schema.String;
+    }>, Schema.Struct<{
+        readonly type: Schema.Literal<"file-id">;
+        readonly id: Schema.String;
+    }>, Schema.Struct<{
+        readonly type: Schema.Literal<"file-uri">;
+        readonly uri: Schema.String;
+        readonly mediaType: Schema.String;
+    }>]>>>;
     readonly options: Schema.optional<Schema.$Record<Schema.String, Schema.Unknown>>;
     readonly http: Schema.optional<typeof HttpOptions>;
 }>, {}>;

package/dist/image.js

@@ -24,9 +24,40 @@ export class ImageModel {
 export const ImageModelSchema = Schema.declare((value) => value instanceof ImageModel, {
     expected: "Image.Model",
 });
+const ImageBytesInput = Schema.Struct({
+    type: Schema.Literal("bytes"),
+    data: Schema.Uint8Array,
+    mediaType: Schema.String,
+});
+const ImageUrlInput = Schema.Struct({
+    type: Schema.Literal("url"),
+    url: Schema.String,
+});
+const ImageFileIDInput = Schema.Struct({
+    type: Schema.Literal("file-id"),
+    id: Schema.String,
+});
+const ImageFileURIInput = Schema.Struct({
+    type: Schema.Literal("file-uri"),
+    uri: Schema.String,
+    mediaType: Schema.String,
+});
+export const ImageInputSchema = Schema.Union([
+    ImageBytesInput,
+    ImageUrlInput,
+    ImageFileIDInput,
+    ImageFileURIInput,
+]).pipe(Schema.toTaggedUnion("type"));
+export const ImageInput = {
+    bytes: (data, mediaType) => ({ type: "bytes", data, mediaType }),
+    url: (url) => ({ type: "url", url }),
+    file: (id) => ({ type: "file-id", id }),
+    fileUri: (uri, mediaType) => ({ type: "file-uri", uri, mediaType }),
+};
 export class ImageRequest extends Schema.Class("Image.Request")({
     model: ImageModelSchema,
     prompt: Schema.String,
+    images: Schema.optional(Schema.Array(ImageInputSchema)),
     options: Schema.optional(Schema.Record(Schema.String, Schema.Unknown)),
     http: Schema.optional(HttpOptions),
 }) {

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export { ProviderPackage } from "./provider-package";
 export { isContextOverflow, isContextOverflowFailure } from "./provider-error";
 export type { RouteModelInput, RouteRoutedModelInput, Interface as LLMClientShape, Service as LLMClientService, } from "./route/client";
 export * from "./schema";
-export { GeneratedImage, ImageModel, ImageRequest, ImageResponse } from "./image";
+export { GeneratedImage, ImageInput, ImageInputSchema, ImageModel, ImageRequest, ImageResponse } from "./image";
 export type { ImageModelOptions, ImageOptions, ImageRequestFor, ImageRequestInput, ImageRoute } from "./image";
 export { Image } from "./image";
 export { Tool, ToolFailure, toDefinitions } from "./tool";

package/dist/index.js

@@ -5,7 +5,7 @@ export { Provider } from "./provider";
 export { ProviderPackage } from "./provider-package";
 export { isContextOverflow, isContextOverflowFailure } from "./provider-error";
 export * from "./schema";
-export { GeneratedImage, ImageModel, ImageRequest, ImageResponse } from "./image";
+export { GeneratedImage, ImageInput, ImageInputSchema, ImageModel, ImageRequest, ImageResponse } from "./image";
 export { Image } from "./image";
 export { Tool, ToolFailure, toDefinitions } from "./tool";
 export { ToolRuntime } from "./tool-runtime";

package/dist/protocols/google-images.d.ts

@@ -13,9 +13,7 @@ export type GoogleImageOptions = {
 export type GoogleImageBody = Record<string, unknown> & {
     readonly contents: ReadonlyArray<{
         readonly role: "user";
-        readonly parts: ReadonlyArray<{
-            readonly text: string;
-        }>;
+        readonly parts: ReadonlyArray<Record<string, unknown>>;
     }>;
     readonly generationConfig: Record<string, unknown>;
 };

package/dist/protocols/google-images.js

@@ -1,9 +1,10 @@
 import { Effect, Encoding, Schema } from "effect";
 import { Headers, HttpClientRequest } from "effect/unstable/http";
-import { GeneratedImage, ImageModel, ImageResponse } from "../image";
+import { GeneratedImage, ImageModel, ImageResponse, } from "../image";
 import { Auth } from "../route/auth";
 import { InvalidProviderOutputReason, LLMError, Usage, mergeHttpOptions, mergeJsonRecords, } from "../schema";
 import { ProviderShared } from "./shared";
+import { ImageInputs } from "./utils/image-input";
 const ADAPTER = "google-images";
 export const DEFAULT_BASE_URL = "https://generativelanguage.googleapis.com/v1beta";
 const GoogleUsage = Schema.StructWithRest(Schema.Struct({
@@ -57,10 +58,6 @@ const nativeOptions = (options) => {
         thinkingConfig: Object.values(thinkingConfig).some((value) => value !== undefined) ? thinkingConfig : undefined,
     }, native) ?? { responseModalities: ["IMAGE"] });
 };
-const body = (request, overlay) => mergeJsonRecords({
-    contents: [{ role: "user", parts: [{ text: request.prompt }] }],
-    generationConfig: nativeOptions(request.options),
-}, overlay);
 const invalidOutput = (message, providerMetadata) => new LLMError({
     module: ADAPTER,
     method: "generate",
@@ -77,8 +74,13 @@ export const model = (input) => {
     const route = {
         id: ADAPTER,
         generate: Effect.fn("GoogleImages.generate")(function* (request, execute) {
+            const imageParts = yield* Effect.forEach(request.images ?? [], googleImagePart);
             const http = mergeHttpOptions(request.model.http, request.http);
-            const text = ProviderShared.encodeJson(body(request, http?.body));
+            const requestBody = mergeJsonRecords({
+                contents: [{ role: "user", parts: [{ text: request.prompt }, ...imageParts] }],
+                generationConfig: nativeOptions(request.options),
+            }, http?.body);
+            const text = ProviderShared.encodeJson(requestBody);
             const url = applyQuery(`${(input.baseURL ?? DEFAULT_BASE_URL).replace(/\/$/, "")}/models/${request.model.id}:generateContent`, http?.query);
             const headers = yield* Auth.toEffect(input.auth)({
                 request,
@@ -169,6 +171,21 @@ export const model = (input) => {
     };
     return ImageModel.make({ id: input.id, provider: "google", route, http: input.http });
 };
+const googleImagePart = (image) => {
+    if (image.type === "bytes")
+        return Effect.succeed({ inlineData: { mimeType: image.mediaType, data: Encoding.encodeBase64(image.data) } });
+    if (image.type === "file-uri")
+        return Effect.succeed({ fileData: { mimeType: image.mediaType, fileUri: image.uri } });
+    if (image.type === "url")
+        return ImageInputs.decodeDataUrl(image.url, ADAPTER).pipe(Effect.flatMap((decoded) => {
+            if (decoded === undefined)
+                return Effect.fail(ImageInputs.invalid(ADAPTER, "Google generateContent does not fetch public image URLs; use bytes, a data URL, or a Gemini file URI"));
+            return Effect.succeed({
+                inlineData: { mimeType: decoded.mediaType, data: Encoding.encodeBase64(decoded.data) },
+            });
+        }));
+    return Effect.fail(ImageInputs.invalid(ADAPTER, "Google generateContent requires Gemini file URIs rather than provider file IDs"));
+};
 export const GoogleImages = {
     model,
 };

package/dist/protocols/openai-compatible-responses.d.ts

@@ -71,13 +71,13 @@ export declare const route: Route<{
     } | {
         readonly type: "image_generation";
         readonly output_format?: "png" | "jpeg" | "webp" | undefined;
+        readonly size?: string | undefined;
+        readonly quality?: "low" | "medium" | "high" | "auto" | undefined;
+        readonly background?: "auto" | "opaque" | "transparent" | undefined;
         readonly output_compression?: number | undefined;
         readonly action?: "generate" | "auto" | "edit" | undefined;
-        readonly background?: "auto" | "opaque" | "transparent" | undefined;
         readonly input_fidelity?: "low" | "high" | undefined;
         readonly partial_images?: number | undefined;
-        readonly quality?: "low" | "medium" | "high" | "auto" | undefined;
-        readonly size?: string | undefined;
     })[] | undefined;
     readonly temperature?: number | undefined;
     readonly tool_choice?: "required" | "none" | "auto" | import("effect/Schema").Struct.ReadonlySide<{

package/dist/protocols/openai-images.d.ts

@@ -1,10 +1,12 @@
-import { ImageModel } from "../image";
+import { ImageModel, type ImageInput } from "../image";
 import { type Definition as AuthDefinition } from "../route/auth";
 import { type HttpOptions } from "../schema";
 export declare const DEFAULT_BASE_URL = "https://api.openai.com/v1";
 export declare const PATH = "/images/generations";
+export declare const EDIT_PATH = "/images/edits";
 export type OpenAIImageString<Known extends string> = Known | (string & {});
 export type OpenAIImageOptions = {
+    readonly mask?: ImageInput;
     readonly n?: number;
     readonly size?: OpenAIImageString<"auto" | "256x256" | "512x512" | "1024x1024" | "1536x1024" | "1024x1536" | "1792x1024" | "1024x1792">;
     readonly quality?: OpenAIImageString<"auto" | "low" | "medium" | "high" | "standard" | "hd">;

package/dist/protocols/openai-images.js

@@ -1,13 +1,15 @@
 import { Effect, Encoding, Schema } from "effect";
-import { Headers, HttpClientRequest } from "effect/unstable/http";
-import { ImageModel, GeneratedImage, ImageResponse } from "../image";
+import { Headers, HttpClientRequest, HttpClientResponse } from "effect/unstable/http";
+import { ImageModel, GeneratedImage, ImageResponse, } from "../image";
 import { Auth } from "../route/auth";
 import { InvalidProviderOutputReason, LLMError, Usage, mergeHttpOptions, mergeJsonRecords, } from "../schema";
 import { ProviderShared } from "./shared";
+import { ImageInputs } from "./utils/image-input";
 import { OpenAIImage } from "./utils/openai-image";
 const ADAPTER = "openai-images";
 export const DEFAULT_BASE_URL = "https://api.openai.com/v1";
 export const PATH = "/images/generations";
+export const EDIT_PATH = "/images/edits";
 const OpenAIImageResponse = Schema.Struct({
     data: Schema.Array(Schema.Struct({
         b64_json: Schema.optional(Schema.String),
@@ -26,7 +28,7 @@ const OpenAIImageResponse = Schema.Struct({
 const nativeOptions = (options) => {
     if (!options)
         return undefined;
-    const { outputFormat, outputCompression, ...native } = options;
+    const { mask: _, outputFormat, outputCompression, ...native } = options;
     return {
         output_format: outputFormat,
         output_compression: outputCompression,
@@ -49,10 +51,85 @@ export const model = (input) => {
     const route = {
         id: ADAPTER,
         generate: Effect.fn("OpenAIImages.generate")(function* (request, execute) {
+            const mask = request.options?.mask;
+            if (mask !== undefined && (request.images?.length ?? 0) === 0)
+                return yield* ImageInputs.invalid(ADAPTER, "An OpenAI image mask requires at least one input image");
             const http = mergeHttpOptions(request.model.http, request.http);
-            const requestBody = mergeJsonRecords({ model: request.model.id, prompt: request.prompt }, nativeOptions(request.options), http?.body);
+            const sourceImages = request.images ?? [];
+            const multipartImages = yield* Effect.forEach(sourceImages, (image) => {
+                if (image.type === "bytes")
+                    return Effect.succeed({ data: image.data, mediaType: image.mediaType });
+                if (image.type === "url")
+                    return ImageInputs.decodeDataUrl(image.url, ADAPTER);
+                return Effect.succeed(undefined);
+            });
+            const multipartMask = mask === undefined
+                ? undefined
+                : mask.type === "bytes"
+                    ? { data: mask.data, mediaType: mask.mediaType }
+                    : mask.type === "url"
+                        ? yield* ImageInputs.decodeDataUrl(mask.url, ADAPTER)
+                        : undefined;
+            const useMultipart = sourceImages.length > 0 &&
+                multipartImages.every((image) => image !== undefined) &&
+                (mask === undefined || multipartMask !== undefined);
+            const path = sourceImages.length === 0 ? PATH : EDIT_PATH;
+            const url = applyQuery(`${(input.baseURL ?? DEFAULT_BASE_URL).replace(/\/$/, "")}${path}`, http?.query);
+            if (useMultipart) {
+                const form = new FormData();
+                form.append("model", request.model.id);
+                form.append("prompt", request.prompt);
+                Object.entries(mergeJsonRecords(nativeOptions(request.options), http?.body) ?? {}).forEach(([key, value]) => {
+                    if (["model", "prompt", "image", "image[]", "images", "mask"].includes(key))
+                        return;
+                    form.append(key, typeof value === "string" ? value : ProviderShared.encodeJson(value));
+                });
+                multipartImages.forEach((image, index) => {
+                    if (image === undefined)
+                        return;
+                    form.append("image[]", imageBlob(image.data, image.mediaType), `image-${index}`);
+                });
+                if (multipartMask !== undefined)
+                    form.append("mask", imageBlob(multipartMask.data, multipartMask.mediaType), "mask");
+                const headers = yield* Auth.toEffect(input.auth)({
+                    request,
+                    method: "POST",
+                    url,
+                    body: "[multipart/form-data]",
+                    headers: Headers.remove(Headers.fromInput({ ...input.headers, ...http?.headers }), "content-type"),
+                });
+                const response = yield* execute(HttpClientRequest.post(url).pipe(HttpClientRequest.setHeaders(headers), HttpClientRequest.bodyFormData(form)));
+                return yield* parseResponse(response, request.options, http?.body);
+            }
+            const references = sourceImages.map((image) => {
+                if (image.type === "bytes")
+                    return { image_url: ImageInputs.dataUrl(image) };
+                if (image.type === "url")
+                    return { image_url: image.url };
+                if (image.type === "file-id")
+                    return { file_id: image.id };
+                return undefined;
+            });
+            if (references.some((image) => image === undefined))
+                return yield* ImageInputs.invalid(ADAPTER, "OpenAI Images accepts image URLs, data URLs, bytes, and file IDs");
+            const maskReference = mask === undefined
+                ? undefined
+                : mask.type === "bytes"
+                    ? { image_url: ImageInputs.dataUrl(mask) }
+                    : mask.type === "url"
+                        ? { image_url: mask.url }
+                        : mask.type === "file-id"
+                            ? { file_id: mask.id }
+                            : undefined;
+            if (mask !== undefined && maskReference === undefined)
+                return yield* ImageInputs.invalid(ADAPTER, "OpenAI Images accepts masks as URLs, data URLs, bytes, or file IDs");
+            const requestBody = mergeJsonRecords({
+                model: request.model.id,
+                prompt: request.prompt,
+                images: references.length === 0 ? undefined : references,
+                mask: maskReference,
+            }, nativeOptions(request.options), http?.body);
             const text = ProviderShared.encodeJson(requestBody);
-            const url = applyQuery(`${(input.baseURL ?? DEFAULT_BASE_URL).replace(/\/$/, "")}${PATH}`, http?.query);
             const headers = yield* Auth.toEffect(input.auth)({
                 request,
                 method: "POST",
@@ -61,42 +138,51 @@ export const model = (input) => {
                 headers: Headers.fromInput({ ...input.headers, ...http?.headers }),
             });
             const response = yield* execute(HttpClientRequest.post(url).pipe(HttpClientRequest.setHeaders(headers), HttpClientRequest.bodyText(text, "application/json")));
-            const payload = yield* response.json.pipe(Effect.mapError(() => invalidOutput("Failed to read the OpenAI Images response")));
-            const decoded = yield* Schema.decodeUnknownEffect(OpenAIImageResponse)(payload).pipe(Effect.mapError(() => invalidOutput("OpenAI Images returned an invalid response")));
-            const format = decoded.output_format ?? (typeof requestBody.output_format === "string" ? requestBody.output_format : "png");
-            const images = yield* Effect.forEach(decoded.data, (item, index) => {
-                if (item.b64_json)
-                    return Effect.fromResult(Encoding.decodeBase64(item.b64_json)).pipe(Effect.mapError(() => invalidOutput(`OpenAI Images result ${index} contains invalid base64 data`)), Effect.map((data) => new GeneratedImage({
-                        mediaType: `image/${format}`,
-                        data,
-                        providerMetadata: item.revised_prompt === undefined ? undefined : { openai: { revisedPrompt: item.revised_prompt } },
-                    })));
-                if (item.url)
-                    return Effect.succeed(new GeneratedImage({
-                        mediaType: `image/${format}`,
-                        data: item.url,
-                        providerMetadata: item.revised_prompt === undefined ? undefined : { openai: { revisedPrompt: item.revised_prompt } },
-                    }));
-                return Effect.fail(invalidOutput(`OpenAI Images result ${index} has neither image data nor a URL`));
-            });
-            if (images.length === 0)
-                return yield* invalidOutput("OpenAI Images returned no images");
-            return new ImageResponse({
-                images,
-                usage: decoded.usage === undefined
-                    ? undefined
-                    : new Usage({
-                        inputTokens: decoded.usage.input_tokens,
-                        outputTokens: decoded.usage.output_tokens,
-                        totalTokens: decoded.usage.total_tokens,
-                        providerMetadata: { openai: decoded.usage },
-                    }),
-                providerMetadata: { openai: { outputFormat: format } },
-            });
+            return yield* parseResponse(response, request.options, http?.body);
         }),
     };
     return ImageModel.make({ id: input.id, provider: "openai", route, http: input.http });
 };
+const parseResponse = Effect.fn("OpenAIImages.parseResponse")(function* (response, options, overlay) {
+    const payload = yield* response.json.pipe(Effect.mapError(() => invalidOutput("Failed to read the OpenAI Images response")));
+    const decoded = yield* Schema.decodeUnknownEffect(OpenAIImageResponse)(payload).pipe(Effect.mapError(() => invalidOutput("OpenAI Images returned an invalid response")));
+    const requestBody = mergeJsonRecords(nativeOptions(options), overlay);
+    const format = decoded.output_format ?? (typeof requestBody?.output_format === "string" ? requestBody.output_format : "png");
+    const images = yield* Effect.forEach(decoded.data, (item, index) => {
+        if (item.b64_json)
+            return Effect.fromResult(Encoding.decodeBase64(item.b64_json)).pipe(Effect.mapError(() => invalidOutput(`OpenAI Images result ${index} contains invalid base64 data`)), Effect.map((data) => new GeneratedImage({
+                mediaType: `image/${format}`,
+                data,
+                providerMetadata: item.revised_prompt === undefined ? undefined : { openai: { revisedPrompt: item.revised_prompt } },
+            })));
+        if (item.url)
+            return Effect.succeed(new GeneratedImage({
+                mediaType: `image/${format}`,
+                data: item.url,
+                providerMetadata: item.revised_prompt === undefined ? undefined : { openai: { revisedPrompt: item.revised_prompt } },
+            }));
+        return Effect.fail(invalidOutput(`OpenAI Images result ${index} has neither image data nor a URL`));
+    });
+    if (images.length === 0)
+        return yield* invalidOutput("OpenAI Images returned no images");
+    return new ImageResponse({
+        images,
+        usage: decoded.usage === undefined
+            ? undefined
+            : new Usage({
+                inputTokens: decoded.usage.input_tokens,
+                outputTokens: decoded.usage.output_tokens,
+                totalTokens: decoded.usage.total_tokens,
+                providerMetadata: { openai: decoded.usage },
+            }),
+        providerMetadata: { openai: { outputFormat: format } },
+    });
+});
+const imageBlob = (data, mediaType) => {
+    const buffer = new ArrayBuffer(data.byteLength);
+    new Uint8Array(buffer).set(data);
+    return new Blob([buffer], { type: mediaType });
+};
 export const OpenAIImages = {
     model,
 };

package/dist/protocols/openai-responses.d.ts

@@ -165,13 +165,13 @@ export declare const protocol: Protocol<{
     } | {
         readonly type: "image_generation";
         readonly output_format?: "png" | "jpeg" | "webp" | undefined;
+        readonly size?: string | undefined;
+        readonly quality?: "low" | "medium" | "high" | "auto" | undefined;
+        readonly background?: "auto" | "opaque" | "transparent" | undefined;
         readonly output_compression?: number | undefined;
         readonly action?: "generate" | "auto" | "edit" | undefined;
-        readonly background?: "auto" | "opaque" | "transparent" | undefined;
         readonly input_fidelity?: "low" | "high" | undefined;
         readonly partial_images?: number | undefined;
-        readonly quality?: "low" | "medium" | "high" | "auto" | undefined;
-        readonly size?: string | undefined;
     })[] | undefined;
     readonly temperature?: number | undefined;
     readonly tool_choice?: "required" | "none" | "auto" | Schema.Struct.ReadonlySide<{
@@ -317,13 +317,13 @@ export declare const httpTransport: HttpTransport.HttpJsonTransport<{
     } | {
         readonly type: "image_generation";
         readonly output_format?: "png" | "jpeg" | "webp" | undefined;
+        readonly size?: string | undefined;
+        readonly quality?: "low" | "medium" | "high" | "auto" | undefined;
+        readonly background?: "auto" | "opaque" | "transparent" | undefined;
         readonly output_compression?: number | undefined;
         readonly action?: "generate" | "auto" | "edit" | undefined;
-        readonly background?: "auto" | "opaque" | "transparent" | undefined;
         readonly input_fidelity?: "low" | "high" | undefined;
         readonly partial_images?: number | undefined;
-        readonly quality?: "low" | "medium" | "high" | "auto" | undefined;
-        readonly size?: string | undefined;
     })[] | undefined;
     readonly temperature?: number | undefined;
     readonly tool_choice?: "required" | "none" | "auto" | Schema.Struct.ReadonlySide<{
@@ -406,13 +406,13 @@ export declare const route: Route<{
     } | {
         readonly type: "image_generation";
         readonly output_format?: "png" | "jpeg" | "webp" | undefined;
+        readonly size?: string | undefined;
+        readonly quality?: "low" | "medium" | "high" | "auto" | undefined;
+        readonly background?: "auto" | "opaque" | "transparent" | undefined;
         readonly output_compression?: number | undefined;
         readonly action?: "generate" | "auto" | "edit" | undefined;
-        readonly background?: "auto" | "opaque" | "transparent" | undefined;
         readonly input_fidelity?: "low" | "high" | undefined;
         readonly partial_images?: number | undefined;
-        readonly quality?: "low" | "medium" | "high" | "auto" | undefined;
-        readonly size?: string | undefined;
     })[] | undefined;
     readonly temperature?: number | undefined;
     readonly tool_choice?: "required" | "none" | "auto" | Schema.Struct.ReadonlySide<{
@@ -495,13 +495,13 @@ export declare const webSocketTransport: import("../route/transport/websocket").
     } | {
         readonly type: "image_generation";
         readonly output_format?: "png" | "jpeg" | "webp" | undefined;
+        readonly size?: string | undefined;
+        readonly quality?: "low" | "medium" | "high" | "auto" | undefined;
+        readonly background?: "auto" | "opaque" | "transparent" | undefined;
         readonly output_compression?: number | undefined;
         readonly action?: "generate" | "auto" | "edit" | undefined;
-        readonly background?: "auto" | "opaque" | "transparent" | undefined;
         readonly input_fidelity?: "low" | "high" | undefined;
         readonly partial_images?: number | undefined;
-        readonly quality?: "low" | "medium" | "high" | "auto" | undefined;
-        readonly size?: string | undefined;
     })[] | undefined;
     readonly temperature?: number | undefined;
     readonly tool_choice?: "required" | "none" | "auto" | Schema.Struct.ReadonlySide<{
@@ -584,13 +584,13 @@ export declare const webSocketTransport: import("../route/transport/websocket").
     } | {
         readonly type: "image_generation";
         readonly output_format?: "png" | "jpeg" | "webp" | undefined;
+        readonly size?: string | undefined;
+        readonly quality?: "low" | "medium" | "high" | "auto" | undefined;
+        readonly background?: "auto" | "opaque" | "transparent" | undefined;
         readonly output_compression?: number | undefined;
         readonly action?: "generate" | "auto" | "edit" | undefined;
-        readonly background?: "auto" | "opaque" | "transparent" | undefined;
         readonly input_fidelity?: "low" | "high" | undefined;
         readonly partial_images?: number | undefined;
-        readonly quality?: "low" | "medium" | "high" | "auto" | undefined;
-        readonly size?: string | undefined;
     })[] | undefined;
     readonly temperature?: number | undefined;
     readonly tool_choice?: "required" | "none" | "auto" | Schema.Struct.ReadonlySide<{
@@ -673,13 +673,13 @@ export declare const webSocketRoute: Route<{
     } | {
         readonly type: "image_generation";
         readonly output_format?: "png" | "jpeg" | "webp" | undefined;
+        readonly size?: string | undefined;
+        readonly quality?: "low" | "medium" | "high" | "auto" | undefined;
+        readonly background?: "auto" | "opaque" | "transparent" | undefined;
         readonly output_compression?: number | undefined;
         readonly action?: "generate" | "auto" | "edit" | undefined;
-        readonly background?: "auto" | "opaque" | "transparent" | undefined;
         readonly input_fidelity?: "low" | "high" | undefined;
         readonly partial_images?: number | undefined;
-        readonly quality?: "low" | "medium" | "high" | "auto" | undefined;
-        readonly size?: string | undefined;
     })[] | undefined;
     readonly temperature?: number | undefined;
     readonly tool_choice?: "required" | "none" | "auto" | Schema.Struct.ReadonlySide<{

package/dist/protocols/utils/image-input.d.ts

@@ -0,0 +1,21 @@
+import { Effect } from "effect";
+import type { ImageInput } from "../../image";
+import { LLMError } from "../../schema";
+export declare const dataUrl: (input: Extract<ImageInput, {
+    readonly type: "bytes";
+}>) => string;
+export declare const decodeDataUrl: (url: string, module: string) => Effect.Effect<{
+    readonly mediaType: string;
+    readonly data: Uint8Array;
+} | undefined, LLMError>;
+export declare const invalidImageInput: (module: string, message: string) => LLMError;
+export declare const ImageInputs: {
+    readonly dataUrl: (input: Extract<ImageInput, {
+        readonly type: "bytes";
+    }>) => string;
+    readonly decodeDataUrl: (url: string, module: string) => Effect.Effect<{
+        readonly mediaType: string;
+        readonly data: Uint8Array;
+    } | undefined, LLMError>;
+    readonly invalid: (module: string, message: string) => LLMError;
+};

package/dist/protocols/utils/image-input.js

@@ -0,0 +1,22 @@
+import { Effect, Encoding } from "effect";
+import { InvalidRequestReason, LLMError } from "../../schema";
+const invalid = (module, message) => new LLMError({
+    module,
+    method: "generate",
+    reason: new InvalidRequestReason({ message }),
+});
+export const dataUrl = (input) => `data:${input.mediaType};base64,${Encoding.encodeBase64(input.data)}`;
+export const decodeDataUrl = (url, module) => {
+    if (!url.startsWith("data:"))
+        return Effect.succeed(undefined);
+    const match = /^data:([^;,]+);base64,(.*)$/s.exec(url);
+    if (!match)
+        return Effect.fail(invalid(module, "Image data URLs must contain a MIME type and base64 data"));
+    return Effect.fromResult(Encoding.decodeBase64(match[2])).pipe(Effect.mapError(() => invalid(module, "Image data URL contains invalid base64 data")), Effect.map((data) => ({ mediaType: match[1], data })));
+};
+export const invalidImageInput = invalid;
+export const ImageInputs = {
+    dataUrl,
+    decodeDataUrl,
+    invalid: invalidImageInput,
+};

package/dist/protocols/xai-images.d.ts

@@ -3,6 +3,7 @@ import { type Definition as AuthDefinition } from "../route/auth";
 import { type HttpOptions } from "../schema";
 export declare const DEFAULT_BASE_URL = "https://api.x.ai/v1";
 export declare const PATH = "/images/generations";
+export declare const EDIT_PATH = "/images/edits";
 export type XAIImageString<Known extends string> = Known | (string & {});
 export type XAIImageOptions = {
     readonly n?: number;

package/dist/protocols/xai-images.js

@@ -4,9 +4,11 @@ import { GeneratedImage, ImageModel, ImageResponse } from "../image";
 import { Auth } from "../route/auth";
 import { InvalidProviderOutputReason, LLMError, Usage, mergeHttpOptions, mergeJsonRecords, } from "../schema";
 import { ProviderShared, optionalNull } from "./shared";
+import { ImageInputs } from "./utils/image-input";
 const ADAPTER = "xai-images";
 export const DEFAULT_BASE_URL = "https://api.x.ai/v1";
 export const PATH = "/images/generations";
+export const EDIT_PATH = "/images/edits";
 const XAIImageResponse = Schema.Struct({
     data: Schema.Array(Schema.Struct({
         b64_json: optionalNull(Schema.String),
@@ -43,9 +45,25 @@ export const model = (input) => {
         id: ADAPTER,
         generate: Effect.fn("XAIImages.generate")(function* (request, execute) {
             const http = mergeHttpOptions(request.model.http, request.http);
-            const requestBody = mergeJsonRecords({ model: request.model.id, prompt: request.prompt }, nativeOptions(request.options), http?.body);
+            const imageReferences = (request.images ?? []).map((image) => {
+                if (image.type === "bytes")
+                    return { url: ImageInputs.dataUrl(image), type: "image_url" };
+                if (image.type === "url")
+                    return { url: image.url, type: "image_url" };
+                if (image.type === "file-id")
+                    return { file_id: image.id };
+                return undefined;
+            });
+            if (imageReferences.some((image) => image === undefined))
+                return yield* ImageInputs.invalid(ADAPTER, "xAI Images accepts image URLs, data URLs, bytes, and file IDs");
+            const requestBody = mergeJsonRecords({
+                model: request.model.id,
+                prompt: request.prompt,
+                image: imageReferences.length === 1 ? imageReferences[0] : undefined,
+                images: imageReferences.length > 1 ? imageReferences : undefined,
+            }, nativeOptions(request.options), http?.body);
             const text = ProviderShared.encodeJson(requestBody);
-            const url = applyQuery(`${(input.baseURL ?? DEFAULT_BASE_URL).replace(/\/$/, "")}${PATH}`, http?.query);
+            const url = applyQuery(`${(input.baseURL ?? DEFAULT_BASE_URL).replace(/\/$/, "")}${imageReferences.length === 0 ? PATH : EDIT_PATH}`, http?.query);
             const headers = yield* Auth.toEffect(input.auth)({
                 request,
                 method: "POST",

package/dist/protocols/zai-images.js

@@ -4,6 +4,7 @@ import { GeneratedImage, ImageModel, ImageResponse } from "../image";
 import { Auth } from "../route/auth";
 import { InvalidProviderOutputReason, LLMError, mergeHttpOptions, mergeJsonRecords } from "../schema";
 import { ProviderShared } from "./shared";
+import { ImageInputs } from "./utils/image-input";
 const ADAPTER = "zai-images";
 export const DEFAULT_BASE_URL = "https://api.z.ai/api/paas/v4";
 export const PATH = "/images/generations";
@@ -42,6 +43,8 @@ export const model = (input) => {
     const route = {
         id: ADAPTER,
         generate: Effect.fn("ZAIImages.generate")(function* (request, execute) {
+            if ((request.images?.length ?? 0) > 0)
+                return yield* ImageInputs.invalid(ADAPTER, "Z.ai hosted image generation does not support image inputs");
             const http = mergeHttpOptions(request.model.http, request.http);
             const requestBody = mergeJsonRecords({ model: request.model.id, prompt: request.prompt }, nativeOptions(request.options), http?.body);
             const text = ProviderShared.encodeJson(requestBody);

package/dist/providers/azure.d.ts

@@ -150,13 +150,13 @@ export declare const routes: (RouteDef<{
     } | {
         readonly type: "image_generation";
         readonly output_format?: "png" | "jpeg" | "webp" | undefined;
+        readonly size?: string | undefined;
+        readonly quality?: "low" | "medium" | "high" | "auto" | undefined;
+        readonly background?: "auto" | "opaque" | "transparent" | undefined;
         readonly output_compression?: number | undefined;
         readonly action?: "generate" | "auto" | "edit" | undefined;
-        readonly background?: "auto" | "opaque" | "transparent" | undefined;
         readonly input_fidelity?: "low" | "high" | undefined;
         readonly partial_images?: number | undefined;
-        readonly quality?: "low" | "medium" | "high" | "auto" | undefined;
-        readonly size?: string | undefined;
     })[] | undefined;
     readonly temperature?: number | undefined;
     readonly tool_choice?: "required" | "none" | "auto" | import("effect/Schema").Struct.ReadonlySide<{

package/dist/providers/github-copilot.d.ts

@@ -138,13 +138,13 @@ export declare const routes: (import("../route").Route<{
     } | {
         readonly type: "image_generation";
         readonly output_format?: "png" | "jpeg" | "webp" | undefined;
+        readonly size?: string | undefined;
+        readonly quality?: "low" | "medium" | "high" | "auto" | undefined;
+        readonly background?: "auto" | "opaque" | "transparent" | undefined;
         readonly output_compression?: number | undefined;
         readonly action?: "generate" | "auto" | "edit" | undefined;
-        readonly background?: "auto" | "opaque" | "transparent" | undefined;
         readonly input_fidelity?: "low" | "high" | undefined;
         readonly partial_images?: number | undefined;
-        readonly quality?: "low" | "medium" | "high" | "auto" | undefined;
-        readonly size?: string | undefined;
     })[] | undefined;
     readonly temperature?: number | undefined;
     readonly tool_choice?: "required" | "none" | "auto" | import("effect/Schema").Struct.ReadonlySide<{

package/dist/providers/google-vertex-responses.d.ts

@@ -82,13 +82,13 @@ export declare const routes: import("../route").Route<{
     } | {
         readonly type: "image_generation";
         readonly output_format?: "png" | "jpeg" | "webp" | undefined;
+        readonly size?: string | undefined;
+        readonly quality?: "low" | "medium" | "high" | "auto" | undefined;
+        readonly background?: "auto" | "opaque" | "transparent" | undefined;
         readonly output_compression?: number | undefined;
         readonly action?: "generate" | "auto" | "edit" | undefined;
-        readonly background?: "auto" | "opaque" | "transparent" | undefined;
         readonly input_fidelity?: "low" | "high" | undefined;
         readonly partial_images?: number | undefined;
-        readonly quality?: "low" | "medium" | "high" | "auto" | undefined;
-        readonly size?: string | undefined;
     })[] | undefined;
     readonly temperature?: number | undefined;
     readonly tool_choice?: "required" | "none" | "auto" | import("effect/Schema").Struct.ReadonlySide<{

package/dist/providers/openai-compatible-responses.d.ts

@@ -80,13 +80,13 @@ export declare const routes: import("../route").Route<{
     } | {
         readonly type: "image_generation";
         readonly output_format?: "png" | "jpeg" | "webp" | undefined;
+        readonly size?: string | undefined;
+        readonly quality?: "low" | "medium" | "high" | "auto" | undefined;
+        readonly background?: "auto" | "opaque" | "transparent" | undefined;
         readonly output_compression?: number | undefined;
         readonly action?: "generate" | "auto" | "edit" | undefined;
-        readonly background?: "auto" | "opaque" | "transparent" | undefined;
         readonly input_fidelity?: "low" | "high" | undefined;
         readonly partial_images?: number | undefined;
-        readonly quality?: "low" | "medium" | "high" | "auto" | undefined;
-        readonly size?: string | undefined;
     })[] | undefined;
     readonly temperature?: number | undefined;
     readonly tool_choice?: "required" | "none" | "auto" | import("effect/Schema").Struct.ReadonlySide<{

package/dist/providers/openai.d.ts

@@ -136,13 +136,13 @@ export declare const routes: (Route<{
     } | {
         readonly type: "image_generation";
         readonly output_format?: "png" | "jpeg" | "webp" | undefined;
+        readonly size?: string | undefined;
+        readonly quality?: "low" | "medium" | "high" | "auto" | undefined;
+        readonly background?: "auto" | "opaque" | "transparent" | undefined;
         readonly output_compression?: number | undefined;
         readonly action?: "generate" | "auto" | "edit" | undefined;
-        readonly background?: "auto" | "opaque" | "transparent" | undefined;
         readonly input_fidelity?: "low" | "high" | undefined;
         readonly partial_images?: number | undefined;
-        readonly quality?: "low" | "medium" | "high" | "auto" | undefined;
-        readonly size?: string | undefined;
     })[] | undefined;
     readonly temperature?: number | undefined;
     readonly tool_choice?: "required" | "none" | "auto" | import("effect/Schema").Struct.ReadonlySide<{
@@ -224,13 +224,13 @@ export declare const routes: (Route<{
     } | {
         readonly type: "image_generation";
         readonly output_format?: "png" | "jpeg" | "webp" | undefined;
+        readonly size?: string | undefined;
+        readonly quality?: "low" | "medium" | "high" | "auto" | undefined;
+        readonly background?: "auto" | "opaque" | "transparent" | undefined;
         readonly output_compression?: number | undefined;
         readonly action?: "generate" | "auto" | "edit" | undefined;
-        readonly background?: "auto" | "opaque" | "transparent" | undefined;
         readonly input_fidelity?: "low" | "high" | undefined;
         readonly partial_images?: number | undefined;
-        readonly quality?: "low" | "medium" | "high" | "auto" | undefined;
-        readonly size?: string | undefined;
     })[] | undefined;
     readonly temperature?: number | undefined;
     readonly tool_choice?: "required" | "none" | "auto" | import("effect/Schema").Struct.ReadonlySide<{

package/dist/providers/xai.d.ts

@@ -135,13 +135,13 @@ export declare const routes: (import("../route").Route<{
     } | {
         readonly type: "image_generation";
         readonly output_format?: "png" | "jpeg" | "webp" | undefined;
+        readonly size?: string | undefined;
+        readonly quality?: "low" | "medium" | "high" | "auto" | undefined;
+        readonly background?: "auto" | "opaque" | "transparent" | undefined;
         readonly output_compression?: number | undefined;
         readonly action?: "generate" | "auto" | "edit" | undefined;
-        readonly background?: "auto" | "opaque" | "transparent" | undefined;
         readonly input_fidelity?: "low" | "high" | undefined;
         readonly partial_images?: number | undefined;
-        readonly quality?: "low" | "medium" | "high" | "auto" | undefined;
-        readonly size?: string | undefined;
     })[] | undefined;
     readonly temperature?: number | undefined;
     readonly tool_choice?: "required" | "none" | "auto" | import("effect/Schema").Struct.ReadonlySide<{

package/package.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
-  "version": "0.0.0-next-15910",
+  "version": "0.0.0-next-15911",
   "name": "@opencode-ai/ai",
   "type": "module",
   "license": "MIT",
@@ -26,7 +26,7 @@
   "devDependencies": {
     "@clack/prompts": "1.0.0-alpha.1",
     "@effect/platform-node": "4.0.0-beta.98",
-    "@opencode-ai/http-recorder": "0.0.0-next-15910",
+    "@opencode-ai/http-recorder": "0.0.0-next-15911",
     "@tsconfig/bun": "1.0.9",
     "@types/bun": "1.3.13",
     "@typescript/native-preview": "7.0.0-dev.20251207.1",
@@ -35,7 +35,7 @@
   "dependencies": {
     "@smithy/eventstream-codec": "4.2.14",
     "@smithy/util-utf8": "4.2.2",
-    "@opencode-ai/schema": "0.0.0-next-15910",
+    "@opencode-ai/schema": "0.0.0-next-15911",
     "aws4fetch": "1.0.20",
     "effect": "4.0.0-beta.98",
     "google-auth-library": "10.5.0"