@xiaozhiclaw/provider-core 0.1.0

package/dist/transports/volcengine-media.js

@@ -0,0 +1,801 @@
+/**
+ * Volcengine Media Transport 鈥?Doubao Seedream (image), Seedance (video), 3D generation.
+ *
+ * API reference:
+ *   Image:  POST /v3/images/generations            (sync)
+ *   Video:  POST /v3/contents/generations/tasks     (async job)
+ *   3D:     POST /v3/contents/generations/tasks     (async job, same endpoint as video)
+ *
+ * Auth: Authorization: Bearer $ARK_API_KEY
+ * Docs: https://www.volcengine.com/docs/82379/1330310
+ *       https://www.volcengine.com/docs/82379/1874993 (3D)
+ */
+const DEFAULT_TIMEOUT_MS = 180_000;
+const POLL_INTERVAL_MS = 3_000;
+const MAX_POLL_MS = 600_000; // 10 min max for video/3D
+export class VolcengineMediaTransport {
+    supportedTypes = ["image", "video", "3d", "embedding"];
+    baseUrl;
+    timeoutMs;
+    constructor(config) {
+        this.baseUrl = config.baseUrl.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 "3d":
+                return this.generate3D(request, apiKey, signal);
+            case "embedding":
+                return this.generateEmbedding(request, apiKey, signal);
+            default:
+                throw new Error(`VolcengineMediaTransport: unsupported mediaType "${request.mediaType}"`);
+        }
+    }
+    async generateEmbedding(request, apiKey, signal) {
+        const start = Date.now();
+        const text = request.text || request.prompt;
+        if (!text)
+            throw new Error("VolcengineMediaTransport: text or prompt is required for embedding");
+        const url = `${this.baseUrl}/embeddings/multimodal`;
+        const body = {
+            model: request.model || "doubao-embedding-vision-251215",
+            input: [{ type: "text", text }],
+        };
+        const res = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify(body),
+            signal: signal ?? AbortSignal.timeout(this.timeoutMs),
+        });
+        if (!res.ok) {
+            const errText = await res.text().catch(() => "");
+            throw new Error(`Volcengine embedding error ${res.status}: ${errText}`);
+        }
+        const data = await res.json();
+        const dataItems = Array.isArray(data.data)
+            ? data.data
+            : data.data
+                ? [data.data]
+                : [];
+        const embeddings = dataItems.map(item => item.embedding).filter((item) => Array.isArray(item));
+        const totalTokens = data.usage?.total_tokens ?? data.usage?.prompt_tokens;
+        return {
+            mediaUrls: [],
+            model: data.model ?? request.model ?? "doubao-embedding-vision-251215",
+            durationMs: Date.now() - start,
+            billingUnit: totalTokens !== undefined ? "per_token" : undefined,
+            billingQuantity: totalTokens,
+            metadata: {
+                embeddings,
+                dimensions: embeddings[0]?.length ?? 0,
+                usage: data.usage,
+            },
+        };
+    }
+    /**
+     * Check if this transport can handle a given operation.
+     * Video edit/merge/upscale are routed through the same video endpoint.
+     */
+    canHandle(request) {
+        if (this.supportedTypes.includes(request.mediaType))
+            return true;
+        return false;
+    }
+    // 鈹€鈹€ Image (Seedream) 鈥?sync 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+    async generateImage(request, apiKey, signal) {
+        const start = Date.now();
+        const url = `${this.baseUrl}/v3/images/generations`;
+        const body = {
+            model: request.model,
+            prompt: request.prompt,
+            size: request.size ?? "2K",
+            n: request.n ?? 1,
+            response_format: "url",
+            sequential_image_generation: "disabled",
+            watermark: true,
+        };
+        if (request.imageUrl)
+            body.image = request.imageUrl;
+        // Multi-reference images for consistency generation (Seedream 5.0)
+        if (request.referenceImages && request.referenceImages.length > 0) {
+            body.image_urls = request.referenceImages;
+        }
+        if (request.style)
+            body.style = request.style;
+        if (request.quality)
+            body.quality = request.quality;
+        if (request.seed !== undefined)
+            body.seed = request.seed;
+        // guidance_scale is only supported by seedream 3.0, not 4.5/5.0
+        if (request.guidanceScale !== undefined)
+            body.guidance_scale = request.guidanceScale;
+        if (request.enhancePrompt !== undefined)
+            body.enhance_prompt = request.enhancePrompt;
+        // T13: Progressive/streaming image generation 鈥?returns low-quality preview
+        // images first, then upgrades to full quality (Seedream stream mode)
+        if (request.streamImage)
+            body.stream = true;
+        const res = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify(body),
+            signal: signal ?? AbortSignal.timeout(this.timeoutMs),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`Volcengine image API error ${res.status}: ${text}`);
+        }
+        // Streaming mode: SSE response with progressive image updates
+        if (request.streamImage && res.body) {
+            return this.parseStreamingImage(res.body, request, start);
+        }
+        const data = await res.json();
+        const mediaUrls = (data.data ?? [])
+            .map(d => d.url)
+            .filter((u) => !!u);
+        return {
+            mediaUrls,
+            model: request.model,
+            size: request.size ?? "1024x1024",
+            durationMs: Date.now() - start,
+            billingUnit: "per_call",
+            billingQuantity: request.n ?? Math.max(mediaUrls.length, 1),
+            metadata: {
+                billableUnits: {
+                    images: request.n ?? Math.max(mediaUrls.length, 1),
+                },
+                pricingSpec: request.size ?? "1024x1024",
+            },
+        };
+    }
+    /**
+     * Parse streaming image SSE 鈥?yields progressive image quality upgrades.
+     * Final event contains the full-quality image URL.
+     */
+    async parseStreamingImage(body, request, startTime) {
+        const decoder = new TextDecoder();
+        let buffer = "";
+        let lastUrl = "";
+        const reader = body.getReader();
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                let newlineIdx;
+                while ((newlineIdx = buffer.indexOf("\n")) !== -1) {
+                    const line = buffer.slice(0, newlineIdx).trim();
+                    buffer = buffer.slice(newlineIdx + 1);
+                    if (!line || line.startsWith(":") || !line.startsWith("data:"))
+                        continue;
+                    const dataStr = line.slice(5).trim();
+                    if (dataStr === "[DONE]")
+                        break;
+                    try {
+                        const parsed = JSON.parse(dataStr);
+                        const url = parsed.data?.[0]?.url;
+                        if (url) {
+                            lastUrl = url;
+                            request.onProgress?.(50, "streaming");
+                        }
+                    }
+                    catch { /* ignore parse errors */ }
+                }
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+        request.onProgress?.(100, "completed");
+        return {
+            mediaUrls: lastUrl ? [lastUrl] : [],
+            model: request.model,
+            size: request.size ?? "1024x1024",
+            durationMs: Date.now() - startTime,
+            billingUnit: "per_call",
+            billingQuantity: 1,
+            metadata: {
+                billableUnits: { images: 1 },
+                pricingSpec: request.size ?? "1024x1024",
+            },
+        };
+    }
+    // 鈹€鈹€ Video (Seedance) 鈥?async job 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+    async generateVideo(request, apiKey, signal) {
+        const start = Date.now();
+        const url = `${this.baseUrl}/v3/contents/generations/tasks`;
+        // 鈹€鈹€ Input validation (volcengine-ProviderMax 搂22.6-22.7) 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+        const refVideoCount = request.referenceVideos?.length ?? 0;
+        const refAudioCount = request.referenceAudios?.length ?? 0;
+        const refImageCount = request.referenceImages?.length ?? 0;
+        const hasImage = !!(request.imageUrl || refImageCount > 0);
+        // Reference video limit: max 3, total duration 鈮?5s (duration enforced server-side)
+        if (refVideoCount > 3) {
+            throw new Error(`Seedance 2.0: max 3 reference videos (got ${refVideoCount}). Total duration must be 鈮?5s.`);
+        }
+        // Reference audio limit: max 3, total duration 鈮?5s
+        if (refAudioCount > 3) {
+            throw new Error(`Seedance 2.0: max 3 reference audios (got ${refAudioCount}). Total duration must be 鈮?5s.`);
+        }
+        // Audio cannot be used alone 鈥?must have at least one image or video
+        if (refAudioCount > 0 && !hasImage && refVideoCount === 0) {
+            throw new Error(`Seedance 2.0: reference audio cannot be used alone. Provide at least one reference image or video.`);
+        }
+        // Reference images limit for video editing: max 9
+        if (request.operation === "edit" && refImageCount > 9) {
+            throw new Error(`Seedance 2.0 video edit: max 9 reference images (got ${refImageCount}).`);
+        }
+        const content = [];
+        // Draft task promotion: use draft task ID as input (搂22.13)
+        if (request.draftTaskId) {
+            content.push({ type: "draft_task", id: request.draftTaskId });
+        }
+        // Explicit operation routing (Volcengine Seedance API distinctions):
+        //   text2video: text only
+        //   img2video:  image (first frame) + optional text
+        //   multimodal_reference: reference_image + reference_video + reference_audio + text (Seedance 2.0)
+        //   extend: multiple reference_video + text
+        //   edit: video_url + text
+        //   merge: multiple video_urls + text
+        //   upscale: video_url + resolution
+        switch (request.operation) {
+            case "multimodal_reference": {
+                // Seedance 2.0: multimodal reference generation
+                // Per volcengine-ProviderMax.md 搂22.6-22.7:
+                //   reference_image, reference_video, reference_audio roles
+                //   Audio cannot be sent alone 鈥?requires at least one image or video
+                if (request.prompt)
+                    content.push({ type: "text", text: request.prompt });
+                // Reference images with role
+                if (request.referenceImages?.length) {
+                    for (let i = 0; i < request.referenceImages.length; i++) {
+                        const role = request.imageRoles?.[i] ?? "reference_image";
+                        content.push({
+                            type: "image_url",
+                            image_url: { url: request.referenceImages[i] },
+                            role,
+                        });
+                    }
+                }
+                // Reference videos
+                if (request.referenceVideos?.length) {
+                    for (const videoUrl of request.referenceVideos) {
+                        content.push({
+                            type: "video_url",
+                            video_url: { url: videoUrl },
+                            role: "reference_video",
+                        });
+                    }
+                }
+                // Reference audios
+                if (request.referenceAudios?.length) {
+                    for (const audioUrl of request.referenceAudios) {
+                        content.push({
+                            type: "audio_url",
+                            audio_url: { url: audioUrl },
+                            role: "reference_audio",
+                        });
+                    }
+                }
+                break;
+            }
+            case "extend": {
+                // Seedance 2.0: extend/bridge video segments
+                if (request.sourceVideos?.length) {
+                    for (const videoUrl of request.sourceVideos) {
+                        content.push({
+                            type: "video_url",
+                            video_url: { url: videoUrl },
+                            role: "reference_video",
+                        });
+                    }
+                }
+                if (request.prompt)
+                    content.push({ type: "text", text: request.prompt });
+                break;
+            }
+            case "merge":
+                // Pass all source videos in order
+                for (const videoUrl of request.sourceVideos ?? []) {
+                    content.push({ type: "video_url", video_url: { url: videoUrl } });
+                }
+                if (request.prompt)
+                    content.push({ type: "text", text: request.prompt });
+                break;
+            case "upscale":
+                if (request.sourceVideos?.[0]) {
+                    content.push({ type: "video_url", video_url: { url: request.sourceVideos[0] } });
+                }
+                content.push({ type: "text", text: request.prompt || "upscale" });
+                break;
+            case "edit":
+                // Seedance 2.0 video edit: source videos (1-3) + reference images (0-9) + text instruction
+                // Per volcengine-ProviderMax 搂22.6-22.7: source videos carry role "reference_video",
+                // reference images carry role "reference_image", enabling element replacement / track fill.
+                for (const videoUrl of request.sourceVideos ?? []) {
+                    content.push({
+                        type: "video_url",
+                        video_url: { url: videoUrl },
+                        role: "reference_video",
+                    });
+                }
+                if (request.referenceImages?.length) {
+                    for (const imgUrl of request.referenceImages) {
+                        content.push({
+                            type: "image_url",
+                            image_url: { url: imgUrl },
+                            role: "reference_image",
+                        });
+                    }
+                }
+                if (request.prompt)
+                    content.push({ type: "text", text: request.prompt });
+                break;
+            default: {
+                // Auto-detect operation type from inputs:
+                //   - referenceImages with roles or referenceVideos/referenceAudios 鈫?multimodal_reference
+                //   - referenceImages without roles 鈫?img2video (first_frame default)
+                //   - imageUrl only 鈫?img2video
+                //   - text only 鈫?text2video
+                const hasRefVideos = (request.referenceVideos?.length ?? 0) > 0;
+                const hasRefAudios = (request.referenceAudios?.length ?? 0) > 0;
+                const hasImageRoles = (request.imageRoles?.length ?? 0) > 0;
+                if (hasRefVideos || hasRefAudios || hasImageRoles) {
+                    // Multimodal reference mode
+                    if (request.prompt)
+                        content.push({ type: "text", text: request.prompt });
+                    if (request.referenceImages?.length) {
+                        for (let i = 0; i < request.referenceImages.length; i++) {
+                            const role = request.imageRoles?.[i] ?? "reference_image";
+                            content.push({
+                                type: "image_url",
+                                image_url: { url: request.referenceImages[i] },
+                                role,
+                            });
+                        }
+                    }
+                    if (hasRefVideos) {
+                        for (const videoUrl of request.referenceVideos) {
+                            content.push({
+                                type: "video_url",
+                                video_url: { url: videoUrl },
+                                role: "reference_video",
+                            });
+                        }
+                    }
+                    if (hasRefAudios) {
+                        for (const audioUrl of request.referenceAudios) {
+                            content.push({
+                                type: "audio_url",
+                                audio_url: { url: audioUrl },
+                                role: "reference_audio",
+                            });
+                        }
+                    }
+                }
+                else if (request.referenceImages?.length) {
+                    for (const imgUrl of request.referenceImages) {
+                        content.push({ type: "image_url", image_url: { url: imgUrl } });
+                    }
+                    if (request.prompt)
+                        content.push({ type: "text", text: request.prompt });
+                }
+                else if (request.imageUrl) {
+                    content.push({ type: "image_url", image_url: { url: request.imageUrl } });
+                    if (request.prompt)
+                        content.push({ type: "text", text: request.prompt });
+                }
+                else {
+                    if (request.prompt)
+                        content.push({ type: "text", text: request.prompt });
+                }
+                break;
+            }
+        }
+        const body = {
+            model: request.model,
+            content,
+        };
+        if (request.duration)
+            body.duration = request.duration;
+        if (request.aspectRatio)
+            body.ratio = request.aspectRatio;
+        if (request.resolution)
+            body.resolution = request.resolution;
+        if (request.seed !== undefined)
+            body.seed = request.seed;
+        if (request.fps)
+            body.fps = request.fps;
+        if (request.generateAudio !== undefined)
+            body.generate_audio = request.generateAudio;
+        if (request.watermark !== undefined)
+            body.watermark = request.watermark;
+        if (request.enhancePrompt !== undefined)
+            body.enhance_prompt = request.enhancePrompt;
+        // P4 advanced params (volcengine-ProviderMax 搂22.10-22.16)
+        if (request.cameraFixed !== undefined)
+            body.camera_fixed = request.cameraFixed;
+        if (request.returnLastFrame !== undefined)
+            body.return_last_frame = request.returnLastFrame;
+        if (request.serviceTier)
+            body.service_tier = request.serviceTier;
+        if (request.executionExpiresAfterSeconds !== undefined)
+            body.execution_expires_after = request.executionExpiresAfterSeconds;
+        if (request.draft !== undefined)
+            body.draft = request.draft;
+        if (request.safetyIdentifier)
+            body.safety_identifier = request.safetyIdentifier;
+        if (request.callbackUrl)
+            body.callback_url = request.callbackUrl;
+        if (request.videoTools?.length) {
+            body.tools = request.videoTools.map(name => ({ type: name }));
+        }
+        const taskId = await this.submitTask(url, body, apiKey, signal);
+        const result = await this.pollTask(`${this.baseUrl}/v3/contents/generations/tasks/${taskId}`, apiKey, signal, request.onProgress, taskId);
+        const mediaUrls = [];
+        // Volcengine returns content as { video_url: "https://..." } (object, not array)
+        const resultContent = result.content;
+        if (typeof resultContent?.video_url === "string") {
+            mediaUrls.push(resultContent.video_url);
+        }
+        // P4 #25: Extract last_frame_url for chaining continuous segments
+        const lastFrameUrl = typeof resultContent?.last_frame_url === "string"
+            ? resultContent.last_frame_url
+            : undefined;
+        const tokenUsage = extractGeneratedTokenUsage(result);
+        return {
+            mediaUrls,
+            model: request.model,
+            durationMs: Date.now() - start,
+            lastFrameUrl,
+            taskId,
+            billingUnit: "per_token",
+            billingQuantity: tokenUsage.completionTokens,
+            metadata: {
+                billableUnits: {
+                    completion_tokens: tokenUsage.completionTokens,
+                    total_tokens: tokenUsage.totalTokens,
+                },
+                usage: tokenUsage.rawUsage,
+                usageMissing: !tokenUsage.hasUsage,
+                pricingSpec: request.resolution ?? "720p",
+            },
+        };
+    }
+    // 鈹€鈹€ 3D 鈥?async job 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+    async generate3D(request, apiKey, signal) {
+        const start = Date.now();
+        // 3D uses the same endpoint as video (per Volcengine docs)
+        const url = `${this.baseUrl}/v3/contents/generations/tasks`;
+        // Build content array 鈥?same structure as video.
+        // Text item carries CLI-style params (--fileformat,subdivisionlevel) and optional prompt.
+        // Image item provides the reference image for image-to-3D.
+        const content = [];
+        const textParts = [];
+        if (request.outputFormat)
+            textParts.push(`--fileformat ${request.outputFormat}`);
+        if (request.prompt)
+            textParts.push(request.prompt);
+        if (textParts.length > 0) {
+            content.push({ type: "text", text: textParts.join(" ") });
+        }
+        if (request.imageUrl) {
+            content.push({ type: "image_url", image_url: { url: request.imageUrl } });
+        }
+        const body = {
+            model: request.model,
+            content,
+        };
+        const taskId = await this.submitTask(url, body, apiKey, signal);
+        const result = await this.pollTask(`${this.baseUrl}/v3/contents/generations/tasks/${taskId}`, apiKey, signal, request.onProgress, taskId);
+        // 3D output: SDK uses content.video_url (same field as video);
+        // also check output.model_urls for possible alternative response shapes.
+        const mediaUrls = [];
+        const resultContent = result.content;
+        if (typeof resultContent?.video_url === "string") {
+            mediaUrls.push(resultContent.video_url);
+        }
+        // Fallback: scan all string values in content for URLs
+        if (mediaUrls.length === 0 && resultContent) {
+            for (const [, v] of Object.entries(resultContent)) {
+                if (typeof v === "string" && /^https?:\/\//.test(v)) {
+                    mediaUrls.push(v);
+                }
+            }
+        }
+        const output = result.output;
+        if (output?.model_urls) {
+            const urls = output.model_urls;
+            for (const u of Object.values(urls)) {
+                if (u && !mediaUrls.includes(u))
+                    mediaUrls.push(u);
+            }
+        }
+        // Debug: log response shape when no URLs found
+        if (mediaUrls.length === 0) {
+            const keys = Object.keys(result);
+            const contentKeys = resultContent ? Object.keys(resultContent) : [];
+            const outputKeys = output ? Object.keys(output) : [];
+            console.error(`[volcengine-3d] No media URLs found. Response keys: [${keys}], content keys: [${contentKeys}], output keys: [${outputKeys}]`);
+            // Also check for nested data field
+            const data = result.data;
+            if (data?.content) {
+                const dc = data.content;
+                for (const [, v] of Object.entries(dc)) {
+                    if (typeof v === "string" && /^https?:\/\//.test(v)) {
+                        mediaUrls.push(v);
+                    }
+                }
+            }
+        }
+        const tokenUsage = extractGeneratedTokenUsage(result);
+        return {
+            mediaUrls,
+            model: request.model,
+            durationMs: Date.now() - start,
+            billingUnit: "per_token",
+            billingQuantity: tokenUsage.completionTokens,
+            metadata: mediaUrls.length === 0 ? {
+                billableUnits: {
+                    completion_tokens: tokenUsage.completionTokens,
+                    total_tokens: tokenUsage.totalTokens,
+                },
+                usage: tokenUsage.rawUsage,
+                usageMissing: !tokenUsage.hasUsage,
+                debugResponseKeys: Object.keys(result),
+                debugContentKeys: resultContent ? Object.keys(resultContent) : null,
+                debugContentSample: resultContent ? JSON.stringify(resultContent).slice(0, 500) : null,
+                debugOutputKeys: output ? Object.keys(output) : null,
+                debugResultSample: JSON.stringify(result).slice(0, 800),
+            } : {
+                billableUnits: {
+                    completion_tokens: tokenUsage.completionTokens,
+                    total_tokens: tokenUsage.totalTokens,
+                },
+                usage: tokenUsage.rawUsage,
+                usageMissing: !tokenUsage.hasUsage,
+                pricingSpec: request.outputFormat ?? "3d",
+            },
+        };
+    }
+    // 鈹€鈹€ Video Task Management (#23, #24) 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+    /**
+     * Query a single video generation task by ID.
+     * GET /v3/contents/generations/tasks/{taskId}
+     */
+    async getTaskStatus(taskId, apiKey, signal) {
+        const url = `${this.baseUrl}/v3/contents/generations/tasks/${taskId}`;
+        const res = await fetch(url, {
+            method: "GET",
+            headers: { Authorization: `Bearer ${apiKey}` },
+            signal: signal ?? AbortSignal.timeout(this.timeoutMs),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`Volcengine task status error ${res.status}: ${text}`);
+        }
+        const data = await res.json();
+        const rawStatus = data.status ?? "unknown";
+        return { status: rawStatus, task: data };
+    }
+    /**
+     * List video generation tasks with optional filters.
+     * GET /v3/contents/generations/tasks
+     */
+    async listVideoTasks(apiKey, options, signal) {
+        const params = new URLSearchParams();
+        if (options?.after)
+            params.set("after", options.after);
+        if (options?.limit)
+            params.set("limit", String(options.limit));
+        if (options?.status)
+            params.set("status", options.status);
+        const qs = params.toString();
+        const url = `${this.baseUrl}/v3/contents/generations/tasks${qs ? `?${qs}` : ""}`;
+        const res = await fetch(url, {
+            method: "GET",
+            headers: { Authorization: `Bearer ${apiKey}` },
+            signal: signal ?? AbortSignal.timeout(this.timeoutMs),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`Volcengine list tasks error ${res.status}: ${text}`);
+        }
+        return await res.json();
+    }
+    /**
+     * Cancel or delete a video generation task.
+     * DELETE /v3/contents/generations/tasks/{taskId}
+     */
+    async deleteVideoTask(taskId, apiKey, signal) {
+        const url = `${this.baseUrl}/v3/contents/generations/tasks/${taskId}`;
+        const res = await fetch(url, {
+            method: "DELETE",
+            headers: { Authorization: `Bearer ${apiKey}` },
+            signal: signal ?? AbortSignal.timeout(this.timeoutMs),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`Volcengine delete task error ${res.status}: ${text}`);
+        }
+    }
+    // 鈹€鈹€ Files API (#29) 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+    /**
+     * Upload a file to Volcengine Files API for reuse in multimodal requests.
+     * POST /v3/files
+     */
+    async uploadFile(file, apiKey, options, signal) {
+        const url = `${this.baseUrl}/v3/files`;
+        const form = new FormData();
+        form.append("file", file instanceof Blob ? file : new Blob([file]), options?.filename ?? "upload");
+        form.append("purpose", options?.purpose ?? "user_data");
+        const res = await fetch(url, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${apiKey}` },
+            body: form,
+            signal: signal ?? AbortSignal.timeout(this.timeoutMs),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`Volcengine file upload error ${res.status}: ${text}`);
+        }
+        const data = await res.json();
+        return { id: String(data.id ?? ""), status: String(data.status ?? "") };
+    }
+    /**
+     * Get file info by ID.
+     * GET /v3/files/{fileId}
+     */
+    async getFile(fileId, apiKey, signal) {
+        const url = `${this.baseUrl}/v3/files/${fileId}`;
+        const res = await fetch(url, {
+            method: "GET",
+            headers: { Authorization: `Bearer ${apiKey}` },
+            signal: signal ?? AbortSignal.timeout(this.timeoutMs),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`Volcengine get file error ${res.status}: ${text}`);
+        }
+        return await res.json();
+    }
+    /**
+     * List uploaded files.
+     * GET /v3/files
+     */
+    async listFiles(apiKey, options, signal) {
+        const params = new URLSearchParams();
+        if (options?.after)
+            params.set("after", options.after);
+        if (options?.limit)
+            params.set("limit", String(options.limit));
+        if (options?.purpose)
+            params.set("purpose", options.purpose);
+        if (options?.order)
+            params.set("order", options.order);
+        const qs = params.toString();
+        const url = `${this.baseUrl}/v3/files${qs ? `?${qs}` : ""}`;
+        const res = await fetch(url, {
+            method: "GET",
+            headers: { Authorization: `Bearer ${apiKey}` },
+            signal: signal ?? AbortSignal.timeout(this.timeoutMs),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`Volcengine list files error ${res.status}: ${text}`);
+        }
+        return await res.json();
+    }
+    /**
+     * Delete a file.
+     * DELETE /v3/files/{fileId}
+     */
+    async deleteFile(fileId, apiKey, signal) {
+        const url = `${this.baseUrl}/v3/files/${fileId}`;
+        const res = await fetch(url, {
+            method: "DELETE",
+            headers: { Authorization: `Bearer ${apiKey}` },
+            signal: signal ?? AbortSignal.timeout(this.timeoutMs),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`Volcengine delete file error ${res.status}: ${text}`);
+        }
+    }
+    // 鈹€鈹€ Shared helpers 鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€鈹€
+    async submitTask(url, body, apiKey, signal) {
+        const res = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify(body),
+            signal: signal ?? AbortSignal.timeout(this.timeoutMs),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`Volcengine task submit error ${res.status}: ${text}`);
+        }
+        const data = await res.json();
+        const taskId = data.id ?? data.task_id;
+        if (!taskId) {
+            throw new Error("Volcengine task submit: no task_id in response");
+        }
+        return taskId;
+    }
+    async pollTask(url, apiKey, signal, onProgress, taskId) {
+        const deadline = Date.now() + MAX_POLL_MS;
+        let pollCount = 0;
+        while (Date.now() < deadline) {
+            signal?.throwIfAborted();
+            const res = await fetch(url, {
+                method: "GET",
+                headers: { Authorization: `Bearer ${apiKey}` },
+                signal: signal ?? AbortSignal.timeout(this.timeoutMs),
+            });
+            if (!res.ok) {
+                const text = await res.text().catch(() => "");
+                throw new Error(`Volcengine task poll error ${res.status}: ${text}`);
+            }
+            const data = await res.json();
+            const status = data.status;
+            if (status === "succeeded" || status === "complete") {
+                onProgress?.(100, "completed", taskId);
+                return data;
+            }
+            if (status === "failed" || status === "cancelled") {
+                const errMsg = data.error?.message ?? "Task failed";
+                throw new Error(`Volcengine task failed: ${errMsg}`);
+            }
+            // Estimate progress from elapsed time
+            pollCount++;
+            const elapsed = Date.now() - (deadline - MAX_POLL_MS);
+            const estimatedPercent = Math.min(95, Math.round((elapsed / MAX_POLL_MS) * 100));
+            onProgress?.(estimatedPercent, status ?? "running", taskId);
+            // Still running 鈥?wait and retry
+            await new Promise(r => setTimeout(r, POLL_INTERVAL_MS));
+        }
+        throw new Error("Volcengine task timed out after polling");
+    }
+}
+function extractGeneratedTokenUsage(result) {
+    const usage = (result.usage ?? result.data?.usage);
+    const completionTokens = numericUsage(usage?.completion_tokens)
+        ?? numericUsage(usage?.completionTokens)
+        ?? numericUsage(usage?.output_tokens)
+        ?? numericUsage(usage?.outputTokens)
+        ?? numericUsage(usage?.total_tokens)
+        ?? numericUsage(usage?.totalTokens)
+        ?? 0;
+    const totalTokens = numericUsage(usage?.total_tokens)
+        ?? numericUsage(usage?.totalTokens)
+        ?? completionTokens;
+    return {
+        completionTokens,
+        totalTokens,
+        hasUsage: !!usage,
+        rawUsage: usage,
+    };
+}
+function numericUsage(value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (typeof value === "string" && value.trim()) {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    return undefined;
+}