@xiaozhiclaw/provider-core 0.1.0

package/dist/llm-client.js

@@ -0,0 +1,217 @@
+/**
+ * LLM Client factory 鈥?resolves ProviderDef 鈫?creates LLMTransport instance.
+ *
+ * Replaces the old createAdminInferProxyClient() call chain.
+ * User API key + ProviderDef 鈫?direct provider connection.
+ */
+import { OpenAIChatTransport } from "./transports/openai-chat.js";
+import { OpenAIResponsesTransport } from "./transports/openai-responses.js";
+import { AnthropicMessagesTransport } from "./transports/anthropic-messages.js";
+import { VolcengineResponsesTransport } from "./transports/volcengine-responses.js";
+import { GeminiGenerateContentTransport } from "./transports/gemini-generatecontent.js";
+import { OpenAIFileUploadAdapter } from "./adapters/openai-file-upload-adapter.js";
+import { VolcengineFileUploadAdapter } from "./adapters/volcengine-file-upload-adapter.js";
+import { GeminiFileUploadAdapter } from "./adapters/gemini-file-upload-adapter.js";
+import { HubOSSFileUploadAdapter } from "./adapters/hub-oss-file-upload-adapter.js";
+import { createAliyunOSSAdapterFromEnv } from "./adapters/aliyun-oss-file-upload-adapter.js";
+/**
+ * Create an LLM client from config + registry.
+ *
+ * 1. Look up provider in registry
+ * 2. Apply baseUrl override if provided
+ * 3. Instantiate the correct transport
+ */
+export function createLLMClient(config, registry) {
+    const providerDef = registry.getProvider(config.provider);
+    if (!providerDef) {
+        throw new Error(`Unknown LLM provider: "${config.provider}". ` +
+            `Available: ${registry.listProviders().map((p) => p.id).join(", ")}`);
+    }
+    // Hermes parity: empty string must fall back to provider default (Python truthiness)
+    let baseUrl = config.baseUrl || providerDef.baseUrl;
+    const builtinBaseUrl = registry.getBuiltinProvider(config.provider)?.baseUrl;
+    // Normalize: Users often copy just the domain (e.g., "https://api.deepseek.com") from docs,
+    // but non-native providers using anthropic-messages transport need a path suffix (e.g., "/anthropic").
+    // If the user's URL has no path but the builtin does, re-append the original path suffix.
+    if (config.baseUrl && builtinBaseUrl) {
+        try {
+            const userUrl = new URL(config.baseUrl);
+            const builtinUrl = new URL(builtinBaseUrl);
+            if ((userUrl.pathname === "/" || userUrl.pathname === "") &&
+                builtinUrl.pathname !== "/" &&
+                builtinUrl.pathname !== "") {
+                baseUrl = new URL(builtinUrl.pathname, config.baseUrl).toString().replace(/\/$/, "");
+            }
+        }
+        catch {
+            // Invalid URL 鈥?use as-is
+        }
+    }
+    const effectiveProviderDef = config.baseUrl ? { ...providerDef, baseUrl } : providerDef;
+    const transport = createTransport(effectiveProviderDef, baseUrl);
+    return {
+        transport,
+        apiKey: config.apiKey,
+        resolvedModel: config.model,
+        providerDef: effectiveProviderDef,
+    };
+}
+/**
+ * Auto-detect provider from API key environment variables.
+ * Scans registry for providers whose env vars are set.
+ * Returns the first match.
+ */
+export function autoDetectProvider(registry) {
+    for (const provider of registry.listProviders()) {
+        const key = registry.resolveApiKey(provider.id);
+        if (key) {
+            return {
+                providerId: provider.id,
+                apiKey: key,
+                defaultModel: provider.defaultModel ?? provider.models?.[0]?.id ?? "",
+            };
+        }
+    }
+    return undefined;
+}
+function createFileUploadAdapter(transport, baseUrl, providerDef) {
+    switch (transport) {
+        case "openai-chat":
+        case "openai-responses":
+            return new OpenAIFileUploadAdapter({
+                baseUrl,
+                provider: providerDef.id,
+                extraHeaders: providerDef.extraHeaders,
+            });
+        case "volcengine-responses":
+            return new VolcengineFileUploadAdapter({ baseUrl });
+        case "gemini-generatecontent":
+            return new GeminiFileUploadAdapter({ baseUrl });
+        case "anthropic-messages":
+        default:
+            // Providers without native File Upload API use cloud OSS.
+            // Priority: Hub OSS relay 鈫?direct Aliyun OSS 鈫?undefined (will error at call site)
+            return getUniversalOSSAdapter();
+    }
+}
+/**
+ * Universal OSS fallback for providers without native File Upload API.
+ * Priority: Hub OSS relay (if configured) 鈫?direct Aliyun OSS (if credentials present).
+ * Cached after first resolution.
+ */
+let _cachedOSSAdapter = null;
+function getUniversalOSSAdapter() {
+    if (_cachedOSSAdapter !== null)
+        return _cachedOSSAdapter || undefined;
+    // Option 1: Hub OSS relay
+    const hubBaseUrl = (process.env.QLOGICAGENT_HUB_URL ?? process.env.HUB_BASE_URL ?? "").trim();
+    if (hubBaseUrl) {
+        _cachedOSSAdapter = new HubOSSFileUploadAdapter({
+            hubBaseUrl,
+            hubApiKey: (process.env.QLOGICAGENT_HUB_API_KEY ?? process.env.HUB_API_KEY ?? "").trim() || undefined,
+        });
+        return _cachedOSSAdapter;
+    }
+    // Option 2: Direct Aliyun OSS
+    const ossAdapter = createAliyunOSSAdapterFromEnv();
+    if (ossAdapter) {
+        _cachedOSSAdapter = ossAdapter;
+        return _cachedOSSAdapter;
+    }
+    // Neither configured 鈥?return undefined (transport will throw on local URL instead of base64 fallback)
+    _cachedOSSAdapter = undefined;
+    return undefined;
+}
+function createTransport(providerDef, baseUrl) {
+    let primary;
+    const fileUploadAdapter = createFileUploadAdapter(providerDef.transport, baseUrl, providerDef);
+    switch (providerDef.transport) {
+        case "openai-chat":
+            primary = new OpenAIChatTransport({
+                baseUrl,
+                extraHeaders: providerDef.extraHeaders,
+                supportsStreamOptions: providerDef.supportsStreamOptions,
+                omitZeroTemperature: providerDef.omitZeroTemperature,
+                quirks: providerDef.quirks,
+                fileUploadAdapter,
+            });
+            break;
+        case "openai-responses":
+            primary = new OpenAIResponsesTransport({
+                baseUrl,
+                extraHeaders: providerDef.extraHeaders,
+                quirks: providerDef.quirks,
+                fileUploadAdapter,
+            });
+            break;
+        case "anthropic-messages":
+            primary = new AnthropicMessagesTransport({
+                baseUrl,
+                omitZeroTemperature: providerDef.omitZeroTemperature,
+                quirks: providerDef.quirks,
+                fileUploadAdapter,
+            });
+            break;
+        case "volcengine-responses":
+            primary = new VolcengineResponsesTransport({
+                baseUrl,
+                extraHeaders: providerDef.extraHeaders,
+                quirks: providerDef.quirks,
+                fileUploadAdapter,
+            });
+            break;
+        case "gemini-generatecontent":
+            primary = new GeminiGenerateContentTransport({
+                baseUrl,
+                quirks: providerDef.quirks,
+                fileUploadAdapter,
+            });
+            break;
+        default:
+            throw new Error(`Unsupported transport type: "${providerDef.transport}" for provider "${providerDef.id}"`);
+    }
+    // Dual-transport: providers using Anthropic Messages as primary transport but
+    // supporting prefix completion via OpenAI /beta endpoint (e.g. DeepSeek).
+    // Route prefix requests to an OpenAI-chat transport; everything else to Anthropic.
+    if (providerDef.transport === "anthropic-messages" &&
+        providerDef.quirks?.supportsPrefixCompletion) {
+        // Derive OpenAI base URL: strip /anthropic suffix to get the standard base.
+        // e.g. "https://api.deepseek.com/anthropic" 鈫?"https://api.deepseek.com"
+        const openaiBaseUrl = baseUrl.replace(/\/anthropic\/?$/, "");
+        const prefixTransport = new OpenAIChatTransport({
+            baseUrl: openaiBaseUrl,
+            quirks: providerDef.quirks,
+        });
+        return new PrefixRoutingTransport(primary, prefixTransport);
+    }
+    return primary;
+}
+/**
+ * Composite transport: routes prefix-completion requests to an OpenAI-chat
+ * transport (DeepSeek /beta endpoint) while keeping the primary Anthropic
+ * transport for all other requests.
+ */
+class PrefixRoutingTransport {
+    primary;
+    prefixTransport;
+    constructor(primary, prefixTransport) {
+        this.primary = primary;
+        this.prefixTransport = prefixTransport;
+    }
+    async *stream(request, apiKey, signal) {
+        const transport = request.prefixMessage
+            ? this.prefixTransport
+            : this.primary;
+        yield* transport.stream(request, apiKey, signal);
+    }
+    // Delegate FIM completion to the prefix transport (OpenAI-chat)
+    // which has the DeepSeek /beta endpoint.
+    async *complete(request, apiKey, signal) {
+        if (this.prefixTransport.complete) {
+            yield* this.prefixTransport.complete(request, apiKey, signal);
+        }
+        else {
+            throw new Error("FIM completion is not supported by this transport");
+        }
+    }
+}

