@warlock.js/ai-openai 4.4.0 → 4.6.0

package/CHANGELOG.md

@@ -4,21 +4,38 @@ All notable changes to `@warlock.js/ai-openai` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 4.6.0
+
+### Added
+
+- **`openai.image({ name })`** — image generation for the `gpt-image-*` (token-metered) and `dall-e-*` (per-image) families, for use with `ai.image()`. A non-image model id is rejected at construction.
+- **PDF + audio input.** `pdf` and `audio` content parts now map to OpenAI `file` (base64 `file_data`) and `input_audio` (`wav` / `mp3`) parts — opt in with `model({ pdf: true })` / `{ audio: true }`. A remote-URL pdf/audio source raises a typed `InvalidRequestError` up front.
+- **`openai.speech({ name })`** — text-to-speech for the `tts-1` / `tts-1-hd` / `gpt-4o-mini-tts` families (`audio.speech.create`), for use with `ai.speech()`.
+- **`openai.transcribe({ name })`** — speech-to-text for the `whisper-1` / `gpt-4o-transcribe` families (`audio.transcriptions.create`), for use with `ai.transcribe()`. `whisper-1` defaults to `verbose_json` (duration + segments); a non-TTS/STT model id is rejected at construction.
+
+### Fixed
+
+- **Non-text content parts are no longer coerced to `image_url`.** The message mapper now branches per modality (image → `image_url`, pdf → `file`, audio → `input_audio`) instead of forcing every attachment through the image path.
+
+## 4.5.0 - 2026-07-01
+
+### Fixed
+
+- **All upstream `ClientOptions` now reach the OpenAI client.** The SDK constructor peels off the framework-only `provider` / `pricing` keys and forwards the rest (`timeout`, `maxRetries`, `defaultHeaders`, custom `fetch`, `organization`, `project`, …) verbatim, instead of dropping everything but `apiKey` / `baseURL`.
+
 ## 4.4.0 - 2026-06-21
 
 ### Fixed
 
-- **Strict structured-output compatibility check is now recursive.** `json_schema` (strict) mode is used only when every object in the schema lists all of its properties in `required` — OpenAI strict has no optional fields, so a schema that omits one anywhere in the tree would `400`. Such schemas now degrade to loose `json_object` instead of failing the call; client-side validation still enforces the full shape.
+- **Strict structured-output compatibility check is now recursive.** A schema that omits a `required` property anywhere in the tree degrades to loose `json_object` instead of `400`-ing; client-side validation still enforces the full shape.
 
 ## 4.3.0 - 2026-06-21
 
 ### Added
 
-- Cost-truth wiring (additive, non-breaking):
-  - `Usage.reasoningTokens` now populated from `completion_tokens_details.reasoning_tokens` on both `complete()` and the streaming `done` event (o-series / gpt-5 hidden reasoning channel). Emitted only when > 0.
-  - `ModelCallOptions.reasoning.effort` mapped to the provider-native `reasoning_effort` request param. Forwarded only for reasoning-capable models; `reasoning.maxTokens` has no Chat Completions equivalent and is ignored.
-  - `ModelCapabilities.reasoning` inferred from the model name (`o1*` / `o3*` / `o4*` / `gpt-5*`), overridable via `.model({ name, reasoning })`. New `known-reasoning-models.ts` prefix helper.
-  - `ModelCapabilities.promptCaching` advertised as always `true` (OpenAI caches automatically and reports hits via `Usage.cachedTokens`). `ModelCallOptions.cacheControl` write breakpoints are a graceful no-op.
+- `Usage.reasoningTokens` is populated from `completion_tokens_details.reasoning_tokens` (o-series / gpt-5 hidden reasoning channel), emitted only when `> 0`.
+- `ModelCallOptions.reasoning.effort` maps to the native `reasoning_effort` param for reasoning-capable models; `reasoning.maxTokens` has no Chat Completions equivalent.
+- `ModelCapabilities.reasoning` is inferred from the model name (overridable via `.model(...)`); `promptCaching` is always `true` (OpenAI caches automatically), and `cacheControl` write breakpoints are a no-op.
 
 ## 4.1.15
 

package/cjs/index.cjs

@@ -115,15 +115,62 @@ function stringifyContent(content) {
 	if (typeof content === "string") return content;
 	return content.filter((part) => part.type === "text").map((part) => part.text).join("");
 }
