@oh-my-pi/pi-ai 18.2.7 → 18.2.8

package/src/providers/images-server.ts

@@ -0,0 +1,159 @@
+import { type } from "@oh-my-pi/omptype";
+import * as AIError from "../error";
+import type { ImageGenerationRequest, ImageGenerationResult } from "../images/types";
+
+const imageJsonRequestSchema = type({
+	model: "string > 0",
+	prompt: "string > 0",
+	"n?": "unknown",
+	"size?": "unknown",
+	"image_size?": "unknown",
+	"aspect_ratio?": "unknown",
+	"response_format?": "unknown",
+	"stream?": "unknown",
+	"input_references?": "unknown",
+	"images?": "unknown",
+	"image?": "unknown",
+});
+
+export type ImageRequestKind = "generations" | "edits";
+
+export interface ImagesParsedRequest {
+	modelId: string;
+	request: ImageGenerationRequest;
+}
+
+export interface ImagesResponseBody {
+	created: number;
+	data: Array<{ b64_json: string; revised_prompt?: string }>;
+	usage: { prompt_tokens: number; completion_tokens: number; total_tokens: number; cost: number };
+}
+
+function validation(message: string): never {
+	throw new AIError.ValidationError(`images: ${message}`);
+}
+
+function optionalString(value: unknown, field: string): string | undefined {
+	if (value === undefined || value === null) return undefined;
+	if (typeof value !== "string" || value.length === 0) validation(`${field} must be a non-empty string`);
+	return value;
+}
+
+function optionalCount(value: unknown): number | undefined {
+	if (value === undefined || value === null) return undefined;
+	if (typeof value !== "number" || !Number.isInteger(value) || value < 1) validation("n must be a positive integer");
+	return value;
+}
+
+function decodeInputReference(value: unknown): { data: string; mimeType: string } {
+	let raw: unknown = value;
+	if (value !== null && typeof value === "object") {
+		raw = "url" in value ? value.url : undefined;
+		const imageUrl = "image_url" in value ? value.image_url : undefined;
+		if (raw === undefined && imageUrl !== null && typeof imageUrl === "object" && "url" in imageUrl) {
+			raw = imageUrl.url;
+		}
+	}
+	if (typeof raw !== "string" || raw.length === 0) validation("input image must be base64 or a data URL");
+	const match = raw.match(/^data:([^;]+);base64,(.+)$/s);
+	if (match) return { data: match[2] ?? "", mimeType: match[1] ?? "image/png" };
+	if (/^[A-Za-z0-9+/]+={0,2}$/.test(raw)) return { data: raw, mimeType: "image/png" };
+	validation("input image URLs are not supported; send a data URL or base64 bytes");
+}
+
+function parseJson(body: unknown, kind: ImageRequestKind): ImagesParsedRequest {
+	const parsed = imageJsonRequestSchema(body);
+	if (parsed instanceof type.errors) validation(parsed.summary);
+	if (parsed.stream === true) validation("streaming image responses are not supported");
+	if (parsed.response_format !== undefined && parsed.response_format !== "b64_json") {
+		validation('response_format must be "b64_json"; URL responses are not supported');
+	}
+	const input = parsed.input_references ?? parsed.images ?? parsed.image;
+	const values = input === undefined ? [] : Array.isArray(input) ? input : [input];
+	if (kind === "edits" && values.length === 0) validation("image edit requires at least one input image");
+	const aspectRatio = optionalString(parsed.aspect_ratio, "aspect_ratio");
+	const imageSize = optionalString(
+		parsed.image_size ?? parsed.size,
+		parsed.image_size === undefined ? "size" : "image_size",
+	);
+	const count = optionalCount(parsed.n);
+	return {
+		modelId: parsed.model,
+		request: {
+			prompt: parsed.prompt,
+			...(values.length > 0 ? { inputImages: values.map(decodeInputReference) } : {}),
+			...(aspectRatio ? { aspectRatio } : {}),
+			...(imageSize ? { imageSize } : {}),
+			...(count ? { count } : {}),
+		},
+	};
+}
+
+async function parseMultipart(form: FormData): Promise<ImagesParsedRequest> {
+	const model = form.get("model");
+	const prompt = form.get("prompt");
+	if (typeof model !== "string" || model.length === 0) validation("model must be a non-empty string");
+	if (typeof prompt !== "string" || prompt.length === 0) validation("prompt must be a non-empty string");
+	const responseFormat = form.get("response_format");
+	if (responseFormat !== null && responseFormat !== "b64_json") {
+		validation('response_format must be "b64_json"; URL responses are not supported');
+	}
+	const stream = form.get("stream");
+	if (stream === "true") validation("streaming image responses are not supported");
+	const entries = [...form.getAll("image"), ...form.getAll("image[]")];
+	if (entries.length === 0) validation("image edit requires at least one image file");
+	const inputImages: Array<{ data: string; mimeType: string }> = [];
+	for (const entry of entries) {
+		if (typeof entry === "string") validation("image must be a file part");
+		const bytes = new Uint8Array(await entry.arrayBuffer());
+		inputImages.push({ data: bytes.toBase64(), mimeType: entry.type || "image/png" });
+	}
+	const nValue = form.get("n");
+	let count: number | undefined;
+	if (nValue !== null) {
+		if (typeof nValue !== "string" || !/^\d+$/.test(nValue)) validation("n must be a positive integer");
+		count = optionalCount(Number(nValue));
+	}
+	const size = form.get("size");
+	if (size !== null && typeof size !== "string") validation("size must be a string");
+	return {
+		modelId: model,
+		request: {
+			prompt,
+			inputImages,
+			...(size ? { imageSize: size } : {}),
+			...(count ? { count } : {}),
+		},
+	};
+}
+
+export async function parseRequest(body: unknown | FormData, kind: ImageRequestKind): Promise<ImagesParsedRequest> {
+	if (body instanceof FormData) {
+		if (kind !== "edits") validation("multipart requests are supported only for image edits");
+		return parseMultipart(body);
+	}
+	return parseJson(body, kind);
+}
+
+export function encodeResponse(result: ImageGenerationResult, _requestedModelId: string): ImagesResponseBody {
+	return {
+		created: Math.floor(Date.now() / 1000),
+		data: result.images.map(image => ({ b64_json: image.data })),
+		usage: {
+			prompt_tokens: result.usage.input,
+			completion_tokens: result.usage.output,
+			total_tokens: result.usage.totalTokens,
+			cost: result.usage.cost.total,
+		},
+	};
+}
+
+export function formatError(status: number, errorType: string, message: string): Response {
+	return new Response(JSON.stringify({ error: { code: status, type: errorType, message } }), {
+		status,
+		headers: {
+			"Content-Type": "application/json; charset=utf-8",
+			"Cache-Control": "no-store",
+		},
+	});
+}