package/dist/media-client.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Media Client factory 鈥?resolves ProviderDef 鈫?creates MediaTransport instances.
+ *
+ * Parallel to createLLMClient() but for generation models (image/video/music/3D).
+ * Uses the same ProviderRegistry to look up provider config, then instantiates
+ * the correct media transport adapter.
+ *
+ * The MediaClient holds a provider-keyed transport cache so that repeated
+ * generation calls reuse the same adapter instance.
+ */
+import type { MediaTransport } from "./media-transport.js";
+import type { ProviderDef, MediaCapability, ModelInfo } from "./provider-def.js";
+import type { ProviderRegistry } from "./provider-registry.js";
+export interface MediaClientConfig {
+    registry: ProviderRegistry;
+}
+export interface ResolvedMediaModel {
+    providerId: string;
+    providerDef: ProviderDef;
+    modelInfo: ModelInfo;
+    mediaType: MediaCapability;
+}
+export declare class MediaClient {
+    private registry;
+    private transports;
+    constructor(config: MediaClientConfig);
+    /**
+     * Find a specific model by provider + model id for a given media type.
+     * Used by the user-designated model routing (no failover).
+     */
+    resolveModelById(providerId: string, modelId: string, mediaType: MediaCapability): ResolvedMediaModel | undefined;
+    /**
+     * Get a MediaTransport for a specific provider.
+     * Creates and caches the adapter on first access.
+     */
+    getTransport(providerId: string): MediaTransport | undefined;
+    /**
+     * List all available generation models across all providers.
+     */
+    listMediaModels(mediaType?: MediaCapability): ResolvedMediaModel[];
+    private findModelInProvider;
+}

