@xiaozhiclaw/provider-core 0.1.0

package/dist/transports/gemini-media.js

@@ -0,0 +1,383 @@
+/**
+ * Gemini Media Transport 鈥?unified media generation for all Gemini media APIs.
+ *
+ * Supported media types and endpoints:
+ *   image          鈥?POST /models/{model}:generateContent  (responseModalities: ["TEXT","IMAGE"])
+ *   video          鈥?POST /models/{model}:predictLongRunning 鈫?poll operations 鈫?download URI
+ *   music          鈥?POST /models/{model}:generateContent  (Lyria 3 鈥?inlineData audio)
+ *   music_realtime 鈥?WebSocket session (Lyria RealTime 鈥?streaming PCM 鈫?WAV)
+ *   tts            鈥?POST /models/{model}:generateContent  (speechConfig 鈥?inlineData PCM)
+ *   embedding      鈥?POST /models/{model}:embedContent   (float vector)
+ *
+ * Auth: x-goog-api-key header for all endpoints.
+ */
+import { writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { getUserCacheDir } from "../paths.js";
+import { generateRealtimeMusic } from "./gemini-lyria-realtime.js";
+const DEFAULT_TIMEOUT_MS = 180_000;
+const VIDEO_POLL_INTERVAL_MS = 10_000;
+const VIDEO_MAX_POLL_MS = 600_000; // 10 min
+export class GeminiMediaTransport {
+    supportedTypes = ["image", "video", "music", "music_realtime", "tts", "embedding"];
+    apiBase;
+    timeoutMs;
+    constructor(config) {
+        this.apiBase = config.baseUrl
+            .replace(/\/openai\/?$/, "")
+            .replace(/\/+$/, "");
+        this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    }
+    async generate(request, apiKey, signal) {
+        switch (request.mediaType) {
+            case "image": return this.generateImage(request, apiKey, signal);
+            case "video": return this.generateVideo(request, apiKey, signal);
+            case "music": return this.generateMusic(request, apiKey, signal);
+            case "music_realtime": return this.generateMusicRealtime(request, apiKey, signal);
+            case "tts": return this.generateTTS(request, apiKey, signal);
+            case "embedding": return this.generateEmbedding(request, apiKey, signal);
+            default:
+                throw new Error(`GeminiMediaTransport: unsupported mediaType "${request.mediaType}"`);
+        }
+    }
+    // 鈹€鈹€ AsyncMediaTransport task management (video only) 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+    async deleteVideoTask(_taskId, _apiKey, _signal) {
+        // Gemini operations API does not expose a cancel/delete endpoint for video tasks
+        throw new Error("Gemini does not support deleting video generation tasks");
+    }
+    async listVideoTasks(_apiKey, _options, _signal) {
+        // Gemini operations API does not expose a list endpoint
+        return { data: [] };
+    }
+    async getTaskStatus(taskId, apiKey, signal) {
+        const url = `${this.apiBase}/${taskId}`;
+        const res = await fetch(url, {
+            method: "GET",
+            headers: { "x-goog-api-key": apiKey },
+            signal: signal ?? AbortSignal.timeout(this.timeoutMs),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`Gemini operation query error ${res.status}: ${text}`);
+        }
+        const data = await res.json();
+        const done = data.done;
+        return {
+            status: done ? "completed" : "running",
+            task: data,
+        };
+    }
+    // 鈹€鈹€ Image (Nano Banana / Gemini generateContent) 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+    async generateImage(request, apiKey, signal) {
+        const start = Date.now();
+        const url = `${this.apiBase}/models/${request.model}:generateContent`;
+        const generationConfig = {
+            responseModalities: ["TEXT", "IMAGE"],
+        };
+        if (request.aspectRatio)
+            generationConfig.aspectRatio = request.aspectRatio;
+        const body = {
+            contents: [{
+                    parts: [{ text: request.prompt }],
+                }],
+            generationConfig,
+        };
+        const data = await this.postJson(url, body, apiKey, signal);
+        const mediaUrls = this.extractInlineImages(data);
+        return {
+            mediaUrls,
+            model: request.model,
+            durationMs: Date.now() - start,
+        };
+    }
+    // 鈹€鈹€ Video (Veo 鈥?predictLongRunning 鈫?poll 鈫?download) 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+    async generateVideo(request, apiKey, signal) {
+        const start = Date.now();
+        const url = `${this.apiBase}/models/${request.model}:predictLongRunning`;
+        // Build instances
+        const instance = { prompt: request.prompt };
+        // Image-to-video: first frame image
+        if (request.imageUrl) {
+            instance.image = { inlineData: await this.resolveImageData(request.imageUrl) };
+        }
+        // Reference images (Veo 3.1 鈥?asset references)
+        if (request.referenceImages?.length) {
+            instance.referenceImages = await Promise.all(request.referenceImages.map(async (imgUrl) => ({
+                image: { inlineData: await this.resolveImageData(imgUrl) },
+                referenceType: "asset",
+            })));
+        }
+        // Build parameters
+        const parameters = {};
+        if (request.aspectRatio)
+            parameters.aspectRatio = request.aspectRatio;
+        if (request.resolution)
+            parameters.resolution = request.resolution;
+        if (request.duration)
+            parameters.durationSeconds = String(request.duration);
+        if (request.n)
+            parameters.numberOfVideos = request.n;
+        if (request.seed !== undefined)
+            parameters.seed = request.seed;
+        const body = { instances: [instance] };
+        if (Object.keys(parameters).length > 0)
+            body.parameters = parameters;
+        // Submit
+        const submitRes = await this.postJson(url, body, apiKey, signal);
+        const operationName = submitRes.name;
+        if (!operationName) {
+            throw new Error("Gemini video submit: no operation name in response");
+        }
+        const taskId = operationName;
+        request.onProgress?.(5, "submitted", taskId);
+        // Poll
+        const result = await this.pollOperation(operationName, apiKey, signal, request.onProgress, taskId);
+        // Extract video URI from completed operation
+        const videoResponse = result.response?.generateVideoResponse;
+        const samples = (videoResponse?.generatedSamples ?? []);
+        const mediaUrls = [];
+        for (const sample of samples) {
+            if (sample.video?.uri) {
+                mediaUrls.push(sample.video.uri);
+            }
+        }
+        return {
+            mediaUrls,
+            model: request.model,
+            durationMs: Date.now() - start,
+            taskId,
+        };
+    }
+    // 鈹€鈹€ Music (Lyria 3 鈥?generateContent 鈫?inlineData audio) 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+    async generateMusic(request, apiKey, signal) {
+        const start = Date.now();
+        const url = `${this.apiBase}/models/${request.model}:generateContent`;
+        const parts = [{ text: request.prompt }];
+        const generationConfig = {};
+        // Lyria defaults to AUDIO+TEXT, but we can be explicit
+        if (request.audioFormat === "wav") {
+            generationConfig.responseModalities = ["AUDIO", "TEXT"];
+            generationConfig.responseFormat = { audio: { mimeType: "audio/wav" } };
+        }
+        const body = {
+            contents: [{ parts }],
+        };
+        if (Object.keys(generationConfig).length > 0)
+            body.generationConfig = generationConfig;
+        const data = await this.postJson(url, body, apiKey, signal);
+        const mediaUrls = this.extractInlineAudio(data, "gemini-music");
+        return {
+            mediaUrls,
+            model: request.model,
+            durationMs: Date.now() - start,
+        };
+    }
+    // 鈹€鈹€ Music RealTime (Lyria RealTime 鈥?WebSocket streaming session) 鈹€鈹€鈹€鈹€
+    async generateMusicRealtime(request, apiKey, signal) {
+        const result = await generateRealtimeMusic(apiKey, { baseUrl: this.apiBase }, {
+            prompts: [{ text: request.prompt, weight: 1.0 }],
+            durationSeconds: request.duration ?? 30,
+            musicConfig: {
+                audioFormat: request.audioFormat === "wav" ? "pcm16" : undefined,
+                sampleRateHz: 48000,
+            },
+            model: request.model,
+            signal,
+            onProgress: request.onProgress,
+        });
+        return {
+            mediaUrls: [result.filePath],
+            model: request.model,
+            durationMs: result.durationMs,
+        };
+    }
+    // 鈹€鈹€ TTS (generateContent with speechConfig 鈫?PCM audio) 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+    async generateTTS(request, apiKey, signal) {
+        const start = Date.now();
+        const url = `${this.apiBase}/models/${request.model}:generateContent`;
+        const generationConfig = {
+            responseModalities: ["AUDIO"],
+        };
+        // Build speechConfig
+        if (request.voice) {
+            generationConfig.speechConfig = {
+                voiceConfig: {
+                    prebuiltVoiceConfig: { voiceName: request.voice },
+                },
+            };
+        }
+        const body = {
+            contents: [{ parts: [{ text: request.text ?? request.prompt }] }],
+            generationConfig,
+        };
+        const data = await this.postJson(url, body, apiKey, signal);
+        const mediaUrls = this.extractInlineAudio(data, "gemini-tts");
+        return {
+            mediaUrls,
+            model: request.model,
+            durationMs: Date.now() - start,
+        };
+    }
+    // 鈹€鈹€ Embedding (embedContent 鈫?float vector) 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+    async generateEmbedding(request, apiKey, signal) {
+        const start = Date.now();
+        const url = `${this.apiBase}/models/${request.model}:embedContent`;
+        const body = {
+            content: { parts: [{ text: request.text ?? request.prompt }] },
+        };
+        // Support output_dimensionality via metadata
+        const dims = request.metadata?.outputDimensionality;
+        if (dims !== undefined)
+            body.output_dimensionality = dims;
+        const data = await this.postJson(url, body, apiKey, signal);
+        const values = data.embedding?.values ?? data.embeddings?.[0]?.values ?? [];
+        return {
+            mediaUrls: [],
+            model: request.model,
+            durationMs: Date.now() - start,
+            metadata: { embedding: values, dimensions: values.length },
+        };
+    }
+    // 鈹€鈹€ Shared helpers 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+    async postJson(url, body, apiKey, signal) {
+        const res = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "x-goog-api-key": apiKey,
+            },
+            body: JSON.stringify(body),
+            signal: signal ?? AbortSignal.timeout(this.timeoutMs),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`Gemini API error ${res.status}: ${text}`);
+        }
+        return res.json();
+    }
+    async pollOperation(operationName, apiKey, signal, onProgress, taskId) {
+        const deadline = Date.now() + VIDEO_MAX_POLL_MS;
+        while (Date.now() < deadline) {
+            signal?.throwIfAborted();
+            const url = `${this.apiBase}/${operationName}`;
+            const res = await fetch(url, {
+                method: "GET",
+                headers: { "x-goog-api-key": apiKey },
+                signal: signal ?? AbortSignal.timeout(this.timeoutMs),
+            });
+            if (!res.ok) {
+                const text = await res.text().catch(() => "");
+                throw new Error(`Gemini operation poll error ${res.status}: ${text}`);
+            }
+            const data = await res.json();
+            if (data.done === true) {
+                onProgress?.(100, "completed", taskId);
+                return data;
+            }
+            // Check for error
+            if (data.error) {
+                const errObj = data.error;
+                throw new Error(`Gemini video generation failed: ${errObj.message ?? JSON.stringify(errObj)}`);
+            }
+            // Estimate progress from elapsed time
+            const elapsed = Date.now() - (deadline - VIDEO_MAX_POLL_MS);
+            const estimatedPercent = Math.min(95, Math.round((elapsed / VIDEO_MAX_POLL_MS) * 100));
+            onProgress?.(estimatedPercent, "running", taskId);
+            await new Promise(r => setTimeout(r, VIDEO_POLL_INTERVAL_MS));
+        }
+        throw new Error("Gemini video generation timed out after polling");
+    }
+    /**
+     * Resolve an image URL to inline data for the Veo API.
+     * Supports file:// paths and https:// URLs.
+     */
+    async resolveImageData(imageUrl) {
+        if (imageUrl.startsWith("data:")) {
+            // data:image/png;base64,...
+            const match = imageUrl.match(/^data:([^;]+);base64,(.+)$/);
+            if (match)
+                return { mimeType: match[1], data: match[2] };
+        }
+        if (imageUrl.startsWith("file://")) {
+            const { readFileSync } = await import("node:fs");
+            const filePath = imageUrl.replace(/^file:\/\//, "");
+            const data = readFileSync(filePath).toString("base64");
+            const ext = filePath.split(".").pop()?.toLowerCase() ?? "png";
+            const mimeType = ext === "jpg" || ext === "jpeg" ? "image/jpeg"
+                : ext === "webp" ? "image/webp" : "image/png";
+            return { mimeType, data };
+        }
+        // Fetch from URL
+        const res = await fetch(imageUrl, { signal: AbortSignal.timeout(60_000) });
+        if (!res.ok)
+            throw new Error(`Failed to fetch image ${imageUrl}: ${res.status}`);
+        const buf = Buffer.from(await res.arrayBuffer());
+        const mimeType = res.headers.get("content-type") ?? "image/png";
+        return { mimeType, data: buf.toString("base64") };
+    }
+    /** Extract base64 image data from generateContent response 鈫?persist to cache files. */
+    extractInlineImages(data) {
+        const mediaUrls = [];
+        const cacheDir = join(getUserCacheDir(), "gemini-images");
+        mkdirSync(cacheDir, { recursive: true });
+        for (const candidate of data.candidates ?? []) {
+            for (const part of candidate.content?.parts ?? []) {
+                if (part.inlineData?.data) {
+                    const ext = part.inlineData.mimeType === "image/png" ? "png"
+                        : part.inlineData.mimeType === "image/webp" ? "webp" : "jpg";
+                    const filename = `gemini-${randomUUID()}.${ext}`;
+                    const filePath = join(cacheDir, filename);
+                    writeFileSync(filePath, Buffer.from(part.inlineData.data, "base64"));
+                    mediaUrls.push(`file://${filePath}`);
+                }
+            }
+        }
+        return mediaUrls;
+    }
+    /** Extract base64 audio data from generateContent response 鈫?persist to cache files. */
+    extractInlineAudio(data, subDir) {
+        const mediaUrls = [];
+        const cacheDir = join(getUserCacheDir(), subDir);
+        mkdirSync(cacheDir, { recursive: true });
+        for (const candidate of data.candidates ?? []) {
+            for (const part of candidate.content?.parts ?? []) {
+                if (part.inlineData?.data && part.inlineData.mimeType?.startsWith("audio/")) {
+                    const ext = part.inlineData.mimeType.includes("wav") ? "wav"
+                        : part.inlineData.mimeType.includes("mpeg") || part.inlineData.mimeType.includes("mp3") ? "mp3"
+                            : "pcm";
+                    const rawBuf = Buffer.from(part.inlineData.data, "base64");
+                    // For raw PCM (TTS output), wrap in a WAV header
+                    const audioBuffer = ext === "pcm" ? wrapPcmAsWav(rawBuf, 24000, 1, 16) : rawBuf;
+                    const filename = `gemini-${randomUUID()}.${ext === "pcm" ? "wav" : ext}`;
+                    const filePath = join(cacheDir, filename);
+                    writeFileSync(filePath, audioBuffer);
+                    mediaUrls.push(`file://${filePath}`);
+                }
+            }
+        }
+        return mediaUrls;
+    }
+}
+// 鈹€鈹€ WAV helper 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+/** Wrap raw PCM s16le data in a minimal WAV header. */
+function wrapPcmAsWav(pcm, sampleRate, channels, bitsPerSample) {
+    const byteRate = sampleRate * channels * (bitsPerSample / 8);
+    const blockAlign = channels * (bitsPerSample / 8);
+    const dataSize = pcm.length;
+    const header = Buffer.alloc(44);
+    header.write("RIFF", 0);
+    header.writeUInt32LE(36 + dataSize, 4);
+    header.write("WAVE", 8);
+    header.write("fmt ", 12);
+    header.writeUInt32LE(16, 16); // SubChunk1Size (PCM)
+    header.writeUInt16LE(1, 20); // AudioFormat (PCM)
+    header.writeUInt16LE(channels, 22);
+    header.writeUInt32LE(sampleRate, 24);
+    header.writeUInt32LE(byteRate, 28);
+    header.writeUInt16LE(blockAlign, 30);
+    header.writeUInt16LE(bitsPerSample, 32);
+    header.write("data", 36);
+    header.writeUInt32LE(dataSize, 40);
+    return Buffer.concat([header, pcm]);
+}

