@mevdragon/vidfarm-devcli 0.2.7 → 0.2.9

package/dist/src/services/providers.js

@@ -8,6 +8,13 @@ export class ProviderKeyUnavailableError extends Error {
 }
 export class ProviderAuthError extends Error {
 }
+export class ProviderLeaseTimeoutError extends Error {
+    retryAfterSeconds;
+    constructor(message, retryAfterSeconds = 5) {
+        super(message);
+        this.retryAfterSeconds = retryAfterSeconds;
+    }
+}
 export class ProviderRateLimitError extends Error {
     retryAfterSeconds;
     constructor(message, retryAfterSeconds = 60) {
@@ -15,6 +22,22 @@ export class ProviderRateLimitError extends Error {
         this.retryAfterSeconds = retryAfterSeconds;
     }
 }
+const SUPPORTED_TTS_MODELS = {
+    openrouter: new Set(["google/gemini-3.1-flash-tts-preview"]),
+    gemini: new Set(["gemini-3.1-flash-tts-preview", "gemini-2.5-flash-preview-tts"]),
+    openai: new Set(["gpt-4o-mini-tts-2025-12-15"])
+};
+const SUPPORTED_STT_MODELS = {
+    openrouter: new Set(["openai/gpt-4o-mini-transcribe"]),
+    gemini: new Set(["gemini-3.1-flash-lite-preview", "gemini-2.5-flash-lite"]),
+    openai: new Set(["gpt-4o-mini-transcribe-2025-12-15"])
+};
+const PROVIDER_KEY_VALIDATION_MODELS = {
+    openai: "gpt-4.1-mini",
+    gemini: "gemini-3.1-flash-lite-preview",
+    openrouter: "google/gemini-3.1-flash-lite-preview",
+    perplexity: "sonar"
+};
 function readStoredProviderSecret(value) {
     try {
         return decryptString(value, config.ENCRYPTION_SECRET);
@@ -23,30 +46,143 @@ function readStoredProviderSecret(value) {
         return value;
     }
 }
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function zeroUsageCost(result) {
+    return {
+        ...result,
+        usage: {
+            ...result.usage,
+            costUsd: 0
+        }
+    };
+}
+const DEFAULT_PROVIDER_LEASE_PRIORITY = 100;
+const CHAT_PROVIDER_LEASE_PRIORITY = 0;
+const DEFAULT_PROVIDER_LEASE_TIMEOUT_MS = 120_000;
+const CHAT_PROVIDER_LEASE_TIMEOUT_MS = 45_000;
+const PROVIDER_LEASE_POLL_MS = 250;
+const DEFAULT_PROVIDER_LEASE_SECONDS = 90;
+const CHAT_PROVIDER_LEASE_SECONDS = 300;
 export class ProviderService {
+    handleLeasedProviderError(input) {
+        if (input.error instanceof ProviderRateLimitError) {
+            database.recordProviderKeyUsage({
+                id: createId("usage"),
+                keyId: input.lease.keyId,
+                jobId: input.jobId,
+                provider: input.provider,
+                model: input.model,
+                eventType: "rate_limit",
+                metadata: {
+                    ...(input.metadata ?? {}),
+                    retryAfterSeconds: input.error.retryAfterSeconds
+                }
+            });
+            database.setProviderKeyCooldown(input.lease.keyId, addSeconds(new Date(), input.error.retryAfterSeconds));
+        }
+        else if (input.error instanceof ProviderAuthError) {
+            database.recordProviderKeyUsage({
+                id: createId("usage"),
+                keyId: input.lease.keyId,
+                jobId: input.jobId,
+                provider: input.provider,
+                model: input.model,
+                eventType: "auth_error",
+                metadata: input.metadata ?? {}
+            });
+            database.setProviderKeyCooldown(input.lease.keyId, null, "invalid", "auth_error");
+        }
+        throw input.error;
+    }
+    listAvailableProviders(customerId) {
+        const now = Date.now();
+        const providers = database.listProviderKeysWithSecrets(customerId)
+            .map((entry) => ({
+            provider: String(entry.provider),
+            status: String(entry.status),
+            cooldownUntil: entry.cooldown_until ? String(entry.cooldown_until) : null,
+            secret: readStoredProviderSecret(String(entry.secret))
+        }))
+            .filter((entry) => entry.status === "active")
+            .filter((entry) => !entry.cooldownUntil || Date.parse(entry.cooldownUntil) <= now)
+            .filter((entry) => entry.secret.trim().length > 0)
+            .map((entry) => entry.provider);
+        return [...new Set(providers)];
+    }
+    async validateProviderKey(input) {
+        const model = PROVIDER_KEY_VALIDATION_MODELS[input.provider];
+        if (!model) {
+            throw new Error(`Provider ${input.provider} does not support validation.`);
+        }
+        if (config.mockProviders) {
+            return { provider: input.provider, model, mock: true };
+        }
+        try {
+            await this.callProvider({
+                provider: input.provider,
+                model,
+                prompt: "Reply with OK.",
+                temperature: 0,
+                apiKey: input.secret
+            });
+            return { provider: input.provider, model, mock: false };
+        }
+        catch (error) {
+            throw new Error(toProviderValidationMessage(input.provider, error));
+        }
+    }
     async leaseCustomerKey(input) {
         const leaseToken = createId("lease");
-        const row = database.acquireProviderKeyLease({
-            customerId: input.customerId,
-            provider: input.provider,
-            workerId: input.workerId,
-            jobId: input.jobId,
-            leaseToken,
-            expiresAt: addSeconds(new Date(), 90)
-        });
-        if (!row) {
-            throw new ProviderKeyUnavailableError(`No eligible ${input.provider} key available.`);
+        const waiterId = createId("wait");
+        const priority = input.priority ?? DEFAULT_PROVIDER_LEASE_PRIORITY;
+        const waitTimeoutMs = input.waitTimeoutMs ?? DEFAULT_PROVIDER_LEASE_TIMEOUT_MS;
+        const leaseDurationSeconds = input.leaseDurationSeconds ?? DEFAULT_PROVIDER_LEASE_SECONDS;
+        const deadline = Date.now() + waitTimeoutMs;
+        try {
+            while (Date.now() < deadline) {
+                const row = database.acquireProviderKeyLease({
+                    customerId: input.customerId,
+                    provider: input.provider,
+                    waiterId,
+                    workerId: input.workerId,
+                    jobId: input.jobId,
+                    priority,
+                    leaseToken,
+                    expiresAt: addSeconds(new Date(), leaseDurationSeconds),
+                    waiterExpiresAt: addSeconds(new Date(), 10)
+                });
+                if (row) {
+                    return {
+                        keyId: row.keyId,
+                        leaseToken,
+                        provider: input.provider,
+                        secret: readStoredProviderSecret(row.encryptedSecret)
+                    };
+                }
+                await sleep(PROVIDER_LEASE_POLL_MS);
+            }
         }
-        return {
-            keyId: row.keyId,
-            leaseToken,
-            provider: input.provider,
-            secret: readStoredProviderSecret(row.encryptedSecret)
-        };
+        finally {
+            database.deleteProviderKeyWaiter(waiterId);
+        }
+        throw new ProviderLeaseTimeoutError(`No eligible ${input.provider} key became available in time.`);
     }
     async releaseLease(lease) {
         database.releaseProviderKeyLease({ keyId: lease.keyId, leaseToken: lease.leaseToken });
     }
+    async leaseEditorChatKey(input) {
+        return this.leaseCustomerKey({
+            customerId: input.customerId,
+            provider: input.provider,
+            jobId: input.chatId,
+            workerId: `editor-chat:${input.chatId}`,
+            priority: CHAT_PROVIDER_LEASE_PRIORITY,
+            waitTimeoutMs: CHAT_PROVIDER_LEASE_TIMEOUT_MS,
+            leaseDurationSeconds: CHAT_PROVIDER_LEASE_SECONDS
+        });
+    }
     async generateText(input) {
         const lease = await this.leaseCustomerKey({
             customerId: input.customerId,
@@ -71,7 +207,6 @@ export class ProviderService {
                     eventType: "success",
                     inputTokens: 180,
                     outputTokens: 120,
-                    costUsd: 0.02,
                     metadata: { mock: true }
                 });
                 database.touchProviderKey(lease.keyId);
@@ -80,11 +215,11 @@ export class ProviderService {
                     usage: {
                         inputTokens: 180,
                         outputTokens: 120,
-                        costUsd: 0.02
+                        costUsd: 0
                     }
                 };
             }
-            const result = await this.callProvider({ ...input, apiKey: lease.secret });
+            const result = zeroUsageCost(await this.callProvider({ ...input, apiKey: lease.secret }));
             database.recordProviderKeyUsage({
                 id: createId("usage"),
                 keyId: lease.keyId,
@@ -93,37 +228,97 @@ export class ProviderService {
                 model: input.model,
                 eventType: "success",
                 inputTokens: result.usage.inputTokens,
-                outputTokens: result.usage.outputTokens,
-                costUsd: result.usage.costUsd
+                outputTokens: result.usage.outputTokens
             });
             database.touchProviderKey(lease.keyId);
             return result;
         }
         catch (error) {
-            if (error instanceof ProviderRateLimitError) {
+            this.handleLeasedProviderError({
+                error,
+                lease,
+                jobId: input.jobId,
+                provider: input.provider,
+                model: input.model
+            });
+        }
+        finally {
+            await this.releaseLease(lease);
+        }
+    }
+    async generateSpeech(input) {
+        assertSupportedSpeechModel("tts", input.provider, input.model);
+        const lease = await this.leaseCustomerKey({
+            customerId: input.customerId,
+            provider: input.provider,
+            jobId: input.jobId,
+            workerId: input.workerId
+        });
+        try {
+            if (config.mockProviders) {
+                const contentType = inferSpeechContentType(input.responseFormat ?? "mp3");
                 database.recordProviderKeyUsage({
                     id: createId("usage"),
                     keyId: lease.keyId,
                     jobId: input.jobId,
                     provider: input.provider,
                     model: input.model,
-                    eventType: "rate_limit",
-                    metadata: { retryAfterSeconds: error.retryAfterSeconds }
+                    eventType: "success",
+                    inputTokens: 0,
+                    outputTokens: 0,
+                    metadata: { mock: true, type: "speech_generation" }
                 });
-                database.setProviderKeyCooldown(lease.keyId, addSeconds(new Date(), error.retryAfterSeconds));
+                database.touchProviderKey(lease.keyId);
+                return {
+                    bytes: Buffer.from(`mock speech:${input.text.slice(0, 120)}`, "utf8"),
+                    contentType,
+                    usage: {
+                        inputTokens: 0,
+                        outputTokens: 0,
+                        costUsd: 0
+                    }
+                };
             }
-            else if (error instanceof ProviderAuthError) {
-                database.recordProviderKeyUsage({
-                    id: createId("usage"),
-                    keyId: lease.keyId,
-                    jobId: input.jobId,
-                    provider: input.provider,
+            const result = zeroUsageCost(input.provider === "gemini"
+                ? await this.callGeminiSpeechGeneration({
                     model: input.model,
-                    eventType: "auth_error"
-                });
-                database.setProviderKeyCooldown(lease.keyId, null, "invalid", "auth_error");
-            }
-            throw error;
+                    text: input.text,
+                    voice: input.voice,
+                    instructions: input.instructions,
+                    apiKey: lease.secret
+                })
+                : await this.callOpenAICompatibleSpeechGeneration({
+                    provider: input.provider === "openrouter" ? "openrouter" : "openai",
+                    model: input.model,
+                    text: input.text,
+                    voice: input.voice,
+                    instructions: input.instructions,
+                    responseFormat: input.responseFormat,
+                    apiKey: lease.secret
+                }));
+            database.recordProviderKeyUsage({
+                id: createId("usage"),
+                keyId: lease.keyId,
+                jobId: input.jobId,
+                provider: input.provider,
+                model: input.model,
+                eventType: "success",
+                inputTokens: result.usage.inputTokens,
+                outputTokens: result.usage.outputTokens,
+                metadata: { type: "speech_generation" }
+            });
+            database.touchProviderKey(lease.keyId);
+            return result;
+        }
+        catch (error) {
+            this.handleLeasedProviderError({
+                error,
+                lease,
+                jobId: input.jobId,
+                provider: input.provider,
+                model: input.model,
+                metadata: { type: "speech_generation" }
+            });
         }
         finally {
             await this.releaseLease(lease);
@@ -148,7 +343,6 @@ export class ProviderService {
                     eventType: "success",
                     inputTokens: 0,
                     outputTokens: 0,
-                    costUsd: 0.04,
                     metadata: { mock: true, type: "image_generation" }
                 });
                 database.touchProviderKey(lease.keyId);
@@ -167,14 +361,103 @@ export class ProviderService {
                     imageSize: input.imageSize,
                     apiKey: lease.secret
                 })
-                : await this.callOpenAIImageGeneration({
+                : input.provider === "openrouter"
+                    ? await this.callOpenRouterImageGeneration({
+                        model: input.model,
+                        prompt: input.prompt,
+                        promptAttachments: input.promptAttachments,
+                        aspectRatio: input.aspectRatio,
+                        imageSize: input.imageSize,
+                        apiKey: lease.secret
+                    })
+                    : await this.callOpenAIImageGeneration({
+                        model: input.model,
+                        prompt: input.prompt,
+                        promptAttachments: input.promptAttachments,
+                        size: input.size,
+                        aspectRatio: input.aspectRatio,
+                        apiKey: lease.secret
+                    });
+            database.recordProviderKeyUsage({
+                id: createId("usage"),
+                keyId: lease.keyId,
+                jobId: input.jobId,
+                provider: input.provider,
+                model: input.model,
+                eventType: "success",
+                inputTokens: 0,
+                outputTokens: 0,
+                metadata: { type: "image_generation" }
+            });
+            database.touchProviderKey(lease.keyId);
+            return result;
+        }
+        catch (error) {
+            this.handleLeasedProviderError({
+                error,
+                lease,
+                jobId: input.jobId,
+                provider: input.provider,
+                model: input.model,
+                metadata: { type: "image_generation" }
+            });
+        }
+        finally {
+            await this.releaseLease(lease);
+        }
+    }
+    async editImage(input) {
+        const lease = await this.leaseCustomerKey({
+            customerId: input.customerId,
+            provider: input.provider,
+            jobId: input.jobId,
+            workerId: input.workerId
+        });
+        try {
+            if (config.mockProviders) {
+                const svg = buildMockSlideSvg(`EDIT ${input.instruction}\n${input.sourceImageUrl}`);
+                database.recordProviderKeyUsage({
+                    id: createId("usage"),
+                    keyId: lease.keyId,
+                    jobId: input.jobId,
+                    provider: input.provider,
                     model: input.model,
-                    prompt: input.prompt,
-                    promptAttachments: input.promptAttachments,
+                    eventType: "success",
+                    inputTokens: 0,
+                    outputTokens: 0,
+                    metadata: { mock: true, type: "image_edit" }
+                });
+                database.touchProviderKey(lease.keyId);
+                return {
+                    bytes: Buffer.from(svg, "utf8"),
+                    contentType: "image/svg+xml",
+                    revisedPrompt: input.instruction
+                };
+            }
+            const result = input.provider === "openai"
+                ? await this.callOpenAIImageEdit({
+                    model: input.model,
+                    sourceImageUrl: input.sourceImageUrl,
+                    instruction: input.instruction,
+                    maskUrl: input.maskUrl,
                     size: input.size,
-                    aspectRatio: input.aspectRatio,
                     apiKey: lease.secret
-                });
+                })
+                : input.provider === "perplexity"
+                    ? (() => {
+                        throw new Error("Perplexity image edit is not supported.");
+                    })()
+                    : await this.callAttachmentDrivenImageEdit({
+                        provider: input.provider,
+                        model: input.model,
+                        sourceImageUrl: input.sourceImageUrl,
+                        instruction: input.instruction,
+                        referenceAttachments: input.referenceAttachments,
+                        maskUrl: input.maskUrl,
+                        aspectRatio: input.aspectRatio,
+                        imageSize: input.imageSize,
+                        apiKey: lease.secret
+                    });
             database.recordProviderKeyUsage({
                 id: createId("usage"),
                 keyId: lease.keyId,
@@ -184,16 +467,31 @@ export class ProviderService {
                 eventType: "success",
                 inputTokens: 0,
                 outputTokens: 0,
-                costUsd: 0.04,
-                metadata: { type: "image_generation" }
+                metadata: { type: input.maskUrl ? "image_inpaint" : "image_edit" }
             });
             database.touchProviderKey(lease.keyId);
             return result;
         }
+        catch (error) {
+            this.handleLeasedProviderError({
+                error,
+                lease,
+                jobId: input.jobId,
+                provider: input.provider,
+                model: input.model,
+                metadata: { type: input.maskUrl ? "image_inpaint" : "image_edit" }
+            });
+        }
         finally {
             await this.releaseLease(lease);
         }
     }
+    async inpaintImage(input) {
+        return this.editImage({
+            ...input,
+            maskUrl: input.maskUrl
+        });
+    }
     async analyzeImageLayout(input) {
         const lease = await this.leaseCustomerKey({
             customerId: input.customerId,
@@ -212,7 +510,6 @@ export class ProviderService {
                     eventType: "success",
                     inputTokens: 0,
                     outputTokens: 0,
-                    costUsd: 0.005,
                     metadata: { mock: true, type: "layout_analysis" }
                 });
                 database.touchProviderKey(lease.keyId);
@@ -250,7 +547,6 @@ export class ProviderService {
                 eventType: "success",
                 inputTokens: 0,
                 outputTokens: 0,
-                costUsd: 0.005,
                 metadata: { type: "layout_analysis" }
             });
             database.touchProviderKey(lease.keyId);
@@ -261,6 +557,101 @@ export class ProviderService {
                 justification: parsed.justification ?? "Selected to preserve legibility and subject framing."
             };
         }
+        catch (error) {
+            this.handleLeasedProviderError({
+                error,
+                lease,
+                jobId: input.jobId,
+                provider: input.provider,
+                model: input.model,
+                metadata: { type: "layout_analysis" }
+            });
+        }
+        finally {
+            await this.releaseLease(lease);
+        }
+    }
+    async transcribeSpeech(input) {
+        assertSupportedSpeechModel("stt", input.provider, input.model);
+        const lease = await this.leaseCustomerKey({
+            customerId: input.customerId,
+            provider: input.provider,
+            jobId: input.jobId,
+            workerId: input.workerId
+        });
+        try {
+            if (config.mockProviders) {
+                database.recordProviderKeyUsage({
+                    id: createId("usage"),
+                    keyId: lease.keyId,
+                    jobId: input.jobId,
+                    provider: input.provider,
+                    model: input.model,
+                    eventType: "success",
+                    inputTokens: 0,
+                    outputTokens: 0,
+                    metadata: { mock: true, type: "speech_transcription" }
+                });
+                database.touchProviderKey(lease.keyId);
+                return {
+                    text: "Mock transcription output.",
+                    usage: {
+                        inputTokens: 0,
+                        outputTokens: 0,
+                        costUsd: 0
+                    }
+                };
+            }
+            const result = zeroUsageCost(input.provider === "gemini"
+                ? await this.callGeminiSpeechTranscription({
+                    model: input.model,
+                    audio: input.audio,
+                    contentType: input.contentType,
+                    prompt: input.prompt,
+                    language: input.language,
+                    apiKey: lease.secret
+                })
+                : input.provider === "openrouter"
+                    ? await this.callOpenRouterSpeechTranscription({
+                        model: input.model,
+                        audio: input.audio,
+                        contentType: input.contentType,
+                        prompt: input.prompt,
+                        language: input.language,
+                        apiKey: lease.secret
+                    })
+                    : await this.callOpenAISpeechTranscription({
+                        model: input.model,
+                        audio: input.audio,
+                        contentType: input.contentType,
+                        prompt: input.prompt,
+                        language: input.language,
+                        apiKey: lease.secret
+                    }));
+            database.recordProviderKeyUsage({
+                id: createId("usage"),
+                keyId: lease.keyId,
+                jobId: input.jobId,
+                provider: input.provider,
+                model: input.model,
+                eventType: "success",
+                inputTokens: result.usage.inputTokens,
+                outputTokens: result.usage.outputTokens,
+                metadata: { type: "speech_transcription" }
+            });
+            database.touchProviderKey(lease.keyId);
+            return result;
+        }
+        catch (error) {
+            this.handleLeasedProviderError({
+                error,
+                lease,
+                jobId: input.jobId,
+                provider: input.provider,
+                model: input.model,
+                metadata: { type: "speech_transcription" }
+            });
+        }
         finally {
             await this.releaseLease(lease);
         }
@@ -308,6 +699,77 @@ export class ProviderService {
             revisedPrompt: data.data?.[0]?.revised_prompt ?? null
         };
     }
+    async callOpenAIImageEdit(input) {
+        const form = new FormData();
+        form.set("model", input.model);
+        form.set("prompt", input.instruction);
+        form.set("size", input.size ?? "1024x1024");
+        form.set("image", await remoteImageToBlob(input.sourceImageUrl));
+        if (input.maskUrl) {
+            form.set("mask", await remoteImageToBlob(input.maskUrl));
+        }
+        const response = await fetch("https://api.openai.com/v1/images/edits", {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${input.apiKey}`
+            },
+            body: form
+        });
+        if (response.status === 401) {
+            throw new ProviderAuthError("openai authentication failed");
+        }
+        if (response.status === 429) {
+            throw new ProviderRateLimitError("openai rate limited");
+        }
+        if (!response.ok) {
+            const details = await response.text();
+            throw new Error(`openai image edit returned ${response.status}${details ? `: ${details}` : ""}`);
+        }
+        const data = await response.json();
+        const encoded = data.data?.[0]?.b64_json;
+        if (!encoded) {
+            throw new Error("openai image edit returned no image payload");
+        }
+        return {
+            bytes: Buffer.from(encoded, "base64"),
+            contentType: "image/png",
+            revisedPrompt: data.data?.[0]?.revised_prompt ?? null
+        };
+    }
+    async callAttachmentDrivenImageEdit(input) {
+        const promptAttachments = [
+            input.sourceImageUrl,
+            ...(input.maskUrl ? [input.maskUrl] : []),
+            ...(input.referenceAttachments ?? [])
+        ];
+        const prompt = [
+            input.maskUrl
+                ? "Edit this image using the provided source image and mask."
+                : "Edit this image using the provided source image as the base reference.",
+            input.maskUrl
+                ? "Only change the masked region. Preserve all unmasked regions exactly."
+                : "Preserve the overall composition unless the instruction explicitly changes it.",
+            `Instruction: ${input.instruction}`,
+            "Return one final edited image only."
+        ].join("\n");
+        return input.provider === "gemini"
+            ? this.callGeminiImageGeneration({
+                model: input.model,
+                prompt,
+                promptAttachments,
+                aspectRatio: input.aspectRatio,
+                imageSize: input.imageSize,
+                apiKey: input.apiKey
+            })
+            : this.callOpenRouterImageGeneration({
+                model: input.model,
+                prompt,
+                promptAttachments,
+                aspectRatio: input.aspectRatio,
+                imageSize: input.imageSize,
+                apiKey: input.apiKey
+            });
+    }
     async callGeminiImageGeneration(input) {
         const imageConfig = {};
         if (input.aspectRatio) {
@@ -355,6 +817,182 @@ export class ProviderService {
             revisedPrompt: null
         };
     }
+    async callOpenRouterImageGeneration(input) {
+        const content = [
+            { type: "text", text: input.prompt },
+            ...(input.promptAttachments ?? []).map((url) => ({
+                type: "image_url",
+                image_url: { url }
+            }))
+        ];
+        const imageConfig = {};
+        if (input.aspectRatio) {
+            imageConfig.aspect_ratio = input.aspectRatio;
+        }
+        if (input.imageSize) {
+            imageConfig.image_size = input.imageSize;
+        }
+        const response = await fetch("https://openrouter.ai/api/v1/chat/completions", {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${input.apiKey}`
+            },
+            body: JSON.stringify({
+                model: input.model,
+                messages: [
+                    {
+                        role: "user",
+                        content
+                    }
+                ],
+                modalities: ["image", "text"],
+                stream: false,
+                ...(Object.keys(imageConfig).length
+                    ? {
+                        image_config: imageConfig
+                    }
+                    : {})
+            })
+        });
+        if (response.status === 401 || response.status === 403) {
+            throw new ProviderAuthError("openrouter authentication failed");
+        }
+        if (response.status === 429) {
+            throw new ProviderRateLimitError("openrouter rate limited");
+        }
+        if (!response.ok) {
+            const details = await response.text();
+            throw new Error(`openrouter image generation returned ${response.status}${details ? `: ${details}` : ""}`);
+        }
+        const data = await response.json();
+        const imageUrl = data.choices?.[0]?.message?.images?.[0]?.image_url?.url ??
+            data.choices?.[0]?.message?.images?.[0]?.imageUrl?.url;
+        if (!imageUrl) {
+            throw new Error("openrouter image generation returned no image payload");
+        }
+        const parsed = decodeInlineDataUrl(imageUrl);
+        if (!parsed) {
+            throw new Error("openrouter image generation returned an unsupported image payload");
+        }
+        return {
+            bytes: parsed.bytes,
+            contentType: parsed.contentType,
+            revisedPrompt: data.choices?.[0]?.message?.content ?? null
+        };
+    }
+    async callOpenAICompatibleSpeechGeneration(input) {
+        const requestedFormat = input.responseFormat ?? "mp3";
+        const usePcmBridge = input.provider === "openrouter" &&
+            /gemini/i.test(input.model) &&
+            requestedFormat !== "mp3";
+        const responseFormat = usePcmBridge ? "pcm" : requestedFormat;
+        const endpoint = input.provider === "openrouter"
+            ? "https://openrouter.ai/api/v1/audio/speech"
+            : "https://api.openai.com/v1/audio/speech";
+        const response = await fetch(endpoint, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${input.apiKey}`
+            },
+            body: JSON.stringify({
+                model: input.model,
+                input: input.text,
+                voice: input.voice ?? "alloy",
+                instructions: input.instructions,
+                response_format: responseFormat
+            })
+        });
+        if (response.status === 401 || response.status === 403) {
+            throw new ProviderAuthError(`${input.provider} authentication failed`);
+        }
+        if (response.status === 429) {
+            throw new ProviderRateLimitError(`${input.provider} rate limited`);
+        }
+        if (!response.ok) {
+            const details = await response.text();
+            throw new Error(`${input.provider} speech generation returned ${response.status}${details ? `: ${details}` : ""}`);
+        }
+        const rawBytes = Buffer.from(await response.arrayBuffer());
+        const bytes = usePcmBridge ? pcm16MonoToWav(rawBytes, 24000) : rawBytes;
+        const contentType = usePcmBridge
+            ? "audio/wav"
+            : response.headers.get("content-type")?.split(";")[0]?.trim() || inferSpeechContentType(responseFormat);
+        return {
+            bytes,
+            contentType,
+            usage: {
+                inputTokens: 0,
+                outputTokens: 0,
+                costUsd: 0
+            }
+        };
+    }
+    async callGeminiSpeechGeneration(input) {
+        const prompt = input.instructions?.trim()
+            ? `${input.instructions.trim()}\n\nSpeak exactly the following text:\n${input.text}`
+            : input.text;
+        const response = await fetch(`https://generativelanguage.googleapis.com/v1beta/models/${input.model}:generateContent?key=${input.apiKey}`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json"
+            },
+            body: JSON.stringify({
+                contents: [{ parts: [{ text: prompt }] }],
+                generationConfig: {
+                    responseModalities: ["AUDIO"],
+                    speechConfig: {
+                        voiceConfig: {
+                            prebuiltVoiceConfig: {
+                                voiceName: input.voice ?? "Kore"
+                            }
+                        }
+                    }
+                }
+            })
+        });
+        if (response.status === 401 || response.status === 403) {
+            throw new ProviderAuthError("gemini authentication failed");
+        }
+        if (response.status === 429) {
+            throw new ProviderRateLimitError("gemini rate limited");
+        }
+        if (!response.ok) {
+            const details = await response.text();
+            throw new Error(`gemini speech generation returned ${response.status}${details ? `: ${details}` : ""}`);
+        }
+        const data = await response.json();
+        const part = data.candidates?.[0]?.content?.parts?.find((item) => item.inlineData?.data || item.inline_data?.data);
+        const encoded = part?.inlineData?.data ?? part?.inline_data?.data;
+        if (!encoded) {
+            throw new Error("gemini speech generation returned no audio payload");
+        }
+        const rawBytes = Buffer.from(encoded, "base64");
+        const rawContentType = String(part?.inlineData?.mimeType ?? part?.inline_data?.mime_type ?? "audio/L16;rate=24000");
+        const pcmRateMatch = /audio\/l16;?\s*rate=(\d+)/i.exec(rawContentType);
+        const looksLikeWav = isWavBuffer(rawBytes);
+        const looksLikeMp3 = isLikelyMp3Buffer(rawBytes);
+        const shouldWrapPcm = Boolean(pcmRateMatch ||
+            (!looksLikeWav && !looksLikeMp3));
+        const bytes = shouldWrapPcm
+            ? pcm16MonoToWav(rawBytes, Number(pcmRateMatch?.[1] || "24000"))
+            : rawBytes;
+        const contentType = shouldWrapPcm
+            ? "audio/wav"
+            : looksLikeWav
+                ? "audio/wav"
+                : "audio/mpeg";
+        return {
+            bytes,
+            contentType,
+            usage: {
+                inputTokens: Number(data.usageMetadata?.promptTokenCount ?? 0),
+                outputTokens: Number(data.usageMetadata?.candidatesTokenCount ?? 0),
+                costUsd: 0
+            }
+        };
+    }
     async callOpenAICompatibleLayoutAnalysis(input) {
         const endpoint = input.provider === "openrouter"
             ? "https://openrouter.ai/api/v1/chat/completions"
@@ -458,6 +1096,128 @@ export class ProviderService {
         const text = data.candidates?.[0]?.content?.parts?.map((part) => part.text ?? "").join("\n") ?? "";
         return String(text);
     }
+    async callOpenAISpeechTranscription(input) {
+        const contentType = input.contentType ?? "audio/mpeg";
+        const form = new FormData();
+        form.set("file", new Blob([Buffer.from(input.audio)], { type: contentType }), `audio.${audioExtensionFromContentType(contentType)}`);
+        form.set("model", input.model);
+        form.set("response_format", "json");
+        if (input.prompt) {
+            form.set("prompt", input.prompt);
+        }
+        if (input.language) {
+            form.set("language", input.language);
+        }
+        const response = await fetch("https://api.openai.com/v1/audio/transcriptions", {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${input.apiKey}`
+            },
+            body: form
+        });
+        if (response.status === 401 || response.status === 403) {
+            throw new ProviderAuthError("openai authentication failed");
+        }
+        if (response.status === 429) {
+            throw new ProviderRateLimitError("openai rate limited");
+        }
+        if (!response.ok) {
+            const details = await response.text();
+            throw new Error(`openai transcription returned ${response.status}${details ? `: ${details}` : ""}`);
+        }
+        const data = await response.json();
+        return {
+            text: String(data.text ?? ""),
+            usage: {
+                inputTokens: Number(data.usage?.input_tokens ?? 0),
+                outputTokens: Number(data.usage?.output_tokens ?? 0),
+                costUsd: Number(data.usage?.cost ?? 0)
+            }
+        };
+    }
+    async callOpenRouterSpeechTranscription(input) {
+        const response = await fetch("https://openrouter.ai/api/v1/audio/transcriptions", {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${input.apiKey}`
+            },
+            body: JSON.stringify({
+                model: input.model,
+                input_audio: {
+                    data: Buffer.from(input.audio).toString("base64"),
+                    format: audioFormatFromContentType(input.contentType)
+                },
+                ...(input.prompt ? { prompt: input.prompt } : {}),
+                ...(input.language ? { language: input.language } : {})
+            })
+        });
+        if (response.status === 401 || response.status === 403) {
+            throw new ProviderAuthError("openrouter authentication failed");
+        }
+        if (response.status === 429) {
+            throw new ProviderRateLimitError("openrouter rate limited");
+        }
+        if (!response.ok) {
+            const details = await response.text();
+            throw new Error(`openrouter transcription returned ${response.status}${details ? `: ${details}` : ""}`);
+        }
+        const data = await response.json();
+        return {
+            text: String(data.text ?? ""),
+            usage: {
+                inputTokens: Number(data.usage?.input_tokens ?? data.usage?.prompt_tokens ?? 0),
+                outputTokens: Number(data.usage?.output_tokens ?? data.usage?.completion_tokens ?? 0),
+                costUsd: Number(data.usage?.cost ?? 0)
+            }
+        };
+    }
+    async callGeminiSpeechTranscription(input) {
+        const response = await fetch(`https://generativelanguage.googleapis.com/v1beta/models/${input.model}:generateContent?key=${input.apiKey}`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json"
+            },
+            body: JSON.stringify({
+                contents: [{
+                        parts: [
+                            {
+                                inline_data: {
+                                    mime_type: input.contentType ?? "audio/mpeg",
+                                    data: Buffer.from(input.audio).toString("base64")
+                                }
+                            },
+                            {
+                                text: buildGeminiTranscriptionPrompt(input.prompt, input.language)
+                            }
+                        ]
+                    }],
+                generationConfig: {
+                    temperature: 0,
+                    responseMimeType: "text/plain"
+                }
+            })
+        });
+        if (response.status === 401 || response.status === 403) {
+            throw new ProviderAuthError("gemini authentication failed");
+        }
+        if (response.status === 429) {
+            throw new ProviderRateLimitError("gemini rate limited");
+        }
+        if (!response.ok) {
+            const details = await response.text();
+            throw new Error(`gemini transcription returned ${response.status}${details ? `: ${details}` : ""}`);
+        }
+        const data = await response.json();
+        return {
+            text: extractGeminiText(data),
+            usage: {
+                inputTokens: Number(data.usageMetadata?.promptTokenCount ?? 0),
+                outputTokens: Number(data.usageMetadata?.candidatesTokenCount ?? 0),
+                costUsd: 0
+            }
+        };
+    }
     async callProvider(input) {
         if (input.provider === "gemini") {
             return this.callGemini({
@@ -543,24 +1303,143 @@ export class ProviderService {
 function clamp(value, min, max) {
     return Math.max(min, Math.min(max, value));
 }
+function summarizeProviderValidationError(error) {
+    const rawMessage = error instanceof Error ? error.message : "Unknown provider error";
+    return rawMessage
+        .replace(/\s+/g, " ")
+        .trim()
+        .slice(0, 280);
+}
+function toProviderValidationMessage(provider, error) {
+    const providerLabel = formatProviderLabel(provider);
+    const summary = summarizeProviderValidationError(error);
+    if (!summary) {
+        return `Unable to verify ${providerLabel} API key.`;
+    }
+    if (/401|403|invalid api key|api key not valid|incorrect api key|unauthorized|permission denied|authentication failed/i.test(summary)) {
+        return `${providerLabel} API key was rejected by the provider. ${summary}`;
+    }
+    return `Unable to verify ${providerLabel} API key. ${summary}`;
+}
+function formatProviderLabel(provider) {
+    switch (provider) {
+        case "openai":
+            return "OpenAI";
+        case "gemini":
+            return "Gemini";
+        case "openrouter":
+            return "OpenRouter";
+        case "perplexity":
+            return "Perplexity";
+    }
+}
+function assertSupportedSpeechModel(kind, provider, model) {
+    const normalizedModel = model.trim();
+    if (!normalizedModel) {
+        throw new Error(`Missing ${kind.toUpperCase()} model for provider ${provider}.`);
+    }
+    const speechCapableProviders = ["openai", "gemini", "openrouter"];
+    if (!speechCapableProviders.includes(provider)) {
+        throw new Error(`Provider ${provider} does not support ${kind.toUpperCase()} requests.`);
+    }
+}
+function inferSpeechContentType(format) {
+    return format === "wav" ? "audio/wav" : "audio/mpeg";
+}
+function pcm16MonoToWav(pcmBuffer, sampleRate) {
+    const header = Buffer.alloc(44);
+    header.write("RIFF", 0, 4, "ascii");
+    header.writeUInt32LE(36 + pcmBuffer.byteLength, 4);
+    header.write("WAVE", 8, 4, "ascii");
+    header.write("fmt ", 12, 4, "ascii");
+    header.writeUInt32LE(16, 16);
+    header.writeUInt16LE(1, 20);
+    header.writeUInt16LE(1, 22);
+    header.writeUInt32LE(sampleRate, 24);
+    header.writeUInt32LE(sampleRate * 2, 28);
+    header.writeUInt16LE(2, 32);
+    header.writeUInt16LE(16, 34);
+    header.write("data", 36, 4, "ascii");
+    header.writeUInt32LE(pcmBuffer.byteLength, 40);
+    return Buffer.concat([header, pcmBuffer]);
+}
+function isWavBuffer(buffer) {
+    return buffer.byteLength >= 12
+        && buffer.subarray(0, 4).toString("ascii") === "RIFF"
+        && buffer.subarray(8, 12).toString("ascii") === "WAVE";
+}
+function isLikelyMp3Buffer(buffer) {
+    if (buffer.byteLength < 3) {
+        return false;
+    }
+    if (buffer.subarray(0, 3).toString("ascii") === "ID3") {
+        return true;
+    }
+    return buffer[0] === 0xff && (buffer[1] & 0xe0) === 0xe0;
+}
+function audioFormatFromContentType(contentType) {
+    const normalized = contentType?.split(";")[0]?.trim().toLowerCase();
+    switch (normalized) {
+        case "audio/wav":
+        case "audio/x-wav":
+            return "wav";
+        case "audio/mp4":
+        case "audio/m4a":
+            return "mp4";
+        case "audio/webm":
+            return "webm";
+        case "audio/ogg":
+            return "ogg";
+        default:
+            return "mp3";
+    }
+}
+function audioExtensionFromContentType(contentType) {
+    switch (audioFormatFromContentType(contentType)) {
+        case "wav":
+            return "wav";
+        case "mp4":
+            return "m4a";
+        case "webm":
+            return "webm";
+        case "ogg":
+            return "ogg";
+        default:
+            return "mp3";
+    }
+}
+function buildGeminiTranscriptionPrompt(prompt, language) {
+    const basePrompt = prompt?.trim() || "Transcribe this audio verbatim. Return plain text only.";
+    return language?.trim()
+        ? `${basePrompt}\n\nExpected language: ${language.trim()}.`
+        : basePrompt;
+}
+function extractGeminiText(data) {
+    return String(data.candidates?.[0]?.content?.parts?.map((part) => part.text ?? "").join("\n") ?? "");
+}
 function supportsGeminiImageSize(model) {
     return model === "gemini-3.1-flash-image-preview" || model === "gemini-3-pro-image-preview";
 }
+async function fetchRemoteBytes(input) {
+    const response = await fetch(input.url);
+    if (!response.ok) {
+        throw new Error(`Could not fetch remote media ${input.url}: ${response.status}`);
+    }
+    const mimeType = response.headers.get("content-type")?.split(";")[0]?.trim() || input.fallbackMimeType || "application/octet-stream";
+    const bytes = Buffer.from(await response.arrayBuffer());
+    return { bytes, mimeType };
+}
+async function remoteImageToBlob(url) {
+    const { bytes, mimeType } = await fetchRemoteBytes({ url, fallbackMimeType: "image/png" });
+    return new Blob([bytes], { type: mimeType });
+}
 async function buildGeminiPromptParts(prompt, attachments) {
     const parts = [];
     for (const attachment of attachments) {
         if (!/^https?:\/\//i.test(attachment)) {
             throw new Error(`Gemini prompt attachments must be public URLs: ${attachment}`);
         }
-        const response = await fetch(attachment);
-        if (!response.ok) {
-            throw new Error(`Could not fetch Gemini prompt attachment ${attachment}: ${response.status}`);
-        }
-        const mimeType = response.headers.get("content-type")?.split(";")[0]?.trim();
-        if (!mimeType) {
-            throw new Error(`Gemini prompt attachment did not return a content type: ${attachment}`);
-        }
-        const bytes = Buffer.from(await response.arrayBuffer());
+        const { bytes, mimeType } = await fetchRemoteBytes({ url: attachment });
         parts.push({
             inlineData: {
                 mimeType,
@@ -571,6 +1450,16 @@ async function buildGeminiPromptParts(prompt, attachments) {
     parts.push({ text: prompt });
     return parts;
 }
+function decodeInlineDataUrl(value) {
+    const match = value.match(/^data:([^;,]+);base64,(.+)$/);
+    if (!match) {
+        return null;
+    }
+    return {
+        contentType: match[1],
+        bytes: Buffer.from(match[2], "base64")
+    };
+}
 function buildMockSlideSvg(prompt) {
     const escaped = escapeXml(prompt.slice(0, 220));
     return `