+/**
+* Map a resolved `ContentPart` to an OpenAI chat content part — one
+* branch per modality, each to its real wire shape:
+*
+* - `text` → `{ type: "text" }`.
+* - `image` → `{ type: "image_url" }` (remote URL, or a `data:` URL for
+*   inlined base64 bytes).
+* - `pdf` → `{ type: "file", file: { file_data } }` (OpenAI document
+*   input; base64 only — there is no remote-URL file source).
+* - `audio` → `{ type: "input_audio", input_audio: { data, format } }`
+*   (base64 only; `wav` / `mp3` are the only formats OpenAI accepts).
+*
+* PDF and audio reach this point ONLY when the model declared the
+* matching capability (`openai.model({ name, pdf: true })` /
+* `{ audio: true }`) — the agent's modality gate throws upfront
+* otherwise, so capability and behavior stay in lockstep. A remote-URL
+* pdf/audio source raises a typed `InvalidRequestError` here rather
+* than a downstream provider fault.
+*/
 function toOpenAIContentPart(part) {
 	if (part.type === "text") return {
 		type: "text",
 		text: part.text
 	};
-	return {
+	if (part.type === "image") return {
 		type: "image_url",
 		image_url: { url: "url" in part.source ? part.source.url : `data:${part.source.mediaType};base64,${part.source.base64}` }
 	};
+	if (part.type === "pdf") {
+		if ("url" in part.source) throw new _warlock_js_ai.InvalidRequestError("OpenAI chat completions cannot fetch a remote-URL PDF; supply base64 document bytes instead.");
+		return {
+			type: "file",
+			file: {
+				filename: "document.pdf",
+				file_data: `data:${part.source.mediaType};base64,${part.source.base64}`
+			}
+		};
+	}
+	if ("url" in part.source) throw new _warlock_js_ai.InvalidRequestError("OpenAI chat completions cannot fetch remote-URL audio; supply base64 audio bytes instead.");
+	return {
+		type: "input_audio",
+		input_audio: {
+			data: part.source.base64,
+			format: toOpenAIAudioFormat(part.source.mediaType)
+		}
+	};
+}
+/**
+* Narrow a neutral audio media type to the two formats OpenAI's
+* `input_audio` accepts (`wav` / `mp3`). An unsupported type raises a
+* typed `InvalidRequestError` up front rather than a provider 400.
+*/
+function toOpenAIAudioFormat(mediaType) {
+	if (mediaType === "audio/wav" || mediaType === "audio/x-wav" || mediaType === "audio/wave") return "wav";
+	if (mediaType === "audio/mp3" || mediaType === "audio/mpeg" || mediaType === "audio/mpga") return "mp3";
+	throw new _warlock_js_ai.InvalidRequestError(`OpenAI input_audio supports only "wav" and "mp3"; got "${mediaType}".`);
 }
 
 //#endregion
@@ -307,7 +354,7 @@ function parseRetryAfter(headers) {
 
 //#endregion
 //#region ../@warlock.js/ai-openai/src/embedder.ts
-const LOG_MODULE$1 = "ai.openai";
+const LOG_MODULE$4 = "ai.openai";
 /**
 * OpenAI-backed implementation of `EmbedderContract`.
 *
@@ -365,7 +412,7 @@ var OpenAIEmbedder = class {
 	* plus a camelCase usage object for the caller to shape.
 	*/
 	async request(input) {
-		this.logger.debug(LOG_MODULE$1, "embedder.request", "embeddings.create", {
+		this.logger.debug(LOG_MODULE$4, "embedder.request", "embeddings.create", {
 			model: this.name,
 			batch: Array.isArray(input),
 			count: Array.isArray(input) ? input.length : 1
@@ -379,13 +426,13 @@ var OpenAIEmbedder = class {
 			});
 		} catch (thrown) {
 			const wrapped = wrapOpenAIError(thrown);
-			this.logger.error(LOG_MODULE$1, "embedder.error", wrapped.message, {
+			this.logger.error(LOG_MODULE$4, "embedder.error", wrapped.message, {
 				code: wrapped.code,
 				context: wrapped.context
 			});
 			throw wrapped;
 		}
-		this.logger.debug(LOG_MODULE$1, "embedder.response", "embeddings.create returned", {
+		this.logger.debug(LOG_MODULE$4, "embedder.response", "embeddings.create returned", {
 			dimensions: response.data[0]?.embedding.length,
 			usage: {
 				promptTokens: response.usage.prompt_tokens,
@@ -404,6 +451,154 @@ var OpenAIEmbedder = class {
 	}
 };
 
+//#endregion
+//#region ../@warlock.js/ai-openai/src/known-image-models.ts
+/**
+* Model-id prefixes OpenAI exposes through the **Images** API
+* (`client.images.generate`). The two live families:
+*
+* - `gpt-image-*` — token-metered, always returns base64 bytes (no
+*   `response_format` knob), supports `output_format` + `background`.
+* - `dall-e-*` — per-image-metered, returns a URL or base64 via
+*   `response_format`.
+*
+* Used by {@link isOpenAIImageModel} for the construction-time guard so
+* `openai.image({ name: "gpt-4o" })` fails fast with a curated error
+* instead of a downstream 400 — mirroring the embedder/vision guards.
+*/
+const OPENAI_IMAGE_MODEL_PREFIXES = ["gpt-image", "dall-e"];
+/**
+* True when `name` is a recognized OpenAI image-generation model. A
+* prefix match (not an exact list) so dated snapshots
+* (`gpt-image-1-mini`, `dall-e-3`) are covered without a maintenance
+* burden every time OpenAI ships a point release.
+*
+* @example
+* isOpenAIImageModel("gpt-image-1"); // true
+* isOpenAIImageModel("dall-e-3");    // true
+* isOpenAIImageModel("gpt-4o");      // false
+*/
+function isOpenAIImageModel(name) {
+	return OPENAI_IMAGE_MODEL_PREFIXES.some((prefix) => name.startsWith(prefix));
+}
+
+//#endregion
+//#region ../@warlock.js/ai-openai/src/image.ts
+const LOG_MODULE$3 = "ai.openai";
+/** Map a neutral output container to its IANA media type. */
+function mediaTypeFor(format) {
+	switch (format) {
+		case "jpeg":
+		case "jpg": return "image/jpeg";
+		case "webp": return "image/webp";
+		default: return "image/png";
+	}
+}
+/**
+* OpenAI-backed implementation of `ImageModelContract`.
+*
+* **Role.** Bridges the vendor-neutral `ai.image()` verb to OpenAI's
+* **Images** API for the two image families OpenAI ships: the
+* token-metered `gpt-image-*` models (always return base64 bytes) and
+* the per-image-metered `dall-e-*` models (URL or base64). Like
+* `OpenAIEmbedder`, it's a standalone primitive — no relationship to
+* chat completions, tools, or the agent loop.
+*
+* **Capability guard.** The constructor rejects a non-image model id
+* up front (`gpt-4o` → typed `InvalidRequestError`) so the mistake
+* surfaces at wiring time, not as a downstream provider 400 — the
+* "fail fast at construction" rule shared with the embedder/vision
+* guards.
+*
+* **Error handling.** Raw OpenAI SDK errors are wrapped into the typed
+* `@warlock.js/ai` `AIError` hierarchy via `wrapOpenAIError`, so a
+* caller catches `ProviderRateLimitError` / `ContentFilterError` /
+* `ProviderAuthError` rather than OpenAI's own classes. `ai.image()`
+* turns those throws into `result.error`.
+*
+* @example
+* const model = new OpenAIImageModel(client, { name: "gpt-image-1" }, "openai");
+* const { images, usage } = await model.generate("a teal ceramic mug, studio light");
+*/
+var OpenAIImageModel = class {
+	constructor(client, config, provider = "openai") {
+		this.logger = _warlock_js_logger.log;
+		if (!isOpenAIImageModel(config.name)) throw new _warlock_js_ai.InvalidRequestError(`"${config.name}" is not a known OpenAI image-generation model. Use a \`gpt-image-*\` or \`dall-e-*\` model with openai.image({ name }).`);
+		this.client = client;
+		this.name = config.name;
+		this.provider = provider;
+		this.pricing = config.pricing;
+	}
+	async generate(prompt, options) {
+		const isGptImage = this.name.startsWith("gpt-image");
+		const responseFormat = options?.responseFormat ?? (isGptImage ? void 0 : "b64_json");
+		const body = {
+			model: this.name,
+			prompt
+		};
+		if (options?.count !== void 0) body.n = options.count;
+		if (options?.size !== void 0) body.size = options.size;
+		if (options?.quality !== void 0) body.quality = options.quality;
+		if (!isGptImage && responseFormat) body.response_format = responseFormat;
+		if (isGptImage && options?.format !== void 0) body.output_format = options.format;
+		if (options?.background !== void 0) body.background = options.background;
+		this.logger.debug(LOG_MODULE$3, "image.request", "images.generate", {
+			model: this.name,
+			count: options?.count ?? 1
+		});
+		let response;
+		try {
+			response = await this.client.images.generate(body, options?.signal ? { signal: options.signal } : void 0);
+		} catch (thrown) {
+			const wrapped = wrapOpenAIError(thrown);
+			this.logger.error(LOG_MODULE$3, "image.error", wrapped.message, {
+				code: wrapped.code,
+				context: wrapped.context
+			});
+			throw wrapped;
+		}
+		const images = (response.data ?? []).map((image) => this.toGeneratedImage(image, options?.format));
+		const usage = response.usage ? {
+			input: response.usage.input_tokens,
+			output: response.usage.output_tokens,
+			total: response.usage.total_tokens
+		} : {
+			input: 0,
+			output: 0,
+			total: 0
+		};
+		this.logger.debug(LOG_MODULE$3, "image.response", "images.generate succeeded", {
+			images: images.length,
+			usage
+		});
+		return {
+			images,
+			usage
+		};
+	}
+	/**
+	* Normalize one OpenAI `Image` into the neutral discriminated shape.
+	* Base64 wins when present (gpt-image, and DALL·E in b64 mode);
+	* otherwise a hosted URL. A response carrying neither is a provider
+	* contract violation — surface it as a typed `ProviderError` rather
+	* than emitting a half-formed part.
+	*/
+	toGeneratedImage(image, format) {
+		if (image.b64_json) return {
+			type: "base64",
+			base64: image.b64_json,
+			mediaType: mediaTypeFor(format),
+			...image.revised_prompt ? { revisedPrompt: image.revised_prompt } : {}
+		};
+		if (image.url) return {
+			type: "url",
+			url: image.url,
+			...image.revised_prompt ? { revisedPrompt: image.revised_prompt } : {}
+		};
+		throw new _warlock_js_ai.ProviderError("OpenAI image response contained neither base64 bytes nor a URL.");
+	}
+};
+
 //#endregion
 //#region ../@warlock.js/ai-openai/src/known-reasoning-models.ts
 /**
@@ -486,7 +681,7 @@ function inferVisionCapability(modelName) {
 
 //#endregion
 //#region ../@warlock.js/ai-openai/src/model.ts
-const LOG_MODULE = "ai.openai";
+const LOG_MODULE$2 = "ai.openai";
 /**
 * Map an explicit `responseFormat` override to the default
 * `structuredOutput` capability. Loose wire modes (`"json_object"`,
@@ -549,7 +744,9 @@ var OpenAIModel = class {
 			structuredOutput: config.structuredOutput ?? inferStructuredOutput(config.responseFormat),
 			vision: config.vision ?? inferVisionCapability(config.name),
 			reasoning: config.reasoning ?? inferReasoningCapability(config.name),
-			promptCaching: true
+			promptCaching: true,
+			pdf: config.pdf ?? false,
+			audio: config.audio ?? false
 		};
 	}
 	/**
@@ -559,7 +756,7 @@ var OpenAIModel = class {
 	* instance's `ModelConfig` defaults for this call only.
 	*/
 	async complete(messages, options) {
-		this.logger.debug(LOG_MODULE, "request", "Starting call to chat.completions", {
+		this.logger.debug(LOG_MODULE$2, "request", "Starting call to chat.completions", {
 			model: this.name,
 			messageCount: messages.length,
 			streaming: false,
@@ -578,7 +775,7 @@ var OpenAIModel = class {
 			}, options?.signal ? { signal: options.signal } : void 0);
 		} catch (thrown) {
 			const wrapped = wrapOpenAIError(thrown);
-			this.logger.error(LOG_MODULE, "error", wrapped.message, {
+			this.logger.error(LOG_MODULE$2, "error", wrapped.message, {
 				code: wrapped.code,
 				context: wrapped.context
 			});
@@ -587,7 +784,7 @@ var OpenAIModel = class {
 		const choice = response.choices[0];
 		const finishReason = mapFinishReason(choice.finish_reason);
 		const usage = this.extractUsage(response.usage);
-		this.logger.debug(LOG_MODULE, "response", "call to chat.completions succeeded", {
+		this.logger.debug(LOG_MODULE$2, "response", "call to chat.completions succeeded", {
 			finishReason,
 			usage
 		});
@@ -605,7 +802,7 @@ var OpenAIModel = class {
 	* Callers consume it with `for await`.
 	*/
 	async *stream(messages, options) {
-		this.logger.debug(LOG_MODULE, "request", "Starting streaming call to chat.completions", {
+		this.logger.debug(LOG_MODULE$2, "request", "Starting streaming call to chat.completions", {
 			model: this.name,
 			messageCount: messages.length,
 			streaming: true,
@@ -626,7 +823,7 @@ var OpenAIModel = class {
 			}, options?.signal ? { signal: options.signal } : void 0);
 		} catch (thrown) {
 			const wrapped = wrapOpenAIError(thrown);
-			this.logger.error(LOG_MODULE, "error", wrapped.message, {
+			this.logger.error(LOG_MODULE$2, "error", wrapped.message, {
 				code: wrapped.code,
 				context: wrapped.context
 			});
@@ -681,14 +878,14 @@ var OpenAIModel = class {
 			}
 		} catch (thrown) {
 			const wrapped = wrapOpenAIError(thrown);
-			this.logger.error(LOG_MODULE, "error", wrapped.message, {
+			this.logger.error(LOG_MODULE$2, "error", wrapped.message, {
 				code: wrapped.code,
 				context: wrapped.context
 			});
 			throw wrapped;
 		}
 		const finishReason = mapFinishReason(rawFinishReason);
-		this.logger.debug(LOG_MODULE, "response", "Streaming call to chat.completions succeeded", {
+		this.logger.debug(LOG_MODULE$2, "response", "Streaming call to chat.completions succeeded", {
 			finishReason,
 			usage
 		});
@@ -851,6 +1048,179 @@ var OpenAIModel = class {
 	}
 };
 
+//#endregion
+//#region ../@warlock.js/ai-openai/src/speech.ts
+const LOG_MODULE$1 = "ai.openai";
+/** Model-id prefixes OpenAI exposes through the **Speech** (TTS) API. */
+const SPEECH_MODEL_PREFIXES = [
+	"tts-1",
+	"gpt-4o-mini-tts",
+	"gpt-audio"
+];
+/** True when `name` is a recognized OpenAI text-to-speech model. */
+function isOpenAISpeechModel(name) {
+	return SPEECH_MODEL_PREFIXES.some((prefix) => name.startsWith(prefix));
+}
+/** Map a neutral output container hint to its IANA audio media type. */
+function audioMediaType(format) {
+	switch (format) {
+		case "opus": return "audio/opus";
+		case "aac": return "audio/aac";
+		case "flac": return "audio/flac";
+		case "wav": return "audio/wav";
+		case "pcm": return "audio/pcm";
+		default: return "audio/mpeg";
+	}
+}
+/**
+* OpenAI-backed implementation of `SpeechModelContract` (text-to-speech)
+* via `audio.speech.create`. Standalone primitive — no relation to chat
+* completions or the agent loop. Consumed by the `ai.speech()` verb.
+*
+* **Capability guard.** The constructor rejects a non-TTS model id up
+* front (`tts-1` / `gpt-4o-mini-tts` only) so the mistake surfaces at
+* wiring time, mirroring the embedder / image guards.
+*
+* @example
+* const tts = new OpenAISpeechModel(client, { name: "tts-1", voice: "alloy" }, "openai");
+* const { audio } = await tts.generate("Welcome aboard.");
+*/
+var OpenAISpeechModel = class {
+	constructor(client, config, provider = "openai") {
+		this.logger = _warlock_js_logger.log;
+		if (!isOpenAISpeechModel(config.name)) throw new _warlock_js_ai.InvalidRequestError(`"${config.name}" is not a known OpenAI text-to-speech model. Use a \`tts-1\` / \`tts-1-hd\` / \`gpt-4o-mini-tts\` model with openai.speech({ name }).`);
+		this.client = client;
+		this.name = config.name;
+		this.provider = provider;
+		this.pricing = config.pricing;
+		this.defaultVoice = config.voice;
+	}
+	async generate(text, options) {
+		const format = options?.format ?? "mp3";
+		this.logger.debug(LOG_MODULE$1, "speech.request", "audio.speech.create", {
+			model: this.name,
+			characters: text.length
+		});
+		let response;
+		try {
+			response = await this.client.audio.speech.create({
+				model: this.name,
+				input: text,
+				voice: options?.voice ?? this.defaultVoice ?? "alloy",
+				response_format: format,
+				...options?.speed !== void 0 ? { speed: options.speed } : {},
+				...options?.instructions !== void 0 ? { instructions: options.instructions } : {}
+			}, options?.signal ? { signal: options.signal } : void 0);
+		} catch (thrown) {
+			const wrapped = wrapOpenAIError(thrown);
+			this.logger.error(LOG_MODULE$1, "speech.error", wrapped.message, {
+				code: wrapped.code,
+				context: wrapped.context
+			});
+			throw wrapped;
+		}
+		return {
+			audio: {
+				type: "base64",
+				base64: Buffer.from(await response.arrayBuffer()).toString("base64"),
+				mediaType: audioMediaType(format)
+			},
+			usage: {
+				input: 0,
+				output: 0,
+				total: 0
+			},
+			characters: text.length
+		};
+	}
+};
+
+//#endregion
+//#region ../@warlock.js/ai-openai/src/transcription.ts
+const LOG_MODULE = "ai.openai";
+/** Model-id prefixes OpenAI exposes through the **Transcription** (STT) API. */
+const TRANSCRIPTION_MODEL_PREFIXES = [
+	"whisper",
+	"gpt-4o-transcribe",
+	"gpt-4o-mini-transcribe"
+];
+/** True when `name` is a recognized OpenAI speech-to-text model. */
+function isOpenAITranscriptionModel(name) {
+	return TRANSCRIPTION_MODEL_PREFIXES.some((prefix) => name.startsWith(prefix));
+}
+/**
+* OpenAI-backed implementation of `TranscriptionModelContract`
+* (speech-to-text) via `audio.transcriptions.create`. Consumed by the
+* `ai.transcribe()` verb.
+*
+* **Response format.** Defaults to `verbose_json` for `whisper-1` (so
+* the run gets a `duration` + timestamped `segments`) and `json` for
+* the token-metered `gpt-4o-transcribe` family. Base64 audio is wrapped
+* in an uploadable via the SDK's `toFile`.
+*
+* @example
+* const stt = new OpenAITranscriptionModel(client, { name: "whisper-1" }, "openai");
+* const { text } = await stt.transcribe({ base64, mediaType: "audio/mpeg" });
+*/
+var OpenAITranscriptionModel = class {
+	constructor(client, config, provider = "openai") {
+		this.logger = _warlock_js_logger.log;
+		if (!isOpenAITranscriptionModel(config.name)) throw new _warlock_js_ai.InvalidRequestError(`"${config.name}" is not a known OpenAI transcription model. Use a \`whisper-1\` / \`gpt-4o-transcribe\` / \`gpt-4o-mini-transcribe\` model with openai.transcribe({ name }).`);
+		this.client = client;
+		this.name = config.name;
+		this.provider = provider;
+		this.pricing = config.pricing;
+	}
+	async transcribe(audio, options) {
+		const isWhisper = this.name.startsWith("whisper");
+		const format = options?.format ?? (isWhisper ? "verbose_json" : "json");
+		const file = await (0, openai.toFile)(Buffer.from(audio.base64, "base64"), audio.filename ?? "audio", { type: audio.mediaType });
+		this.logger.debug(LOG_MODULE, "transcription.request", "audio.transcriptions.create", {
+			model: this.name,
+			format
+		});
+		let raw;
+		try {
+			raw = await this.client.audio.transcriptions.create({
+				model: this.name,
+				file,
+				response_format: format,
+				...options?.language ? { language: options.language } : {},
+				...options?.prompt ? { prompt: options.prompt } : {}
+			}, options?.signal ? { signal: options.signal } : void 0);
+		} catch (thrown) {
+			const wrapped = wrapOpenAIError(thrown);
+			this.logger.error(LOG_MODULE, "transcription.error", wrapped.message, {
+				code: wrapped.code,
+				context: wrapped.context
+			});
+			throw wrapped;
+		}
+		const response = raw;
+		const segments = response.segments?.map((segment) => ({
+			text: segment.text,
+			...segment.start !== void 0 ? { start: segment.start } : {},
+			...segment.end !== void 0 ? { end: segment.end } : {}
+		}));
+		const durationSeconds = response.duration ?? (response.usage?.type === "duration" ? response.usage.seconds : void 0);
+		const usage = response.usage?.type === "tokens" ? {
+			input: response.usage.input_tokens ?? 0,
+			output: response.usage.output_tokens ?? 0,
+			total: response.usage.total_tokens ?? 0
+		} : {
+			input: 0,
+			output: 0,
+			total: 0
+		};
+		return {
+			text: response.text,
+			...segments && segments.length > 0 ? { segments } : {},
+			...durationSeconds !== void 0 ? { durationSeconds } : {},
+			usage
+		};
+	}
+};
+
 //#endregion
 //#region ../@warlock.js/ai-openai/src/sdk.ts
 /**
@@ -889,12 +1259,10 @@ var OpenAIModel = class {
 */
 var OpenAISDK = class {
 	constructor(config) {
-		this.client = new openai.default({
-			apiKey: config.apiKey,
-			baseURL: config.baseURL
-		});
-		this.provider = config.provider ?? "openai";
-		this.pricing = config.pricing;
+		const { provider, pricing, ...clientOptions } = config;
+		this.client = new openai.default(clientOptions);
+		this.provider = provider ?? "openai";
+		this.pricing = pricing;
 	}
 	/**
 	* Build an `OpenAIModel` bound to this SDK's client. Each call returns
@@ -939,9 +1307,66 @@ var OpenAISDK = class {
 	embedder(config) {
 		return new OpenAIEmbedder(this.client, config);
 	}
+	/**
+	* Build an `OpenAIImageModel` bound to this SDK's client for use with
+	* `ai.image({ model, prompt })`. Accepts the `gpt-image-*` (token-metered)
+	* and `dall-e-*` (per-image-metered) families; a non-image model id
+	* is rejected at construction.
+	*
+	* Pricing resolution mirrors `model()`: per-model `config.pricing`
+	* wins, otherwise the SDK-level registry entry keyed by `config.name`,
+	* otherwise `undefined` (no cost computed). A token-priced
+	* `gpt-image-1` entry can live in the same SDK registry as the chat
+	* models.
+	*
+	* @example
+	* const model = openai.image({ name: "gpt-image-1" });
+	* const { data } = await ai.image({ model, prompt: "a red bicycle" });
+	*/
+	image(config) {
+		const resolvedPricing = config.pricing ?? this.pricing?.[config.name];
+		const resolvedConfig = resolvedPricing === config.pricing ? config : {
+			...config,
+			pricing: resolvedPricing
+		};
+		return new OpenAIImageModel(this.client, resolvedConfig, this.provider);
+	}
+	/**
+	* Build an `OpenAISpeechModel` (text-to-speech) bound to this SDK's
+	* client, for use with `ai.speech({ model, text })`. Accepts the
+	* `tts-1` / `gpt-4o-mini-tts` families; a non-TTS model id is rejected
+	* at construction.
+	*
+	* @example
+	* const tts = openai.speech({ name: "tts-1", voice: "alloy" });
+	* const { data } = await ai.speech({ model: tts, text: "Hello" });
+	*/
+	speech(config) {
+		return new OpenAISpeechModel(this.client, config, this.provider);
+	}
+	/**
+	* Build an `OpenAITranscriptionModel` (speech-to-text) bound to this
+	* SDK's client, for use with `ai.transcribe({ model, audio })`.
+	* Accepts the `whisper-1` / `gpt-4o-transcribe` families; a non-STT
+	* model id is rejected at construction.
+	*
+	* @example
+	* const stt = openai.transcribe({ name: "whisper-1" });
+	* const { data } = await ai.transcribe({ model: stt, audio });
+	*/
+	transcribe(config) {
+		return new OpenAITranscriptionModel(this.client, config, this.provider);
+	}
 };
 
 //#endregion
+exports.OPENAI_IMAGE_MODEL_PREFIXES = OPENAI_IMAGE_MODEL_PREFIXES;
 exports.OpenAIEmbedder = OpenAIEmbedder;
+exports.OpenAIImageModel = OpenAIImageModel;
 exports.OpenAISDK = OpenAISDK;
+exports.OpenAISpeechModel = OpenAISpeechModel;
+exports.OpenAITranscriptionModel = OpenAITranscriptionModel;
+exports.isOpenAIImageModel = isOpenAIImageModel;
+exports.isOpenAISpeechModel = isOpenAISpeechModel;
+exports.isOpenAITranscriptionModel = isOpenAITranscriptionModel;
 //# sourceMappingURL=index.cjs.map