package/dist/media-client.js

@@ -0,0 +1,174 @@
+/**
+ * Media Client factory 鈥?resolves ProviderDef 鈫?creates MediaTransport instances.
+ *
+ * Parallel to createLLMClient() but for generation models (image/video/music/3D).
+ * Uses the same ProviderRegistry to look up provider config, then instantiates
+ * the correct media transport adapter.
+ *
+ * The MediaClient holds a provider-keyed transport cache so that repeated
+ * generation calls reuse the same adapter instance.
+ */
+import { VolcengineMediaTransport } from "./transports/volcengine-media.js";
+import { OpenAIMediaTransport } from "./transports/openai-media.js";
+import { MiniMaxMediaTransport } from "./transports/minimax-media.js";
+import { GeminiMediaTransport } from "./transports/gemini-media.js";
+import { QwenMediaTransport } from "./transports/qwen-media.js";
+import { ZhipuMediaTransport } from "./transports/zhipu-media.js";
+// 鈹€鈹€ MediaClient 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+export class MediaClient {
+    registry;
+    transports = new Map();
+    constructor(config) {
+        this.registry = config.registry;
+    }
+    /**
+     * Find a specific model by provider + model id for a given media type.
+     * Used by the user-designated model routing (no failover).
+     */
+    resolveModelById(providerId, modelId, mediaType) {
+        const providerDef = this.registry.getProvider(providerId);
+        if (!providerDef)
+            return undefined;
+        const models = this.registry.listModels(providerId);
+        const model = models.find(m => m.id === modelId && m.mediaType === mediaType);
+        if (!model)
+            return undefined;
+        return { providerId, providerDef, modelInfo: model, mediaType };
+    }
+    /**
+     * Get a MediaTransport for a specific provider.
+     * Creates and caches the adapter on first access.
+     */
+    getTransport(providerId) {
+        const cached = this.transports.get(providerId);
+        if (cached)
+            return cached;
+        const providerDef = this.registry.getProvider(providerId);
+        if (!providerDef)
+            return undefined;
+        const transport = createMediaTransport(providerDef);
+        if (!transport)
+            return undefined;
+        this.transports.set(providerId, transport);
+        return transport;
+    }
+    /**
+     * List all available generation models across all providers.
+     */
+    listMediaModels(mediaType) {
+        const results = [];
+        for (const provider of this.registry.listProviders()) {
+            const models = this.registry.listModels(provider.id);
+            for (const model of models) {
+                if (model.mediaType && (!mediaType || model.mediaType === mediaType)) {
+                    results.push({
+                        providerId: provider.id,
+                        providerDef: provider,
+                        modelInfo: model,
+                        mediaType: model.mediaType,
+                    });
+                }
+            }
+        }
+        return results;
+    }
+    // 鈹€鈹€ Internal 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+    findModelInProvider(providerId, mediaType, request) {
+        const providerDef = this.registry.getProvider(providerId);
+        if (!providerDef)
+            return undefined;
+        const models = this.registry.listModels(providerId);
+        const requiredOp = request ? inferRequiredOperation(request) : undefined;
+        const model = models.find(m => {
+            if (m.mediaType !== mediaType)
+                return false;
+            // If no specific operation required, any model of this type matches
+            if (!requiredOp)
+                return true;
+            // If model has no capability metadata, assume it supports everything (backward compat)
+            if (!m.mediaCapabilities)
+                return true;
+            // Check if the model declares support for the required operation
+            return modelSupportsOperation(m.mediaCapabilities, requiredOp);
+        });
+        if (!model)
+            return undefined;
+        return { providerId, providerDef, modelInfo: model, mediaType };
+    }
+}
+// 鈹€鈹€ Capability matching helpers 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+/**
+ * Infer the required operation from a MediaRequest.
+ * Maps request fields to the specific operation the model must support.
+ */
+function inferRequiredOperation(request) {
+    switch (request.mediaType) {
+        case "video":
+            if (request.operation === "merge")
+                return "merge";
+            if (request.operation === "upscale")
+                return "upscale";
+            if (request.operation === "edit")
+                return "edit";
+            return request.imageUrl ? "img2video" : "text2video";
+        case "image":
+            if (request.operation === "edit")
+                return "inpainting";
+            return request.imageUrl ? "img2img" : "text2image";
+        case "music":
+            return request.audioUrl ? "cover" : "text2music";
+        case "music_realtime":
+            return "realtime";
+        case "tts":
+            return "text2speech";
+        case "3d":
+            return request.imageUrl ? "img2_3d" : "text2_3d";
+        default:
+            return undefined;
+    }
+}
+/**
+ * Check if a model's declared capabilities include the required operation.
+ */
+function modelSupportsOperation(caps, requiredOp) {
+    if (!("operations" in caps) || !caps.operations)
+        return true;
+    return caps.operations.includes(requiredOp);
+}
+// 鈹€鈹€ Transport factory 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+/**
+ * Provider 鈫?MediaTransport mapping.
+ * Each provider that has generation models gets a dedicated transport.
+ */
+function createMediaTransport(providerDef) {
+    // Remove trailing /anthropic path for providers that use it for chat
+    const rawUrl = providerDef.baseUrl;
+    switch (providerDef.id) {
+        case "volcengine":
+            return new VolcengineMediaTransport({ baseUrl: rawUrl });
+        case "openai":
+            return new OpenAIMediaTransport({ baseUrl: rawUrl });
+        case "minimax":
+            return new MiniMaxMediaTransport({ baseUrl: rawUrl });
+        case "google":
+            return new GeminiMediaTransport({ baseUrl: rawUrl });
+        case "qwen":
+            return new QwenMediaTransport({ baseUrl: rawUrl });
+        case "zhipu":
+            // Media models use the OpenAI-compat /paas/v4 endpoint, not the Anthropic endpoint.
+            // The zhipu provider's baseUrl is /api/anthropic 鈥?derive the media base.
+            return new ZhipuMediaTransport({
+                baseUrl: rawUrl.replace(/\/api\/anthropic\/?$/, "/api/paas/v4"),
+            });
+        case "zhipu-openai":
+        case "zhipu-coding":
+            // These providers already use /api/paas/v4 or /api/coding/paas/v4 base URL.
+            // Media endpoints are on /api/paas/v4 regardless.
+            return new ZhipuMediaTransport({
+                baseUrl: rawUrl.replace(/\/api\/coding\/paas\/v4\/?$/, "/api/paas/v4"),
+            });
+        default:
+            // Provider doesn't support media generation
+            return undefined;
+    }
+}