package/dist/transports/media-resolve.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Media URL Resolution 鈥?resolves local/private URLs for cloud LLM APIs.
+ *
+ * Cloud LLM APIs (OpenAI, Anthropic, DeepSeek, etc.) cannot fetch content
+ * from localhost or private networks.
+ *
+ * **Primary approach (upload-based):**
+ *   Local URLs are fetched 鈫?uploaded to provider's File API or Aliyun OSS 鈫?public URL returned.
+ *   This is the ONLY approach for images, video, and documents.
+ *
+ * **Audio exception (base64):**
+ *   OpenAI's input_audio.data API field mandates base64 encoding.
+ *   resolveMediaUrl() is retained ONLY for this case.
+ *
+ * URL-first design: the gateway stores media as HTTP URLs; this layer handles
+ * the last-mile transformation before sending to provider APIs.
+ */
+import type { FileUploadAdapter } from "../file-upload-service.js";
+/** Check if a URL points to a local/private address that cloud APIs cannot reach. */
+export declare function isLocalUrl(url: string): boolean;
+export interface MediaResolveContext {
+    /** Provider-specific upload adapter. */
+    uploadAdapter: FileUploadAdapter;
+    /** API key for the upload. */
+    apiKey: string;
+    /** Abort signal. */
+    signal?: AbortSignal;
+}
+/**
+ * Resolve a local URL by uploading to the provider's File API.
+ * This is the **preferred** method for all media types.
+ *
+ * Public URLs pass through unchanged.
+ * Local URLs are uploaded 鈫?public URL or file_id returned.
+ */
+export declare function resolveMediaUrlViaUpload(url: string, ctx: MediaResolveContext): Promise<string>;
+/**
+ * Batch-resolve URLs via upload. Best-effort: failures return original URL.
+ */
+export declare function resolveMediaUrlsViaUpload(urls: string[], ctx: MediaResolveContext): Promise<string[]>;
+/**
+ * Resolve local audio URL to base64 data URL.
+ *
+ * ONLY for audio 鈥?OpenAI's input_audio.data API field mandates base64 encoding.
+ * There is no upload alternative for audio in the OpenAI API.
+ *
+ * For images/video/documents: ALWAYS use resolveMediaUrlViaUpload() instead.
+ * base64 is forbidden for non-audio media per project architecture rules.
+ */
+export declare function resolveMediaUrl(url: string, fallbackMime?: string): Promise<string>;