package/src/providers/rerank-server.ts

@@ -0,0 +1,166 @@
+import { type } from "@oh-my-pi/omptype";
+import * as AIError from "../error";
+import type { RerankRequest, RerankResult } from "../rerank/types";
+
+export const MAX_RERANK_BODY_BYTES = 8 * 1024 * 1024;
+
+const rerankRequestSchema = type({
+	model: "string > 0",
+	query: "string",
+	documents: "unknown[]",
+	"top_n?": "unknown",
+	"return_documents?": "unknown",
+});
+
+export interface RerankObjectDocument {
+	text: string;
+}
+
+export type RerankWireDocument = string | RerankObjectDocument;
+
+export interface RerankParsedRequest {
+	modelId: string;
+	request: RerankRequest;
+	originalDocuments: RerankWireDocument[];
+}
+
+export class RerankWireError extends AIError.ValidationError {
+	readonly status: number;
+
+	constructor(status: number, message: string, options?: { cause?: unknown }) {
+		super(message, options);
+		this.name = "RerankWireError";
+		this.status = status;
+	}
+}
+
+function validation(message: string): never {
+	throw new RerankWireError(400, `rerank: ${message}`);
+}
+
+function parseTopN(value: unknown): number | undefined {
+	if (value === undefined || value === null) return undefined;
+	if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
+		validation("top_n must be a positive integer");
+	}
+	return value;
+}
+
+function parseReturnDocuments(value: unknown): boolean | undefined {
+	if (value === undefined || value === null) return undefined;
+	if (typeof value !== "boolean") validation("return_documents must be a boolean");
+	return value;
+}
+
+function parseDocument(value: unknown, index: number): RerankWireDocument {
+	if (typeof value === "string") return value;
+	if (value === null || typeof value !== "object" || !("text" in value) || typeof value.text !== "string") {
+		validation(`documents[${index}] must be a string or an object with a text string`);
+	}
+	return { text: value.text };
+}
+
+async function readBody(req: Request): Promise<Uint8Array> {
+	const contentLength = req.headers.get("content-length");
+	if (contentLength !== null) {
+		const declared = Number(contentLength);
+		if (Number.isFinite(declared) && declared > MAX_RERANK_BODY_BYTES) {
+			throw new RerankWireError(413, "Request payload exceeds the 8 MiB limit");
+		}
+	}
+	const reader = req.body?.getReader();
+	if (!reader) return new Uint8Array();
+	const chunks: Uint8Array[] = [];
+	let total = 0;
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		total += value.byteLength;
+		if (total > MAX_RERANK_BODY_BYTES) {
+			await reader.cancel();
+			throw new RerankWireError(413, "Request payload exceeds the 8 MiB limit");
+		}
+		chunks.push(value);
+	}
+	if (chunks.length === 1) return chunks[0]!;
+	const bytes = new Uint8Array(total);
+	let offset = 0;
+	for (const chunk of chunks) {
+		bytes.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return bytes;
+}
+
+/** Parse an OpenRouter-compatible JSON rerank request. */
+export async function parseRequest(req: Request): Promise<RerankParsedRequest> {
+	const contentType = req.headers.get("content-type")?.toLowerCase() ?? "";
+	if (!contentType.startsWith("application/json")) {
+		throw new RerankWireError(400, "Content-Type must be application/json");
+	}
+	const bytes = await readBody(req);
+	let body: unknown;
+	try {
+		body = JSON.parse(new TextDecoder().decode(bytes));
+	} catch (error) {
+		throw new RerankWireError(400, "Invalid JSON body", { cause: error });
+	}
+	const parsed = rerankRequestSchema(body);
+	if (parsed instanceof type.errors) validation(parsed.summary);
+	if (parsed.documents.length === 0) validation("documents must contain at least one document");
+	const originalDocuments = parsed.documents.map(parseDocument);
+	const topN = parseTopN(parsed.top_n);
+	const returnDocuments = parseReturnDocuments(parsed.return_documents);
+	return {
+		modelId: parsed.model,
+		request: {
+			query: parsed.query,
+			documents: originalDocuments.map(document => (typeof document === "string" ? document : document.text)),
+			...(topN !== undefined && { topN }),
+			...(returnDocuments !== undefined && { returnDocuments }),
+		},
+		originalDocuments,
+	};
+}
+
+export interface RerankResponseBody {
+	model: string;
+	results: Array<{
+		index: number;
+		relevance_score: number;
+		document?: RerankObjectDocument;
+	}>;
+	usage: { total_tokens: number; cost: number };
+}
+
+/** Encode a canonical result as the OpenRouter rerank response shape. */
+export function encodeResponse(
+	result: RerankResult,
+	requestedModelId: string,
+	originalDocuments: readonly RerankWireDocument[],
+	returnDocuments: boolean,
+): RerankResponseBody {
+	return {
+		model: requestedModelId,
+		results: result.results.map(item => {
+			const original = originalDocuments[item.index];
+			const document =
+				typeof original === "string"
+					? { text: original }
+					: (original ?? (item.document ? { text: item.document } : undefined));
+			return {
+				index: item.index,
+				relevance_score: item.relevanceScore,
+				...(returnDocuments && document !== undefined && { document }),
+			};
+		}),
+		usage: { total_tokens: result.usage.totalTokens, cost: result.usage.cost.total },
+	};
+}
+
+export function formatError(status: number, errorType: string, message: string): Response {
+	return new Response(JSON.stringify({ error: { code: status, type: errorType, message } }), {
+		status,
+		headers: { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store" },
+	});
+}

package/src/providers/speech-server.ts

@@ -0,0 +1,53 @@
+import { type } from "@oh-my-pi/omptype";
+import * as AIError from "../error";
+import type { SpeechRequest, SpeechResult } from "../speech/types";
+
+const speechRequestSchema = type({
+	model: "string > 0",
+	input: "string > 0",
+	"voice?": "string > 0",
+	"response_format?": "'mp3' | 'wav' | 'pcm' | 'opus' | 'aac' | 'flac'",
+	"speed?": "number",
+	"instructions?": "string",
+});
+
+export interface SpeechParsedRequest {
+	modelId: string;
+	request: SpeechRequest;
+}
+
+export function parseRequest(body: unknown, _headers?: Headers): SpeechParsedRequest {
+	const parsed = speechRequestSchema(body);
+	if (parsed instanceof type.errors) throw new AIError.ValidationError(`speech: ${parsed.summary}`);
+	return {
+		modelId: parsed.model,
+		request: {
+			text: parsed.input,
+			format: parsed.response_format ?? "mp3",
+			...(parsed.voice !== undefined ? { voice: parsed.voice } : {}),
+			...(parsed.speed !== undefined ? { speed: parsed.speed } : {}),
+			...(parsed.instructions !== undefined ? { instructions: parsed.instructions } : {}),
+		},
+	};
+}
+
+export function encodeResponse(result: SpeechResult, _requestedModelId: string): Response {
+	return new Response(result.audio, {
+		status: 200,
+		headers: {
+			"Content-Type": result.mimeType,
+			"Cache-Control": "no-store",
+			"X-Content-Type-Options": "nosniff",
+		},
+	});
+}
+
+export function formatError(status: number, errorType: string, message: string): Response {
+	return new Response(JSON.stringify({ error: { code: status, type: errorType, message } }), {
+		status,
+		headers: {
+			"Content-Type": "application/json; charset=utf-8",
+			"Cache-Control": "no-store",
+		},
+	});
+}

package/src/providers/systemone-server.ts

@@ -0,0 +1,73 @@
+/**
+ * Server side of TypeSafe's System One wire format (`POST /v1/systemone`),
+ * served by the auth-gateway so TypeSafe SDKs and omp's own `TypeSafeJudge`
+ * can point `TYPESAFE_BASE_URL` at the gateway and never hold the real key.
+ *
+ * Requests are validated only as far as routing needs — the `model` id and
+ * the shape of the `questions` map — and otherwise forwarded verbatim, so
+ * structured `instructions`/`criteria` and forward-compatible fields reach
+ * the upstream untouched. Validation failures answer `422` like TypeSafe.
+ */
+import { type } from "@oh-my-pi/omptype";
+import * as AIError from "../error";
+import type { JudgmentRequest, JudgmentResult } from "../judgment/types";
+
+/**
+ * TypeSafe accepts `instructions` and `criteria` as strings or structured
+ * JSON (https://docs.typesafe.ai/api); only `type` decides how an answer is
+ * read back, so that is all the gateway pins down.
+ */
+const systemOneRequestSchema = type({
+	model: "string > 0",
+	state: "string | object",
+	questions: type({ "[string]": { type: "'noul' | 'choice' | 'score'", instructions: "string | object" } }),
+});
+
+export interface SystemOneParsedRequest {
+	modelId: string;
+	request: JudgmentRequest;
+}
+
+/** `POST /v1/systemone` response body; `cost` (USD) appears only when the route billed one. */
+export interface SystemOneResponseBody {
+	model: string;
+	answers: JudgmentResult["answers"];
+	usage: { input_tokens: number; output_tokens: number; cost?: number };
+}
+
+/**
+ * Validate the routing-relevant parts of a System One request body.
+ *
+ * @throws {AIError.ValidationError} naming the offending field when `model`,
+ * `state`, or `questions` is missing or malformed.
+ */
+export function parseRequest(body: unknown): SystemOneParsedRequest {
+	const parsed = systemOneRequestSchema(body);
+	if (parsed instanceof type.errors) throw new AIError.ValidationError(`systemone: ${parsed.summary}`);
+	// `req.json()` output is JSON by construction, and the typed `Questions`
+	// contract models string instructions only; the judge forwards the request
+	// verbatim and reads back nothing but each question's `type`.
+	const request = { state: parsed.state, questions: parsed.questions } as JudgmentRequest;
+	return { modelId: parsed.model, request };
+}
+
+/** Re-encode a judgment result in TypeSafe's response shape. */
+export function encodeResponse(result: JudgmentResult): SystemOneResponseBody {
+	const usage: SystemOneResponseBody["usage"] = {
+		input_tokens: result.usage.input,
+		output_tokens: result.usage.output,
+	};
+	if (result.usage.cost.total > 0) usage.cost = result.usage.cost.total;
+	return { model: result.model, answers: result.answers, usage };
+}
+
+/** TypeSafe answers errors with a status code and a JSON body; the envelope mirrors the other gateway routes. */
+export function formatError(status: number, type: string, message: string): Response {
+	return new Response(JSON.stringify({ error: { type, message } }), {
+		status,
+		headers: {
+			"Content-Type": "application/json; charset=utf-8",
+			"Cache-Control": "no-store",
+		},
+	});
+}

package/src/providers/transcriptions-server.ts

@@ -0,0 +1,243 @@
+import { type } from "@oh-my-pi/omptype";
+import * as AIError from "../error";
+import type {
+	TranscriptionRequest,
+	TranscriptionResponseFormat,
+	TranscriptionResult,
+	TranscriptionTimestampGranularity,
+} from "../transcription/types";
+
+export const MAX_TRANSCRIPTION_BODY_BYTES = 25 * 1024 * 1024;
+
+const jsonRequestSchema = type({
+	model: "string > 0",
+	input_audio: { data: "string > 0", format: "string > 0" },
+	"language?": "string",
+	"prompt?": "string",
+	"temperature?": "number",
+	"response_format?": "string",
+	"timestamp_granularities?": "string[]",
+});
+
+const MIME_TYPES: Readonly<Record<string, string>> = {
+	wav: "audio/wav",
+	wave: "audio/wav",
+	mp3: "audio/mpeg",
+	mpeg: "audio/mpeg",
+	flac: "audio/flac",
+	m4a: "audio/mp4",
+	mp4: "audio/mp4",
+	ogg: "audio/ogg",
+	opus: "audio/ogg",
+	webm: "audio/webm",
+	aac: "audio/aac",
+};
+
+export class TranscriptionWireError extends AIError.ValidationError {
+	readonly status: number;
+
+	constructor(status: number, message: string, options?: { cause?: unknown }) {
+		super(message, options);
+		this.name = "TranscriptionWireError";
+		this.status = status;
+	}
+}
+
+export interface TranscriptionParsedRequest {
+	modelId: string;
+	request: TranscriptionRequest;
+}
+
+function responseFormat(value: string | undefined): TranscriptionResponseFormat {
+	const resolved = value ?? "json";
+	if (resolved !== "json" && resolved !== "verbose_json") {
+		throw new TranscriptionWireError(400, `Unsupported response_format: ${resolved}`);
+	}
+	return resolved;
+}
+
+function timestampGranularities(values: readonly string[]): TranscriptionTimestampGranularity[] | undefined {
+	if (values.length === 0) return undefined;
+	const granularities: TranscriptionTimestampGranularity[] = [];
+	for (const value of values) {
+		if (value !== "word" && value !== "segment") {
+			throw new TranscriptionWireError(400, `Unsupported timestamp granularity: ${value}`);
+		}
+		if (!granularities.includes(value)) granularities.push(value);
+	}
+	return granularities;
+}
+
+function mimeTypeFor(format: string): string {
+	return MIME_TYPES[format.trim().toLowerCase().replace(/^\./, "")] ?? "application/octet-stream";
+}
+
+function mimeTypeForFile(file: File): string {
+	const partType = file.type.trim();
+	if (partType && partType !== "application/octet-stream") return partType;
+	const dot = file.name.lastIndexOf(".");
+	return dot >= 0 ? mimeTypeFor(file.name.slice(dot + 1)) : "application/octet-stream";
+}
+
+function stringField(form: { get(name: string): unknown }, name: string): string | undefined {
+	const value = form.get(name);
+	if (value === null) return undefined;
+	if (typeof value !== "string") throw new TranscriptionWireError(400, `${name} must be a string`);
+	return value;
+}
+
+function parseTemperature(value: string | undefined): number | undefined {
+	if (value === undefined) return undefined;
+	const parsed = Number(value);
+	if (!Number.isFinite(parsed)) throw new TranscriptionWireError(400, "temperature must be a finite number");
+	return parsed;
+}
+
+async function readBody(req: Request): Promise<Uint8Array> {
+	const contentLength = req.headers.get("content-length");
+	if (contentLength !== null) {
+		const declared = Number(contentLength);
+		if (Number.isFinite(declared) && declared > MAX_TRANSCRIPTION_BODY_BYTES) {
+			throw new TranscriptionWireError(413, "Request payload exceeds the 25 MB limit");
+		}
+	}
+	const reader = req.body?.getReader();
+	if (!reader) return new Uint8Array();
+	const chunks: Uint8Array[] = [];
+	let total = 0;
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		total += value.byteLength;
+		if (total > MAX_TRANSCRIPTION_BODY_BYTES) {
+			await reader.cancel();
+			throw new TranscriptionWireError(413, "Request payload exceeds the 25 MB limit");
+		}
+		chunks.push(value);
+	}
+	if (chunks.length === 1) return chunks[0]!;
+	const bytes = new Uint8Array(total);
+	let offset = 0;
+	for (const chunk of chunks) {
+		bytes.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return bytes;
+}
+
+async function parseMultipart(bytes: Uint8Array, contentType: string): Promise<TranscriptionParsedRequest> {
+	const form = await new Response(bytes, { headers: { "Content-Type": contentType } }).formData().catch(error => {
+		throw new TranscriptionWireError(400, "Invalid multipart/form-data body", { cause: error });
+	});
+	const file = form.get("file");
+	if (!(file instanceof File)) throw new TranscriptionWireError(400, "file must be an audio upload");
+	const modelId = stringField(form, "model")?.trim();
+	if (!modelId) throw new TranscriptionWireError(400, "model must be a non-empty string");
+	const responseFormatValue = responseFormat(stringField(form, "response_format"));
+	const granularities = timestampGranularities(
+		form
+			.getAll("timestamp_granularities[]")
+			.concat(form.getAll("timestamp_granularities"))
+			.map(value => {
+				if (typeof value !== "string") {
+					throw new TranscriptionWireError(400, "timestamp_granularities[] must contain strings");
+				}
+				return value;
+			}),
+	);
+	return {
+		modelId,
+		request: {
+			audio: new Uint8Array(await file.arrayBuffer()),
+			mimeType: mimeTypeForFile(file),
+			fileName: file.name || undefined,
+			language: stringField(form, "language"),
+			prompt: stringField(form, "prompt"),
+			temperature: parseTemperature(stringField(form, "temperature")),
+			responseFormat: responseFormatValue,
+			timestampGranularities: granularities,
+		},
+	};
+}
+
+function decodeBase64(data: string): Uint8Array {
+	if (!/^[A-Za-z0-9+/]*={0,2}$/.test(data) || data.length % 4 === 1) {
+		throw new TranscriptionWireError(400, "input_audio.data must be valid base64");
+	}
+	try {
+		return Uint8Array.fromBase64(data);
+	} catch (error) {
+		throw new TranscriptionWireError(400, "input_audio.data must be valid base64", { cause: error });
+	}
+}
+
+function parseJson(bytes: Uint8Array): TranscriptionParsedRequest {
+	let body: unknown;
+	try {
+		body = JSON.parse(new TextDecoder().decode(bytes));
+	} catch (error) {
+		throw new TranscriptionWireError(400, "Invalid JSON body", { cause: error });
+	}
+	const parsed = jsonRequestSchema(body);
+	if (parsed instanceof type.errors) throw new TranscriptionWireError(400, `transcriptions: ${parsed.summary}`);
+	const audio = decodeBase64(parsed.input_audio.data);
+	if (audio.byteLength === 0) throw new TranscriptionWireError(400, "input_audio.data must not be empty");
+	const format = parsed.input_audio.format.trim().toLowerCase().replace(/^\./, "");
+	if (!format) throw new TranscriptionWireError(400, "input_audio.format must not be empty");
+	return {
+		modelId: parsed.model,
+		request: {
+			audio,
+			mimeType: mimeTypeFor(format),
+			fileName: `audio.${format}`,
+			language: parsed.language,
+			prompt: parsed.prompt,
+			temperature: parsed.temperature,
+			responseFormat: responseFormat(parsed.response_format),
+			timestampGranularities: timestampGranularities(parsed.timestamp_granularities ?? []),
+		},
+	};
+}
+
+/** Parse either OpenAI multipart uploads or OpenRouter base64 JSON requests. */
+export async function parseRequest(req: Request): Promise<TranscriptionParsedRequest> {
+	const contentType = req.headers.get("content-type")?.trim() ?? "";
+	const bytes = await readBody(req);
+	if (contentType.toLowerCase().startsWith("multipart/form-data")) return parseMultipart(bytes, contentType);
+	if (contentType.toLowerCase().startsWith("application/json")) return parseJson(bytes);
+	throw new TranscriptionWireError(400, "Content-Type must be multipart/form-data or application/json");
+}
+
+export interface TranscriptionResponseBody {
+	text: string;
+	language?: string;
+	duration?: number;
+	segments?: TranscriptionResult["segments"];
+	words?: TranscriptionResult["words"];
+	usage: { input_tokens: number; output_tokens: number; total_tokens: number; cost: number; seconds?: number };
+}
+
+/** Encode a canonical result as the shared OpenAI/OpenRouter transcription response. */
+export function encodeResponse(result: TranscriptionResult): TranscriptionResponseBody {
+	return {
+		text: result.text,
+		...(result.language !== undefined && { language: result.language }),
+		...(result.duration !== undefined && { duration: result.duration }),
+		...(result.segments !== undefined && { segments: result.segments }),
+		...(result.words !== undefined && { words: result.words }),
+		usage: {
+			input_tokens: result.usage.input,
+			output_tokens: result.usage.output,
+			total_tokens: result.usage.totalTokens,
+			cost: result.usage.cost.total,
+			...(result.seconds !== undefined && { seconds: result.seconds }),
+		},
+	};
+}
+
+export function formatError(status: number, errorType: string, message: string): Response {
+	return new Response(JSON.stringify({ error: { code: status, type: errorType, message } }), {
+		status,
+		headers: { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store" },
+	});
+}