package/dist/media-transport.d.ts

@@ -0,0 +1,176 @@
+/**
+ * MediaTransport 鈥?transport interface for generation APIs (image, video, music, 3D).
+ *
+ * Parallel to LLMTransport (chat/reasoning), MediaTransport handles
+ * non-chat generation endpoints that each vendor exposes differently:
+ *   - Sync (OpenAI images, Volcengine Seedream, Gemini generateContent)
+ *   - Async job (Volcengine Seedance/3D, MiniMax music) 鈥?submit 鈫?poll 鈫?result
+ *
+ * Each provider adapter implements this interface and hides vendor-specific
+ * auth, endpoint paths, request shapes, and polling logic.
+ */
+export type MediaType = "image" | "video" | "music" | "music_realtime" | "tts" | "3d" | "stt" | "embedding" | "video_understanding" | "image_understanding" | "voice_clone" | "rerank" | "document_parsing" | "realtime_audio" | "realtime_video";
+export interface MediaRequest {
+    /** Generation model id, e.g. "doubao-seedream-5-0-260128", "gpt-image-2" */
+    model: string;
+    /** What kind of media to generate */
+    mediaType: MediaType;
+    /** Text prompt for generation */
+    prompt: string;
+    /** Optional reference image URL (img2img, i2v, img-to-3d) */
+    imageUrl?: string;
+    /** Desired dimensions, e.g. "1024x1024" */
+    size?: string;
+    /** Aspect ratio for video, e.g. "16:9" */
+    aspectRatio?: string;
+    /** Duration in seconds (video, music) */
+    duration?: number;
+    /** Number of outputs (image) */
+    n?: number;
+    /** Visual/musical style */
+    style?: string;
+    /** Intended use / purpose */
+    purpose?: string;
+    /** Lyrics for music generation */
+    lyrics?: string;
+    /** Text for TTS */
+    text?: string;
+    /** TTS channel hint */
+    channel?: string;
+    /** Source video URLs for edit/merge operations */
+    sourceVideos?: string[];
+    /** Reference images (no role / first_frame / last_frame) */
+    referenceImages?: string[];
+    /** Reference image roles 鈥?parallel array with referenceImages. */
+    imageRoles?: Array<"first_frame" | "last_frame" | "reference_image">;
+    /** Reference video URLs for multimodal reference generation (Seedance 2.0) */
+    referenceVideos?: string[];
+    /** Reference audio URLs for multimodal reference generation (Seedance 2.0) */
+    referenceAudios?: string[];
+    /** Generate synchronized audio track (Seedance 2.0 / 1.5 pro) */
+    generateAudio?: boolean;
+    /** Output resolution for upscale, e.g. "1080p" */
+    resolution?: string;
+    /** Operation variant: generate (default), edit, merge, upscale, multimodal_reference, extend */
+    operation?: "generate" | "edit" | "merge" | "upscale" | "multimodal_reference" | "extend";
+    /** Image/video quality, e.g. "auto", "high", "low", "hd" */
+    quality?: string;
+    /** Seed for reproducible generation */
+    seed?: number;
+    /** TTS voice, e.g. "alloy", "nova", "shimmer" */
+    voice?: string;
+    /** TTS speech speed multiplier */
+    speed?: number;
+    /** Pure instrumental mode (MiniMax music) */
+    isInstrumental?: boolean;
+    /** Source audio URL for cover/remix (MiniMax music) */
+    audioUrl?: string;
+    /** Output audio format, e.g. "mp3", "wav", "flac" */
+    audioFormat?: string;
+    /** Video frames per second */
+    fps?: number;
+    /** Whether to add AI watermark */
+    watermark?: boolean;
+    /** img2img guidance/control strength (0-1), e.g. Volcengine */
+    guidanceScale?: number;
+    /** Auto-generate lyrics when none provided (MiniMax) */
+    lyricsOptimizer?: boolean;
+    /** 3D output format, e.g. "glb", "obj", "usd", "usdz" */
+    outputFormat?: string;
+    /** Image background mode (OpenAI gpt-image-2): "transparent", "opaque", "auto" */
+    background?: string;
+    /** Provider-specific request metadata (e.g. rerank documents, parsing options) */
+    metadata?: Record<string, unknown>;
+    /** Ask the provider to optimize/enhance the prompt before generation */
+    enhancePrompt?: boolean;
+    /**
+     * Progress callback for async polling operations (video gen, 3D gen, etc.).
+     * Called periodically with estimated progress percentage, status text, and
+     * the provider-specific task ID (available once the task is submitted).
+     */
+    onProgress?: (percent: number, status: string, taskId?: string) => void;
+    /** Enable progressive/streaming image generation (Volcengine Seedream stream:true) */
+    streamImage?: boolean;
+    /** Lock camera position (Seedance 1.0/1.5, not Seedance 2.0) */
+    cameraFixed?: boolean;
+    /** Return last frame URL for chaining continuous video segments */
+    returnLastFrame?: boolean;
+    /** Service tier: 'default' (online) or 'flex' (offline, ~50% cost) 鈥?not all models support flex */
+    serviceTier?: "default" | "flex";
+    /** Task expiration in seconds (for flex/offline scheduling) */
+    executionExpiresAfterSeconds?: number;
+    /** Draft mode 鈥?low-cost preview (Seedance 1.5 pro only) */
+    draft?: boolean;
+    /** Draft task ID to promote to final video */
+    draftTaskId?: string;
+    /** Video-level builtin tools, e.g. ["web_search"] (Seedance 2.0) */
+    videoTools?: string[];
+    /** End-user safety identifier for content moderation */
+    safetyIdentifier?: string;
+    /** Callback URL for async task status push notifications */
+    callbackUrl?: string;
+    /** Image detail level control: 'auto' | 'low' | 'high' */
+    detail?: "auto" | "low" | "high";
+    /** Max image pixels budget (Volcengine image_pixel_limit) */
+    imagePixelLimit?: number;
+}
+export interface MediaResult {
+    /** URLs of generated media files */
+    mediaUrls: string[];
+    /** Model actually used */
+    model?: string;
+    /** Output dimensions / format info */
+    size?: string;
+    /** Total generation time in ms */
+    durationMs?: number;
+    /** Billing unit type for non-token models */
+    billingUnit?: "per_call" | "per_second" | "per_character" | "per_pixel" | "per_token";
+    /** Quantity consumed (seconds, characters, pixels, etc.) */
+    billingQuantity?: number;
+    /** Provider-specific metadata */
+    metadata?: Record<string, unknown>;
+    /** Last frame image URL for chaining continuous video generation */
+    lastFrameUrl?: string;
+    /** Task ID (for continuing draft鈫抐inal or querying) */
+    taskId?: string;
+}
+export interface MediaTransport {
+    /**
+     * Generate media content.
+     * Handles sync APIs directly and async job APIs (submit + poll) internally.
+     *
+     * @param request - Generation parameters
+     * @param apiKey  - User API key (passed explicitly, not from env)
+     * @param signal  - Optional abort signal
+     */
+    generate(request: MediaRequest, apiKey: string, signal?: AbortSignal): Promise<MediaResult>;
+    /**
+     * Which media types this transport supports.
+     * Used by the media client factory to route requests.
+     */
+    readonly supportedTypes: readonly MediaType[];
+}
+/**
+ * Extended transport for providers that support async task management
+ * (submit 鈫?poll 鈫?cancel/query). Volcengine Seedance, MiniMax async, etc.
+ */
+export interface AsyncMediaTransport extends MediaTransport {
+    /** Cancel / delete an async task. */
+    deleteVideoTask(taskId: string, apiKey: string, signal?: AbortSignal): Promise<void>;
+    /** List recent tasks for status queries. */
+    listVideoTasks(apiKey: string, options?: {
+        after?: string;
+        limit?: number;
+        status?: string;
+    }, signal?: AbortSignal): Promise<Record<string, unknown>>;
+    /**
+     * Query a single task by ID 鈥?preferred over listVideoTasks for direct lookups.
+     * Not all providers support listing; all async providers support single-task queries.
+     */
+    getTaskStatus?(taskId: string, apiKey: string, signal?: AbortSignal): Promise<{
+        status: string;
+        task: Record<string, unknown>;
+    }>;
+}
+/** Type guard for transports that support async task management. */
+export declare function isAsyncMediaTransport(t: MediaTransport): t is AsyncMediaTransport;