package/dist/transports/media-resolve.js

@@ -0,0 +1,91 @@
+/**
+ * Media URL Resolution 鈥?resolves local/private URLs for cloud LLM APIs.
+ *
+ * Cloud LLM APIs (OpenAI, Anthropic, DeepSeek, etc.) cannot fetch content
+ * from localhost or private networks.
+ *
+ * **Primary approach (upload-based):**
+ *   Local URLs are fetched 鈫?uploaded to provider's File API or Aliyun OSS 鈫?public URL returned.
+ *   This is the ONLY approach for images, video, and documents.
+ *
+ * **Audio exception (base64):**
+ *   OpenAI's input_audio.data API field mandates base64 encoding.
+ *   resolveMediaUrl() is retained ONLY for this case.
+ *
+ * URL-first design: the gateway stores media as HTTP URLs; this layer handles
+ * the last-mile transformation before sending to provider APIs.
+ */
+import { resolveLocalMedia } from "../file-upload-service.js";
+const LOCAL_URL_RE = /^https?:\/\/(127\.0\.0\.1|localhost|0\.0\.0\.0|\[::1\])(:\d+)?/i;
+/** Check if a URL points to a local/private address that cloud APIs cannot reach. */
+export function isLocalUrl(url) {
+    return LOCAL_URL_RE.test(url);
+}
+/**
+ * Resolve a local URL by uploading to the provider's File API.
+ * This is the **preferred** method for all media types.
+ *
+ * Public URLs pass through unchanged.
+ * Local URLs are uploaded 鈫?public URL or file_id returned.
+ */
+export async function resolveMediaUrlViaUpload(url, ctx) {
+    return resolveLocalMedia(url, ctx.uploadAdapter, ctx.apiKey, ctx.signal);
+}
+/**
+ * Batch-resolve URLs via upload. Best-effort: failures return original URL.
+ */
+export async function resolveMediaUrlsViaUpload(urls, ctx) {
+    return Promise.all(urls.map(async (url) => {
+        try {
+            return await resolveMediaUrlViaUpload(url, ctx);
+        }
+        catch {
+            return url;
+        }
+    }));
+}
+// 鈹€鈹€ Legacy base64 Resolution (fallback only) 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+/** Maximum file size for base64 fallback (20MB). Beyond this, upload is required. */
+const BASE64_MAX_BYTES = 20 * 1024 * 1024;
+/**
+ * Resolve local audio URL to base64 data URL.
+ *
+ * ONLY for audio 鈥?OpenAI's input_audio.data API field mandates base64 encoding.
+ * There is no upload alternative for audio in the OpenAI API.
+ *
+ * For images/video/documents: ALWAYS use resolveMediaUrlViaUpload() instead.
+ * base64 is forbidden for non-audio media per project architecture rules.
+ */
+export async function resolveMediaUrl(url, fallbackMime) {
+    if (url.startsWith("data:"))
+        return url;
+    if (!isLocalUrl(url))
+        return url;
+    const res = await fetch(url);
+    if (!res.ok) {
+        throw new Error(`Failed to fetch local media ${url}: ${res.status}`);
+    }
+    const buffer = Buffer.from(await res.arrayBuffer());
+    if (buffer.byteLength > BASE64_MAX_BYTES) {
+        throw new Error(`Local media too large for base64 (${(buffer.byteLength / 1024 / 1024).toFixed(1)}MB). ` +
+            `Use file upload API instead.`);
+    }
+    const contentType = res.headers.get("content-type") || fallbackMime || guessMimeFromExt(url);
+    return `data:${contentType};base64,${buffer.toString("base64")}`;
+}
+// 鈹€鈹€ Helpers 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+function guessMimeFromExt(url) {
+    const clean = url.split("?")[0].split("#")[0];
+    const ext = clean.slice(clean.lastIndexOf(".")).toLowerCase();
+    const map = {
+        ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg",
+        ".gif": "image/gif", ".webp": "image/webp", ".svg": "image/svg+xml",
+        ".bmp": "image/bmp", ".avif": "image/avif", ".heic": "image/heic",
+        ".mp4": "video/mp4", ".webm": "video/webm", ".mov": "video/quicktime",
+        ".mp3": "audio/mpeg", ".wav": "audio/wav", ".ogg": "audio/ogg",
+        ".aac": "audio/aac", ".flac": "audio/flac", ".m4a": "audio/mp4",
+        ".opus": "audio/opus",
+        ".pdf": "application/pdf",
+    };
+    return map[ext] || "application/octet-stream";
+}

package/dist/transports/minimax-media.d.ts

@@ -0,0 +1,56 @@
+/**
+ * MiniMax Media Transport 鈥?Music + Video + TTS Generation.
+ *
+ * Music: POST /v1/music_generation (sync or async poll)
+ * Video: POST /v1/video_generation (4 modes: text, image, first-last-frame, subject-ref)
+ * Video Query: GET /v1/query/video_generation?task_id=XXX
+ * File Retrieve: GET /v1/files/retrieve?file_id=XXX (get download_url)
+ *
+ * Auth: Authorization: Bearer $MINIMAX_API_KEY
+ * Docs: minimax-ProviderMax.md 搂13-18 (video), 搂21 (music), 搂24-28 (files)
+ */
+import type { AsyncMediaTransport, MediaRequest, MediaResult, MediaType } from "../media-transport.js";
+export interface MiniMaxMediaConfig {
+    /** Base URL, e.g. "https://api.minimaxi.com" */
+    baseUrl: string;
+    timeoutMs?: number;
+}
+export declare class MiniMaxMediaTransport implements AsyncMediaTransport {
+    readonly supportedTypes: readonly MediaType[];
+    private baseUrl;
+    private timeoutMs;
+    constructor(config: MiniMaxMediaConfig);
+    generate(request: MediaRequest, apiKey: string, signal?: AbortSignal): Promise<MediaResult>;
+    private generateTTS;
+    private generateMusic;
+    private pollTask;
+    /**
+     * Generate lyrics from a text prompt via MiniMax Lyrics Generation API.
+     * POST /v1/lyrics_generation 鈥?returns structured lyrics with tags.
+     */
+    generateLyrics(prompt: string, apiKey: string, signal?: AbortSignal): Promise<string>;
+    private generateVideo;
+    private pollVideoTask;
+    private getFileDownloadUrl;
+    /**
+     * Query a single video task by ID.
+     * GET /v1/query/video_generation?task_id=XXX
+     */
+    getTaskStatus(taskId: string, apiKey: string, signal?: AbortSignal): Promise<{
+        status: string;
+        task: Record<string, unknown>;
+    }>;
+    /**
+     * List tasks 鈥?MiniMax does not have a bulk list endpoint.
+     * Each task must be queried individually with getTaskStatus().
+     */
+    listVideoTasks(_apiKey: string, _options?: {
+        after?: string;
+        limit?: number;
+        status?: string;
+    }, _signal?: AbortSignal): Promise<Record<string, unknown>>;
+    /**
+     * Cancel/delete is not natively supported by MiniMax video API.
+     */
+    deleteVideoTask(_taskId: string, _apiKey: string, _signal?: AbortSignal): Promise<void>;
+}