package/dist/media-transport.js

@@ -0,0 +1,16 @@
+/**
+ * MediaTransport 鈥?transport interface for generation APIs (image, video, music, 3D).
+ *
+ * Parallel to LLMTransport (chat/reasoning), MediaTransport handles
+ * non-chat generation endpoints that each vendor exposes differently:
+ *   - Sync (OpenAI images, Volcengine Seedream, Gemini generateContent)
+ *   - Async job (Volcengine Seedance/3D, MiniMax music) 鈥?submit 鈫?poll 鈫?result
+ *
+ * Each provider adapter implements this interface and hides vendor-specific
+ * auth, endpoint paths, request shapes, and polling logic.
+ */
+/** Type guard for transports that support async task management. */
+export function isAsyncMediaTransport(t) {
+    return typeof t.deleteVideoTask === "function"
+        && typeof t.listVideoTasks === "function";
+}

package/dist/media.d.ts

@@ -0,0 +1,2 @@
+export type { MediaTransport, MediaRequest, MediaResult, MediaType } from "./media-transport.js";
+export { isAsyncMediaTransport } from "./media-transport.js";

package/dist/media.js

@@ -0,0 +1 @@
+export { isAsyncMediaTransport } from "./media-transport.js";

package/dist/model-detection.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Model detection helpers shared between OpenAI transport implementations.
+ *
+ * These are used by both openai-chat.ts and openai-responses.ts to detect
+ * model families and apply family-specific constraints:
+ *   - GPT-5.x: unified reasoning, temperature allowed, reasoning object format
+ *   - GPT-5.4-nano: reasoning effort capped at medium
+ *   - o-series (legacy): reasoning_effort flat string, temperature suppressed
+ */
+/** GPT-5.x models (new generation with unified reasoning). */
+export declare function isGPT5xModel(model: string): boolean;
+/**
+ * GPT-5.4-nano models 鈥?reasoning effort capped at medium.
+ * openai-ProviderMax 搂3: gpt-5.4-nano only supports none/low/medium effort.
+ */
+export declare function isGPT5NanoModel(model: string): boolean;
+/**
+ * OpenAI o-series reasoning models (legacy, kept for 3rd-party provider compat).
+ * These suppress temperature/top_p and use reasoning_effort as flat string.
+ * Matches: o1, o1-mini, o1-pro, o3, o3-mini, o3-pro, o4-mini, etc.
+ */
+export declare function isOpenAIReasoningModel(model: string): boolean;