@nodetool-ai/runtime 0.7.0-rc.23 → 0.8.1

package/dist/providers/kie-provider.js

@@ -7,22 +7,140 @@
  * endpoints and reuse the existing OpenAI/Anthropic provider implementations
  * where their APIs are wire-compatible.
  */
+import { recordGenerationReceipt } from "../generation-receipt.js";
 import Anthropic from "@anthropic-ai/sdk";
 import OpenAI from "openai";
 import { BaseProvider } from "./base-provider.js";
+import { safeFetch } from "./safe-url.js";
+import { isString } from "@nodetool-ai/protocol";
 import { createLogger } from "@nodetool-ai/config";
-import { loadVideoModels, loadImageModels } from "./manifest-models.js";
+import { loadVideoModels, loadImageModels, loadMusicModels, loadTTSModels, getModelImageInputs, getModelMediaInputs, getModelReferenceInputs, getModelInputFields, getManifestNodeMeta, selectPrimaryImageInput, selectMaskImageInput } from "./manifest-models.js";
+import { validateReferenceInputs } from "./manifest-models.js";
+import { registerWebhookWait } from "./kie-webhook-registry.js";
+import { sniffAudioMime } from "./audio-mime.js";
+import { detectImageMime, extForImageMime } from "./image-mime.js";
+import { sniffMediaMime } from "./media-mime.js";
 import { OpenAIProvider } from "./openai-provider.js";
 import { AnthropicProvider } from "./anthropic-provider.js";
+import { extractResponsesText, extractResponsesToolCalls, messagesToResponsesInput, responseToolChoice, responseTools, responseUsage, streamResponsesEvents } from "./responses-api.js";
 const log = createLogger("nodetool.runtime.providers.kie");
+function combineSignals(signal, timeout) {
+    if (!signal)
+        return timeout;
+    if (!timeout)
+        return signal;
+    return AbortSignal.any([signal, timeout]);
+}
 const KIE_API_BASE = "https://api.kie.ai";
+const KIE_UPLOAD_URL = "https://kieai.redpandaai.co/api/file-stream-upload";
+// The Suno API always requires a callBackUrl. When KIE_WEBHOOK_URL is set we
+// use it; otherwise a placeholder satisfies the requirement (we poll instead).
+const KIE_SUNO_CALLBACK = "https://nodetool.ai/kie-callback";
+/**
+ * When set, KIE tasks are submitted with a real callBackUrl and the provider
+ * waits for the webhook instead of polling. Set to the public base URL of this
+ * server (e.g. `https://myserver.example.com`).
+ */
+function getWebhookBaseUrl() {
+    const url = process.env.KIE_WEBHOOK_URL;
+    return url && url.trim() ? url.replace(/\/+$/, "") : undefined;
+}
+// Mirrors the "Chat Models" section of docs.kie.ai/llms.txt. Each entry's
+// basePath is the model's documented endpoint prefix: the Claude models share
+// /claude/v1/messages, the GPT, Grok, Kimi and DeepSeek models post to a
+// /responses endpoint, and every Gemini (plus GPT 5.2) endpoint is OpenAI
+// chat-completions with the model pinned by the path.
 const KIE_CHAT_MODELS = [
+    {
+        id: "gpt-6-sol",
+        name: "GPT 6 Sol",
+        api: "responses",
+        basePath: "/codex/v1"
+    },
+    {
+        id: "gpt-6-astra",
+        name: "GPT 6 Astra",
+        api: "responses",
+        basePath: "/codex/v1"
+    },
+    {
+        id: "gpt-6-luna",
+        name: "GPT 6 Luna",
+        api: "responses",
+        basePath: "/codex/v1"
+    },
+    {
+        id: "gpt-5-6-sol",
+        name: "GPT 5.6 Sol",
+        api: "responses",
+        basePath: "/codex/v1"
+    },
+    {
+        id: "gpt-5-6-terra",
+        name: "GPT 5.6 Terra",
+        api: "responses",
+        basePath: "/codex/v1"
+    },
+    {
+        id: "gpt-5-6-luna",
+        name: "GPT 5.6 Luna",
+        api: "responses",
+        basePath: "/codex/v1"
+    },
     {
         id: "gpt-5-5",
         name: "GPT 5.5",
         api: "responses",
         basePath: "/codex/v1"
     },
+    {
+        id: "gpt-5-4",
+        name: "GPT 5.4",
+        api: "responses",
+        basePath: "/codex/v1"
+    },
+    {
+        id: "gpt-5.1-codex",
+        name: "GPT Codex",
+        api: "responses",
+        basePath: "/api/v1"
+    },
+    {
+        id: "gpt-5-2",
+        name: "GPT 5.2",
+        api: "openai",
+        basePath: "/gpt-5-2/v1"
+    },
+    {
+        id: "claude-opus-5",
+        name: "Claude Opus 5",
+        api: "anthropic",
+        basePath: "/claude"
+    },
+    {
+        id: "claude-sonnet-5",
+        name: "Claude Sonnet 5",
+        api: "anthropic",
+        basePath: "/claude"
+    },
+    {
+        id: "claude-fable-5",
+        name: "Claude Fable 5",
+        api: "anthropic",
+        basePath: "/claude"
+    },
+    {
+        id: "claude-opus-4-8",
+        name: "Claude Opus 4.8",
+        api: "anthropic",
+        basePath: "/claude"
+    },
+    {
+        id: "claude-opus-4-7",
+        name: "Claude Opus 4.7",
+        api: "anthropic",
+        basePath: "/claude"
+    },
     {
         id: "claude-opus-4-6",
         name: "Claude Opus 4.6",
@@ -35,23 +153,113 @@ const KIE_CHAT_MODELS = [
         api: "anthropic",
         basePath: "/claude"
     },
+    {
+        id: "claude-opus-4-5",
+        name: "Claude Opus 4.5",
+        api: "anthropic",
+        basePath: "/claude"
+    },
+    {
+        id: "claude-sonnet-4-5",
+        name: "Claude Sonnet 4.5",
+        api: "anthropic",
+        basePath: "/claude"
+    },
     {
         id: "claude-haiku-4-5",
         name: "Claude Haiku 4.5",
         api: "anthropic",
         basePath: "/claude"
     },
+    {
+        id: "grok-4-7",
+        name: "Grok 4.7",
+        api: "responses",
+        basePath: "/grok/v1"
+    },
+    {
+        id: "grok-4-6",
+        name: "Grok 4.6",
+        api: "responses",
+        basePath: "/grok/v1"
+    },
+    {
+        id: "grok-4-5",
+        name: "Grok 4.5",
+        api: "responses",
+        basePath: "/grok/v1"
+    },
+    {
+        id: "grok-4-3",
+        name: "Grok 4.3",
+        api: "responses",
+        basePath: "/grok/v1"
+    },
+    {
+        id: "kimi-k3",
+        name: "Kimi K3",
+        api: "responses",
+        basePath: "/openai/v1"
+    },
+    {
+        id: "deepseek-v4-1-flash",
+        name: "DeepSeek V4.1 Flash",
+        api: "responses",
+        basePath: "/openai/v1"
+    },
     {
         id: "gemini-3.1-pro",
         name: "Gemini 3.1 Pro",
         api: "openai",
         basePath: "/gemini-3.1-pro/v1"
     },
+    {
+        id: "gemini-3-pro",
+        name: "Gemini 3 Pro",
+        api: "openai",
+        basePath: "/gemini-3-pro/v1"
+    },
+    {
+        id: "gemini-3-8-flash",
+        name: "Gemini 3.8 Flash",
+        api: "openai",
+        basePath: "/gemini-3-8-flash-openai/v1"
+    },
+    {
+        id: "gemini-3-7-flash",
+        name: "Gemini 3.7 Flash",
+        api: "openai",
+        basePath: "/gemini-3-7-flash-openai/v1"
+    },
+    {
+        id: "gemini-3-6-flash",
+        name: "Gemini 3.6 Flash",
+        api: "openai",
+        basePath: "/gemini-3-6-flash-openai/v1"
+    },
+    {
+        id: "gemini-3-5-flash",
+        name: "Gemini 3.5 Flash",
+        api: "openai",
+        basePath: "/gemini-3-5-flash-openai/v1"
+    },
     {
         id: "gemini-3-flash",
         name: "Gemini 3 Flash",
         api: "openai",
         basePath: "/gemini-3-flash/v1"
+    },
+    {
+        id: "gemini-2.5-pro",
+        name: "Gemini 2.5 Pro",
+        api: "openai",
+        basePath: "/gemini-2.5-pro/v1"
+    },
+    {
+        id: "gemini-2.5-flash",
+        name: "Gemini 2.5 Flash",
+        api: "openai",
+        basePath: "/gemini-2.5-flash/v1"
     }
 ];
 function chatModel(model) {
@@ -63,73 +271,377 @@ function headers(apiKey) {
         "Content-Type": "application/json"
     };
 }
-async function submitTask(apiKey, model, input) {
+/** Resolve the abort reason as an Error (mirrors the gemini provider). */
+function abortError(signal) {
+    return signal?.reason instanceof Error ? signal.reason : new Error("Aborted");
+}
+/** Sleep that rejects promptly when `signal` aborts instead of running full. */
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(abortError(signal));
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(abortError(signal));
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/**
+ * KIE reports API errors inside HTTP-200 bodies as `{code, msg}`. Map the known
+ * error codes to a message and throw; code 200 (and any unmapped code) passes
+ * through. Mirrors kie-base's `checkStatus` — without this a failed job returns
+ * a 200 that the poll loop reads as "not done yet" and runs to full timeout.
+ */
+/** The `code` values KIE returns inside an HTTP-200 error envelope. */
+const KIE_ERROR_CODES = {
+    401: "Unauthorized",
+    402: "Insufficient Credits",
+    404: "Not Found",
+    422: "Validation Error",
+    429: "Rate Limited",
+    455: "Service Unavailable",
+    500: "Server Error",
+    501: "Generation Failed",
+    505: "Feature Disabled"
+};
+/**
+ * Classify a KIE response envelope. Returns the error KIE announced inside an
+ * otherwise-successful HTTP response, or null when the envelope is not an
+ * error. The live contract probe reads this to check that the error envelope
+ * still looks the way the provider expects.
+ */
+export function kieEnvelopeError(data) {
+    const code = Number(data.code);
+    const label = KIE_ERROR_CODES[code];
+    if (!label)
+        return null;
+    const message = isString(data.msg) ? data.msg : "";
+    return { code, label, message };
+}
+function checkStatus(data) {
+    const error = kieEnvelopeError(data);
+    if (error)
+        throw new Error(`${error.label}: ${JSON.stringify(data)}`);
+}
+/** Decode a `createTask` body into the task id it announces. */
+export function decodeKieTaskSubmission(data) {
+    checkStatus(data);
+    const taskId = data.data?.taskId;
+    if (!isString(taskId) || taskId.length === 0) {
+        throw new Error(`No taskId in Kie response: ${JSON.stringify(data)}`);
+    }
+    return taskId;
+}
+/** Decode a `recordInfo` body into the job state the poller branches on. */
+export function decodeKieRecordInfo(data) {
+    checkStatus(data);
+    const payload = data.data ?? {};
+    const state = payload.state;
+    if (!isString(state) || state.length === 0) {
+        throw new Error(`No state in Kie recordInfo: ${JSON.stringify(data)}`);
+    }
+    return { state, failMsg: isString(payload.failMsg) ? payload.failMsg : "" };
+}
+/**
+ * Decode the result URLs out of a finished `recordInfo` body. KIE nests them
+ * as a JSON *string* under `data.resultJson`, so this is two decodes.
+ */
+export function decodeKieResultUrls(data) {
+    checkStatus(data);
+    const resultJsonStr = data.data?.resultJson;
+    if (!isString(resultJsonStr)) {
+        throw new Error("No resultJson in Kie response");
+    }
+    let resultData;
+    try {
+        resultData = JSON.parse(resultJsonStr);
+    }
+    catch {
+        throw new Error("Kie resultJson is not JSON");
+    }
+    const resultUrls = resultData.resultUrls;
+    if (!Array.isArray(resultUrls) || resultUrls.length === 0) {
+        throw new Error("No resultUrls in Kie resultJson");
+    }
+    return resultUrls.filter(isString);
+}
+/**
+ * Parse a KIE JSON response defensively: a gateway 502 returns an HTML page, not
+ * JSON, so read the text and surface a "Kie <label> failed: <status> …" error
+ * with a body snippet rather than a bare SyntaxError. Applies the HTTP-200 error
+ * envelope check ({@link checkStatus}) on every parsed body.
+ */
+async function parseKieJson(res, label) {
+    const text = await res.text();
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`Kie ${label} failed: ${res.status} ${text.slice(0, 200)}`);
+    }
+    if (data.code !== undefined)
+        checkStatus(data);
+    return data;
+}
+/** Parse an "a:b" aspect ratio string into its numeric value, or undefined. */
+function aspectToNumber(ratio) {
+    const m = /^(\d+(?:\.\d+)?)\s*:\s*(\d+(?:\.\d+)?)$/.exec(ratio.trim());
+    if (!m)
+        return undefined;
+    const w = Number(m[1]);
+    const h = Number(m[2]);
+    if (!Number.isFinite(w) || !Number.isFinite(h) || h === 0)
+        return undefined;
+    return w / h;
+}
+/** Choose the declared enum aspect ratio closest to a target numeric ratio. */
+function nearestAspect(enumValues, target) {
+    let best;
+    for (const value of enumValues) {
+        const n = aspectToNumber(value);
+        if (n === undefined)
+            continue;
+        const diff = Math.abs(n - target);
+        if (!best || diff < best.diff)
+            best = { value, diff };
+    }
+    return best?.value ?? enumValues[0];
+}
+/**
+ * Coerce a requested duration (seconds) to the model's declared `duration`
+ * field type: snap to the nearest allowed enum value (sent as the enum's own
+ * value type — the manifest enums are strings), round to an int, or pass a
+ * float through. Returns undefined when the model declares no duration field.
+ */
+function coerceDuration(field, seconds) {
+    if (!field)
+        return undefined;
+    if (field.type === "enum" && field.enumValues && field.enumValues.length > 0) {
+        let best;
+        for (const value of field.enumValues) {
+            const n = Number(value);
+            if (!Number.isFinite(n))
+                continue;
+            const diff = Math.abs(n - seconds);
+            if (!best || diff < best.diff)
+                best = { value, diff };
+        }
+        return best?.value ?? field.enumValues[0];
+    }
+    if (field.type === "float")
+        return seconds;
+    // int and any other numeric type: send a rounded integer.
+    return Math.round(seconds);
+}
+/**
+ * A field's default usable as an input value: the declared default when it's
+ * meaningful (not an empty string), otherwise the first enum option. KIE's
+ * required `model` field ships with an empty default, so the first declared
+ * version is used.
+ */
+/**
+ * HOLDOUT (anti-slop/no-unknown-returns): the value comes straight from the
+ * manifest's `default`, which `ModelInputField` declares `unknown`; naming the
+ * result means typing the manifest decoder in `manifest-models.ts`.
+ */
+function defaultForField(field) {
+    const d = field.default;
+    if (d !== undefined && !(isString(d) && d === ""))
+        return d;
+    if (field.enumValues && field.enumValues.length > 0)
+        return field.enumValues[0];
+    return undefined;
+}
+/**
+ * Upload raw image bytes to KIE's file store and return the hosted URL. Sniffs
+ * the container from the magic bytes so the upload carries the right mime and
+ * extension (KIE rejects a JPEG announced as PNG).
+ */
+async function uploadImageBytes(apiKey, bytes, signal) {
+    const mime = detectImageMime(bytes);
+    const ext = extForImageMime(mime) ?? "png";
+    const fileName = `upload-${Date.now()}.${ext}`;
+    const form = new FormData();
+    form.append("file", new Blob([new Uint8Array(bytes)], { type: mime }), fileName);
+    form.append("uploadPath", "images/user-uploads");
+    form.append("fileName", fileName);
+    const res = await fetch(KIE_UPLOAD_URL, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${apiKey}` },
+        body: form,
+        signal
+    });
+    const data = await parseKieJson(res, "upload");
+    if (!res.ok || !data.success) {
+        throw new Error(`Kie upload failed: ${res.status} ${JSON.stringify(data)}`);
+    }
+    const downloadUrl = data.data
+        ?.downloadUrl;
+    if (!downloadUrl) {
+        throw new Error(`No downloadUrl in Kie upload response`);
+    }
+    return downloadUrl;
+}
+async function uploadMediaBytes(apiKey, bytes, signal, kind) {
+    const mime = sniffMediaMime(bytes, kind === "image" ? "image/png" : "video/mp4");
+    const ext = kind === "image" ? (extForImageMime(mime) ?? "png") : "mp4";
+    const fileName = `upload-${Date.now()}.${ext}`;
+    const form = new FormData();
+    form.append("file", new Blob([new Uint8Array(bytes)], { type: mime }), fileName);
+    form.append("uploadPath", kind === "image" ? "images/user-uploads" : "videos/user-uploads");
+    form.append("fileName", fileName);
+    const res = await fetch(KIE_UPLOAD_URL, { method: "POST", headers: { Authorization: `Bearer ${apiKey}` }, body: form, signal });
+    const data = await parseKieJson(res, "upload");
+    if (!res.ok || !data.success)
+        throw new Error(`Kie upload failed: ${res.status} ${JSON.stringify(data)}`);
+    const downloadUrl = data.data?.downloadUrl;
+    if (typeof downloadUrl !== "string" || !downloadUrl)
+        throw new Error("No downloadUrl in Kie upload response");
+    return downloadUrl;
+}
+async function submitTask(apiKey, model, input, signal) {
     const res = await fetch(`${KIE_API_BASE}/api/v1/jobs/createTask`, {
         method: "POST",
         headers: headers(apiKey),
-        body: JSON.stringify({ model, input })
+        body: JSON.stringify({ model, input }),
+        signal
     });
-    const data = (await res.json());
+    const data = await parseKieJson(res, "submit");
     if (!res.ok) {
         throw new Error(`Kie submit failed: ${res.status} ${JSON.stringify(data)}`);
     }
-    const taskId = data.data?.taskId;
-    if (!taskId) {
-        throw new Error(`No taskId in Kie response: ${JSON.stringify(data)}`);
-    }
+    const taskId = decodeKieTaskSubmission(data);
+    // KIE bills at submit, so the task id is the receipt even when the poll
+    // later fails or times out: the reconciler looks the charge up by it.
+    recordGenerationReceipt({ provider_request_id: taskId });
     return taskId;
 }
-async function pollUntilDone(apiKey, taskId, pollInterval = 4000, maxAttempts = 300) {
+/**
+ * Submit a task with an optional webhook callback URL. When webhook mode is
+ * enabled, the callBackUrl is injected into the input so KIE calls us back
+ * when the task completes. The generic `/api/kie/webhook` endpoint extracts
+ * the taskId from the callback body.
+ */
+async function submitTaskWithWebhook(apiKey, model, input, signal) {
+    const webhookBase = getWebhookBaseUrl();
+    const finalInput = webhookBase
+        ? { ...input, callBackUrl: `${webhookBase}/api/kie/webhook` }
+        : input;
+    return submitTask(apiKey, model, finalInput, signal);
+}
+async function pollUntilDone(apiKey, taskId, pollInterval = 4000, maxAttempts = 300, signal) {
     const url = `${KIE_API_BASE}/api/v1/jobs/recordInfo?taskId=${taskId}`;
+    // KIE reports failures two ways that both look like "still running" to a naive
+    // loop: a persistent non-OK poll (429/5xx/revoked key) after createTask
+    // succeeded, and an HTTP-200 body carrying an error `code` (checkStatus). Both
+    // used to run the full maxAttempts (~20 min) before blaming a slow job. Fail
+    // fast: on a bounded run of consecutive HTTP errors, and immediately on a code
+    // envelope (via parseKieJson).
+    const MAX_CONSECUTIVE_ERRORS = 5;
+    let consecutiveErrors = 0;
     for (let i = 0; i < maxAttempts; i++) {
-        const res = await fetch(url, { headers: headers(apiKey) });
-        const data = (await res.json());
-        const state = data.data?.state;
+        const res = await fetch(url, { headers: headers(apiKey), signal });
+        if (!res.ok) {
+            consecutiveErrors += 1;
+            if (consecutiveErrors >= MAX_CONSECUTIVE_ERRORS) {
+                const body = await res.text().catch(() => "");
+                throw new Error(`Kie recordInfo failed ${consecutiveErrors}× (HTTP ${res.status}) for taskId ${taskId}: ${body.slice(0, 200)}`);
+            }
+            await sleep(pollInterval, signal);
+            continue;
+        }
+        consecutiveErrors = 0;
+        const { state, failMsg } = decodeKieRecordInfo(await parseKieJson(res, "recordInfo"));
         if (state === "success")
             return;
         if (state === "failed" || state === "fail") {
-            const msg = data.data?.failMsg || "Unknown error";
-            throw new Error(`Kie task failed: ${msg}`);
+            throw new Error(`Kie task failed: ${failMsg || "Unknown error"} (taskId: ${taskId})`);
         }
-        await new Promise((r) => setTimeout(r, pollInterval));
+        await sleep(pollInterval, signal);
     }
-    throw new Error(`Kie task timed out after ${maxAttempts * pollInterval}ms`);
+    const timeoutSeconds = (maxAttempts * pollInterval) / 1000;
+    throw new Error(`Kie task timed out after ${timeoutSeconds}s (taskId: ${taskId}). ` +
+        "The job may still complete on KIE — check recordInfo or the KIE dashboard.");
 }
-async function downloadResultBytes(apiKey, taskId) {
+/**
+ * Wait for a KIE task to complete: use webhook if KIE_WEBHOOK_URL is set,
+ * otherwise fall back to polling.
+ */
+async function waitForCompletion(apiKey, taskId, pollInterval, maxAttempts, signal) {
+    if (getWebhookBaseUrl()) {
+        const timeoutMs = pollInterval * maxAttempts;
+        log.info("Waiting for KIE webhook callback", { taskId, timeoutMs });
+        await registerWebhookWait(taskId, timeoutMs, signal);
+        return;
+    }
+    await pollUntilDone(apiKey, taskId, pollInterval, maxAttempts, signal);
+}
+async function downloadResultBytes(apiKey, taskId, signal) {
     const url = `${KIE_API_BASE}/api/v1/jobs/recordInfo?taskId=${taskId}`;
-    const res = await fetch(url, { headers: headers(apiKey) });
+    const res = await fetch(url, { headers: headers(apiKey), signal });
     if (!res.ok)
         throw new Error(`Failed to get Kie result: ${res.status}`);
-    const data = (await res.json());
-    const resultJsonStr = data.data
-        ?.resultJson;
-    if (!resultJsonStr)
-        throw new Error("No resultJson in Kie response");
-    const resultData = JSON.parse(resultJsonStr);
-    const resultUrls = resultData.resultUrls;
-    if (!resultUrls?.length)
-        throw new Error("No resultUrls in Kie resultJson");
-    const dlRes = await fetch(resultUrls[0]);
+    const resultUrls = decodeKieResultUrls(await parseKieJson(res, "recordInfo"));
+    const dlRes = await safeFetch(resultUrls[0], { signal });
     if (!dlRes.ok) {
         throw new Error(`Failed to download from ${resultUrls[0]}`);
     }
     return new Uint8Array(await dlRes.arrayBuffer());
 }
-function isRecord(value) {
-    return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-function stringifyContent(value) {
-    if (typeof value === "string")
-        return value;
-    if (value == null)
-        return "";
-    return JSON.stringify(value);
+/**
+ * Submit a Suno music task to `<sunoEndpoint>` and return the task id. The Suno
+ * API is separate from the generic jobs API and always requires `callBackUrl`.
+ */
+async function submitSuno(apiKey, endpoint, input, signal) {
+    const callBackUrl = getWebhookBaseUrl()
+        ? `${getWebhookBaseUrl()}/api/kie/webhook`
+        : KIE_SUNO_CALLBACK;
+    const body = { ...input, callBackUrl };
+    const res = await fetch(`${KIE_API_BASE}${endpoint}`, {
+        method: "POST",
+        headers: headers(apiKey),
+        body: JSON.stringify(body),
+        signal
+    });
+    const data = await parseKieJson(res, "submit");
+    if (!res.ok) {
+        throw new Error(`Kie submit failed: ${res.status} ${JSON.stringify(data)}`);
+    }
+    const taskId = decodeKieTaskSubmission(data);
+    recordGenerationReceipt({ provider_request_id: taskId });
+    return taskId;
 }
-function dataUri(mimeType, data) {
-    if (typeof data === "string" && data.startsWith("data:"))
-        return data;
-    const base64 = typeof data === "string" ? data : Buffer.from(data).toString("base64");
-    return `data:${mimeType};base64,${base64}`;
+/** Poll the Suno record-info endpoint until the task reaches a terminal state. */
+async function pollSuno(apiKey, taskId, pollInterval, maxAttempts, signal) {
+    const url = `${KIE_API_BASE}/api/v1/generate/record-info?taskId=${taskId}`;
+    const failed = new Set([
+        "CREATE_TASK_FAILED",
+        "GENERATE_AUDIO_FAILED",
+        "CALLBACK_EXCEPTION",
+        "SENSITIVE_WORD_ERROR"
+    ]);
+    for (let i = 0; i < maxAttempts; i++) {
+        const res = await fetch(url, { headers: headers(apiKey), signal });
+        const data = await parseKieJson(res, "record-info");
+        const status = data.data?.status;
+        if (status === "SUCCESS")
+            return data;
+        if (failed.has(status)) {
+            throw new Error(`Kie Suno task failed: ${status} (taskId: ${taskId})`);
+        }
+        await sleep(pollInterval, signal);
+    }
+    const timeoutSeconds = (maxAttempts * pollInterval) / 1000;
+    throw new Error(`Kie Suno task timed out after ${timeoutSeconds}s (taskId: ${taskId}). ` +
+        "The job may still complete on KIE — check record-info or the KIE dashboard.");
 }
 const KIE_MANIFEST_PKG = "@nodetool-ai/kie-nodes";
 const KIE_MANIFEST_PATH = "kie-manifest.json";
@@ -152,24 +664,22 @@ export class KieProvider extends BaseProvider {
         return this.apiKey;
     }
     makeOpenAIProvider(basePath) {
-        const provider = new OpenAIProvider({ OPENAI_API_KEY: this.requireApiKey() }, {
+        return new OpenAIProvider({ OPENAI_API_KEY: this.requireApiKey() }, {
+            providerId: "kie",
             clientFactory: (apiKey) => new OpenAI({
                 apiKey,
                 baseURL: `${KIE_API_BASE}${basePath}`
             })
         });
-        provider.provider = "kie";
-        return provider;
     }
     makeAnthropicProvider(basePath) {
-        const provider = new AnthropicProvider({ ANTHROPIC_API_KEY: this.requireApiKey() }, {
+        return new AnthropicProvider({ ANTHROPIC_API_KEY: this.requireApiKey() }, {
+            providerId: "kie",
             clientFactory: (apiKey) => new Anthropic({
                 authToken: apiKey,
                 baseURL: `${KIE_API_BASE}${basePath}`
             })
         });
-        provider.provider = "kie";
-        return provider;
     }
     makeResponsesClient(basePath) {
         return new OpenAI({
@@ -215,93 +725,11 @@ export class KieProvider extends BaseProvider {
         }
         yield* this.generateResponseMessages(args, model.basePath);
     }
-    async responseInputContent(content) {
-        if (content.type === "text") {
-            return { type: "input_text", text: content.text };
-        }
-        if (content.type === "image_url") {
-            const image = content.image;
-            if (image.uri) {
-                const resolved = await this.resolveUri(image.uri);
-                return { type: "input_image", image_url: resolved };
-            }
-            if (image.data) {
-                return {
-                    type: "input_image",
-                    image_url: dataUri(image.mimeType ?? "image/jpeg", image.data)
-                };
-            }
-        }
-        return null;
-    }
-    async messagesToResponsesInput(messages) {
-        const input = [];
-        for (const message of messages) {
-            if (message.role === "tool") {
-                input.push({
-                    type: "function_call_output",
-                    call_id: message.toolCallId ?? "",
-                    output: stringifyContent(message.content)
-                });
-                continue;
-            }
-            if (message.role === "assistant") {
-                const text = stringifyContent(message.content);
-                if (text) {
-                    input.push({
-                        type: "message",
-                        role: "assistant",
-                        content: [{ type: "output_text", text }]
-                    });
-                }
-                for (const toolCall of message.toolCalls ?? []) {
-                    input.push({
-                        type: "function_call",
-                        id: toolCall.id,
-                        call_id: toolCall.id,
-                        name: toolCall.name,
-                        arguments: JSON.stringify(toolCall.args ?? {})
-                    });
-                }
-                continue;
-            }
-            const content = [];
-            if (typeof message.content === "string") {
-                content.push({ type: "input_text", text: message.content });
-            }
-            else if (Array.isArray(message.content)) {
-                for (const part of message.content) {
-                    const converted = await this.responseInputContent(part);
-                    if (converted)
-                        content.push(converted);
-                }
-            }
-            if (content.length === 0)
-                continue;
-            input.push({ role: message.role, content });
-        }
-        return input;
-    }
-    responseTools(tools = []) {
-        return tools.map((tool) => ({
-            type: "function",
-            name: tool.name,
-            description: tool.description ?? "",
-            parameters: tool.inputSchema ?? { type: "object", properties: {} }
-        }));
-    }
-    responseToolChoice(toolChoice) {
-        if (!toolChoice)
-            return undefined;
-        if (toolChoice === "any")
-            return "auto";
-        return { type: "function", name: toolChoice };
-    }
     async generateResponseMessage(args, basePath) {
         const client = this.makeResponsesClient(basePath);
         const request = {
             model: args.model,
-            input: await this.messagesToResponsesInput(args.messages),
+            input: await messagesToResponsesInput(args.messages, (uri) => this.resolveUri(uri)),
             stream: false
         };
         if (args.maxTokens != null)
@@ -310,19 +738,22 @@ export class KieProvider extends BaseProvider {
             request.temperature = args.temperature;
         if (args.topP != null)
             request.top_p = args.topP;
-        const tools = this.responseTools(args.tools);
+        const tools = responseTools(args.tools);
         if (tools.length > 0) {
             request.tools = tools;
-            request.tool_choice = this.responseToolChoice(args.toolChoice) ?? "auto";
+            request.tool_choice = responseToolChoice(args.toolChoice) ?? "auto";
         }
+        this.recordRequestPayload(request);
+        // SAFETY: the SDK's `create` is overloaded over a closed param interface,
+        // while this request is assembled field by field.
         const response = (await client.responses.create.call(client.responses, request, {
             signal: args.signal
         }));
-        this.trackResponseUsage(args.model, response);
-        const outputText = typeof response.output_text === "string"
+        this.trackUsage(args.model, responseUsage(response));
+        const outputText = isString(response.output_text)
             ? response.output_text
-            : this.extractResponsesText(response.output);
-        const toolCalls = this.extractResponsesToolCalls(response.output);
+            : extractResponsesText(response.output);
+        const toolCalls = extractResponsesToolCalls(response.output, this.buildToolCall.bind(this));
         return {
             role: "assistant",
             content: outputText || null,
@@ -333,7 +764,7 @@ export class KieProvider extends BaseProvider {
         const client = this.makeResponsesClient(basePath);
         const request = {
             model: args.model,
-            input: await this.messagesToResponsesInput(args.messages),
+            input: await messagesToResponsesInput(args.messages, (uri) => this.resolveUri(uri)),
             stream: true
         };
         if (args.maxTokens != null)
@@ -342,122 +773,639 @@ export class KieProvider extends BaseProvider {
             request.temperature = args.temperature;
         if (args.topP != null)
             request.top_p = args.topP;
-        const tools = this.responseTools(args.tools);
+        const tools = responseTools(args.tools);
         if (tools.length > 0) {
             request.tools = tools;
-            request.tool_choice = this.responseToolChoice(args.toolChoice) ?? "auto";
+            request.tool_choice = responseToolChoice(args.toolChoice) ?? "auto";
         }
+        this.recordRequestPayload(request);
+        // SAFETY: as above, for the streaming overload.
         const stream = (await client.responses.create.call(client.responses, request, { signal: args.signal }));
-        const pendingArgs = new Map();
-        for await (const event of stream) {
-            const type = event.type;
-            if (type === "response.output_text.delta") {
-                const chunk = {
-                    type: "chunk",
-                    content: String(event.delta ?? ""),
-                    done: false
-                };
-                yield chunk;
-                continue;
+        yield* streamResponsesEvents(stream, {
+            model: args.model,
+            buildToolCall: this.buildToolCall.bind(this),
+            onUsage: (model, usage) => this.trackUsage(model, usage)
+        });
+    }
+    async getAvailableVideoModels() {
+        return loadVideoModels(KIE_MANIFEST_PKG, KIE_MANIFEST_PATH, "kie");
+    }
+    async getAvailableImageModels() {
+        return loadImageModels(KIE_MANIFEST_PKG, KIE_MANIFEST_PATH, "kie");
+    }
+    async getAvailableTTSModels() {
+        return loadTTSModels(KIE_MANIFEST_PKG, KIE_MANIFEST_PATH, "kie");
+    }
+    async getAvailableMusicModels() {
+        return loadMusicModels(KIE_MANIFEST_PKG, KIE_MANIFEST_PATH, "kie");
+    }
+    /** Resolve poll interval and attempt count for a model's async task. */
+    pollConfig(modelId, timeoutSeconds) {
+        const meta = getManifestNodeMeta(KIE_MANIFEST_PKG, KIE_MANIFEST_PATH, modelId);
+        const pollInterval = meta?.pollInterval ?? 4000;
+        // A caller-supplied timeout wins: translate it into a bounded poll window.
+        if (timeoutSeconds != null && timeoutSeconds > 0) {
+            const maxAttempts = Math.max(1, Math.ceil((timeoutSeconds * 1000) / pollInterval));
+            return { pollInterval, maxAttempts };
+        }
+        return { pollInterval, maxAttempts: meta?.maxAttempts ?? 300 };
+    }
+    declaresField(fields, name) {
+        return fields.some((f) => f.name === name);
+    }
+    /**
+     * Per-call timeout signal (mirrors the gemini provider): threaded into the
+     * poll-loop fetches and sleeps so an expired budget aborts the in-flight
+     * request promptly instead of leaking it until the loop exhausts.
+     */
+    timeoutSignal(timeoutSeconds) {
+        return timeoutSeconds && timeoutSeconds > 0
+            ? AbortSignal.timeout(timeoutSeconds * 1000)
+            : undefined;
+    }
+    /**
+     * Generate music as an encoded audio file. The advertised KIE music models
+     * (generate-music, generate-sounds) run through the Suno API — a separate
+     * submit endpoint and record-info poll, not the generic jobs task API. A
+     * music model without Suno metadata falls back to the generic jobs path.
+     */
+    async textToMusic(params) {
+        if (!params.prompt)
+            throw new Error("Prompt is required");
+        const apiKey = this.requireApiKey();
+        const modelId = params.model.id;
+        log.debug("Kie textToMusic", { model: modelId });
+        const signal = this.timeoutSignal(params.timeoutSeconds);
+        const meta = getManifestNodeMeta(KIE_MANIFEST_PKG, KIE_MANIFEST_PATH, modelId);
+        if (meta?.useSuno && meta.sunoEndpoint) {
+            const input = this.buildSunoInput(modelId, params);
+            const taskId = await submitSuno(apiKey, meta.sunoEndpoint, input, signal);
+            const { pollInterval, maxAttempts } = this.sunoPollConfig(meta.pollInterval, meta.maxAttempts, params.timeoutSeconds);
+            if (getWebhookBaseUrl()) {
+                const timeoutMs = pollInterval * maxAttempts;
+                log.info("Waiting for KIE Suno webhook callback", { taskId, timeoutMs });
+                await registerWebhookWait(taskId, timeoutMs, signal);
+                // After webhook fires, fetch the record to download audio
+                const url = `${KIE_API_BASE}/api/v1/generate/record-info?taskId=${taskId}`;
+                const res = await fetch(url, { headers: headers(apiKey), signal });
+                const record = await parseKieJson(res, "record-info");
+                const bytes = await this.downloadSunoAudio(record, signal);
+                return { data: bytes, mimeType: sniffAudioMime(bytes) };
             }
-            if (type === "response.function_call_arguments.delta") {
-                const itemId = String(event.item_id ?? "");
-                pendingArgs.set(itemId, (pendingArgs.get(itemId) ?? "") + String(event.delta ?? ""));
-                continue;
+            const record = await pollSuno(apiKey, taskId, pollInterval, maxAttempts, signal);
+            const bytes = await this.downloadSunoAudio(record, signal);
+            return { data: bytes, mimeType: sniffAudioMime(bytes) };
+        }
+        // Fallback: a music model that doesn't route through Suno.
+        const input = { prompt: params.prompt };
+        if (params.lyrics)
+            input.lyrics = params.lyrics;
+        if (params.durationSeconds != null) {
+            input.duration = Math.round(params.durationSeconds);
+        }
+        const { pollInterval, maxAttempts } = this.pollConfig(modelId, params.timeoutSeconds);
+        const taskId = await submitTaskWithWebhook(apiKey, modelId, input, signal);
+        await waitForCompletion(apiKey, taskId, pollInterval, maxAttempts, signal);
+        const bytes = await downloadResultBytes(apiKey, taskId, signal);
+        return { data: bytes, mimeType: sniffAudioMime(bytes) };
+    }
+    /** Poll interval/attempts for a Suno task, honoring a per-call timeout. */
+    sunoPollConfig(metaPollInterval, metaMaxAttempts, timeoutSeconds) {
+        const pollInterval = metaPollInterval ?? 4000;
+        if (timeoutSeconds != null && timeoutSeconds > 0) {
+            return {
+                pollInterval,
+                maxAttempts: Math.max(1, Math.ceil((timeoutSeconds * 1000) / pollInterval))
+            };
+        }
+        return { pollInterval, maxAttempts: metaMaxAttempts ?? 120 };
+    }
+    /**
+     * Build the Suno submit body from the model's manifest fields. `generate-music`
+     * distinguishes custom mode (lyrics supplied → prompt = lyrics, style = the
+     * description) from non-custom mode (KIE auto-generates lyrics from the
+     * prompt). Required fields with a usable default (e.g. `model`) are filled.
+     */
+    buildSunoInput(modelId, params) {
+        const fields = getModelInputFields(KIE_MANIFEST_PKG, KIE_MANIFEST_PATH, modelId);
+        const has = (name) => this.declaresField(fields, name);
+        const input = {};
+        if (params.lyrics && has("customMode") && has("style")) {
+            input.customMode = true;
+            input.prompt = params.lyrics;
+            input.style = params.prompt;
+            if (has("instrumental"))
+                input.instrumental = false;
+        }
+        else {
+            if (has("customMode"))
+                input.customMode = false;
+            input.prompt = params.prompt;
+        }
+        for (const f of fields) {
+            if (f.required && input[f.name] === undefined) {
+                const d = defaultForField(f);
+                if (d !== undefined)
+                    input[f.name] = d;
             }
-            if (type === "response.function_call_arguments.done") {
-                const itemId = String(event.item_id ?? "");
-                const argsText = String(event.arguments ?? pendingArgs.get(itemId) ?? "{}");
-                pendingArgs.delete(itemId);
-                yield this.buildToolCall(itemId, String(event.name ?? ""), argsText);
+        }
+        return input;
+    }
+    /** Download the first audio track from a Suno record-info response. */
+    async downloadSunoAudio(record, signal) {
+        const response = record.data?.response;
+        const sunoData = response?.sunoData;
+        const audioUrl = sunoData?.[0]?.audioUrl;
+        if (!audioUrl)
+            throw new Error("No audioUrl in Kie Suno response");
+        const dlRes = await safeFetch(audioUrl, { signal });
+        if (!dlRes.ok) {
+            throw new Error(`Failed to download from ${audioUrl}`);
+        }
+        return new Uint8Array(await dlRes.arrayBuffer());
+    }
+    /**
+     * Generate speech as an encoded audio file. KIE runs TTS as an async job and
+     * returns a result URL (mp3); the unified TTS node consumes this encoded path
+     * rather than streaming PCM samples.
+     */
+    async textToSpeechEncoded(args) {
+        if (!args.text)
+            throw new Error("text must not be empty");
+        const input = { text: args.text };
+        if (args.voice)
+            input.voice = args.voice;
+        if (args.speed != null)
+            input.speed = args.speed;
+        log.debug("Kie textToSpeech", { model: args.model });
+        const apiKey = this.requireApiKey();
+        const { pollInterval, maxAttempts } = this.pollConfig(args.model);
+        const taskId = await submitTaskWithWebhook(apiKey, args.model, input);
+        await waitForCompletion(apiKey, taskId, pollInterval, maxAttempts);
+        const bytes = await downloadResultBytes(apiKey, taskId);
+        return { data: bytes, mimeType: sniffAudioMime(bytes) };
+    }
+    async textToVideo(params) {
+        if (!params.prompt)
+            throw new Error("Prompt is required");
+        const modelId = params.model.id;
+        const fields = getModelInputFields(KIE_MANIFEST_PKG, KIE_MANIFEST_PATH, modelId);
+        const input = { prompt: params.prompt };
+        if (params.aspectRatio)
+            input.aspect_ratio = params.aspectRatio;
+        this.applyVideoDuration(input, fields, params);
+        this.applyRequiredDefaults(input, fields);
+        this.clampToDeclaredMax(input, fields);
+        log.debug("Kie textToVideo", { model: modelId });
+        const apiKey = this.requireApiKey();
+        const signal = this.timeoutSignal(params.timeoutSeconds);
+        const { pollInterval, maxAttempts } = this.pollConfig(modelId, params.timeoutSeconds);
+        const taskId = await submitTaskWithWebhook(apiKey, modelId, input, signal);
+        await waitForCompletion(apiKey, taskId, pollInterval, maxAttempts, signal);
+        return downloadResultBytes(apiKey, taskId, signal);
+    }
+    /**
+     * Set the request `duration` from the caller's requested seconds (preferring
+     * `durationSeconds`, falling back to `numFrames`/24), coerced to the model's
+     * declared field type. A declared schema with no `duration` field sends
+     * nothing; an unknown model keeps the historical numeric behavior.
+     */
+    /**
+     * Fill required fields the model declares but nothing else set, using the
+     * manifest's declared default.
+     *
+     * Kie rejects a task with `500 "This field is required"` when a declared
+     * required field is absent — it does not fall back to the documented default
+     * itself. `kling-2.6/image-to-video` requires `sound` (default false), which
+     * no param maps to, so an image-to-video task failed outright.
+     *
+     * Only fields the manifest marks required AND gives a default are filled, so
+     * this cannot invent a value the model never described.
+     */
+    /**
+     * Trim string inputs to the length the manifest declares for them.
+     *
+     * Kie rejects an over-long field with `500 {"msg":"The text length cannot
+     * exceed the maximum limit"}` — no field name, no limit, no actual length.
+     * The manifest already carries the cap (Kling 2.6's `prompt` is capped at
+     * 1000), so the ceiling is known here and there is no reason to spend a
+     * round trip discovering it.
+     *
+     * Composed prompts are what hit this: `composeShotPrompt` concatenates a
+     * shot's action, camera, motion and the screenplay's style bible, and a
+     * verbose director clears 1000 characters without trying. Truncation is on a
+     * word boundary and always logged with both lengths — silently reshaping
+     * someone's prompt is worse than the 500 it replaces.
+     */
+    clampToDeclaredMax(input, fields) {
+        for (const field of fields) {
+            const max = field.max;
+            if (max === undefined || max <= 0)
                 continue;
-            }
-            if (type === "response.completed") {
-                const response = event.response;
-                if (isRecord(response))
-                    this.trackResponseUsage(args.model, response);
-                const chunk = { type: "chunk", content: "", done: true };
-                yield chunk;
+            const value = input[field.name];
+            if (!isString(value) || value.length <= max)
                 continue;
-            }
-            if (type === "response.failed" || type === "response.error") {
-                throw new Error(`Kie responses stream failed: ${JSON.stringify(event)}`);
-            }
+            const cut = value.slice(0, max);
+            const lastSpace = cut.lastIndexOf(" ");
+            input[field.name] = (lastSpace > max * 0.6 ? cut.slice(0, lastSpace) : cut).trimEnd();
+            log.warn("Kie input truncated to the manifest's declared maximum", {
+                field: field.name,
+                max,
+                originalLength: value.length
+            });
         }
     }
-    extractResponsesText(output) {
-        if (!Array.isArray(output))
-            return "";
-        const parts = [];
-        for (const item of output) {
-            if (!isRecord(item) || item.type !== "message" || !Array.isArray(item.content)) {
+    applyRequiredDefaults(input, fields) {
+        for (const field of fields) {
+            if (!field.required)
                 continue;
-            }
-            for (const content of item.content) {
-                if (isRecord(content) && content.type === "output_text") {
-                    parts.push(String(content.text ?? ""));
-                }
-            }
+            if (field.default === undefined)
+                continue;
+            if (input[field.name] !== undefined)
+                continue;
+            input[field.name] = field.default;
         }
-        return parts.join("");
     }
-    extractResponsesToolCalls(output) {
-        if (!Array.isArray(output))
-            return [];
-        const toolCalls = [];
-        for (const item of output) {
-            if (!isRecord(item) || item.type !== "function_call")
+    /**
+     * Refuse a call whose required text field is blank, naming the field and the
+     * model.
+     *
+     * Kie answers one with `500 {"msg":"This field is required"}` — no field, no
+     * model, and by then the rest of the graph has been paid for. Reaching it is
+     * easy from a generic node: `nodetool.video.ImageToVideo` treats `prompt` as
+     * optional because Veo 3.1 does, so pointing the same node at
+     * `kling-2.6/image-to-video` sends a blank one. `applyRequiredDefaults` does
+     * not save it — the manifest's declared default for such a field is `""`,
+     * which is the value the endpoint rejects.
+     *
+     * Text only. A required media field arrives under its upload descriptor's API
+     * name (`images` is sent as `image_urls`), so reading it off the input bag
+     * under the manifest's name would refuse a call that is correctly formed.
+     */
+    assertRequiredTextFields(input, fields, modelId) {
+        for (const field of fields) {
+            if (!field.required || field.type !== "str")
+                continue;
+            const value = input[field.name];
+            if (isString(value) && value.trim().length > 0)
                 continue;
-            toolCalls.push(this.buildToolCall(String(item.call_id ?? item.id ?? ""), String(item.name ?? ""), item.arguments));
+            throw new Error(`Kie model "${modelId}" requires "${field.name}", which is empty. ` +
+                `Set the node's "${field.name}" property (or wire it), or choose a ` +
+                "model that does not require it.");
         }
-        return toolCalls;
     }
-    trackResponseUsage(model, response) {
-        const usage = response.usage;
-        if (!isRecord(usage))
+    applyVideoDuration(input, fields, params) {
+        const seconds = params.durationSeconds != null
+            ? params.durationSeconds
+            : params.numFrames != null
+                ? params.numFrames / 24
+                : undefined;
+        if (seconds == null)
             return;
-        const inputTokens = Number(usage.input_tokens ?? 0);
-        const outputTokens = Number(usage.output_tokens ?? 0);
-        const details = usage.input_tokens_details;
-        const cachedTokens = isRecord(details) ? Number(details.cached_tokens ?? 0) : 0;
-        this.trackUsage(model, {
-            inputTokens: Number.isFinite(inputTokens) ? inputTokens : 0,
-            outputTokens: Number.isFinite(outputTokens) ? outputTokens : 0,
-            cachedTokens: Number.isFinite(cachedTokens) ? cachedTokens : 0
-        });
-    }
-    async getAvailableVideoModels() {
-        return loadVideoModels(KIE_MANIFEST_PKG, KIE_MANIFEST_PATH, "kie");
-    }
-    async getAvailableImageModels() {
-        return loadImageModels(KIE_MANIFEST_PKG, KIE_MANIFEST_PATH, "kie");
+        if (fields.length === 0) {
+            // Unknown model: derive a plain integer as before (ceil for a frame count,
+            // round for an explicit second count).
+            input.duration =
+                params.durationSeconds != null ? Math.round(seconds) : Math.ceil(seconds);
+            return;
+        }
+        const durationField = fields.find((f) => f.name === "duration");
+        if (!durationField)
+            return;
+        input.duration = coerceDuration(durationField, seconds);
     }
-    async textToVideo(params) {
+    async textToImage(params) {
         if (!params.prompt)
             throw new Error("Prompt is required");
+        const modelId = params.model.id;
+        const fields = getModelInputFields(KIE_MANIFEST_PKG, KIE_MANIFEST_PATH, modelId);
         const input = { prompt: params.prompt };
-        if (params.aspectRatio)
+        // Schema-driven: only send fields the model declares. No KIE model declares
+        // width/height, so those are never sent — an aspect ratio is derived instead.
+        if (params.negativePrompt && this.declaresField(fields, "negative_prompt")) {
+            input.negative_prompt = params.negativePrompt;
+        }
+        if (params.seed != null && this.declaresField(fields, "seed")) {
+            input.seed = params.seed;
+        }
+        this.applyTextToImageAspect(input, fields, params);
+        log.debug("Kie textToImage", { model: modelId });
+        const apiKey = this.requireApiKey();
+        const { pollInterval, maxAttempts } = this.pollConfig(modelId);
+        this.applyRequiredDefaults(input, fields);
+        this.clampToDeclaredMax(input, fields);
+        const taskId = await submitTaskWithWebhook(apiKey, modelId, input);
+        await waitForCompletion(apiKey, taskId, pollInterval, maxAttempts);
+        return downloadResultBytes(apiKey, taskId);
+    }
+    /**
+     * Set `aspect_ratio` when the model declares it: pass a caller-supplied ratio
+     * through if it's a declared enum value (else snap to the nearest), or derive
+     * the nearest declared ratio from width/height when no ratio was given.
+     */
+    applyTextToImageAspect(input, fields, params) {
+        const field = fields.find((f) => f.name === "aspect_ratio");
+        if (!field)
+            return;
+        const enumValues = field.enumValues;
+        if (params.aspectRatio) {
+            if (enumValues && enumValues.length > 0) {
+                input.aspect_ratio = enumValues.includes(params.aspectRatio)
+                    ? params.aspectRatio
+                    : nearestAspect(enumValues, aspectToNumber(params.aspectRatio) ?? 1);
+            }
+            else {
+                input.aspect_ratio = params.aspectRatio;
+            }
+            return;
+        }
+        if (params.width && params.height && enumValues && enumValues.length > 0) {
+            input.aspect_ratio = nearestAspect(enumValues, params.width / params.height);
+        }
+    }
+    /**
+     * Set the request's `negative_prompt` / `aspect_ratio` / `seed` from the
+     * caller only when the model declares them. Unknown models (empty schema)
+     * keep the historical behavior: send whatever the caller supplied under the
+     * conventional names.
+     */
+    applyEditOptions(input, fields, params) {
+        const declaredOrUnknown = (name) => fields.length === 0 || this.declaresField(fields, name);
+        if (params.negativePrompt && declaredOrUnknown("negative_prompt")) {
+            input.negative_prompt = params.negativePrompt;
+        }
+        if (params.aspectRatio && declaredOrUnknown("aspect_ratio")) {
             input.aspect_ratio = params.aspectRatio;
-        if (params.numFrames) {
-            input.duration = Math.ceil(params.numFrames / 24);
+        }
+        if (params.seed != null && declaredOrUnknown("seed")) {
+            input.seed = params.seed;
+        }
+    }
+    /**
+     * Edit/transform one or more source images. Uses the model's schema to route
+     * the uploaded image(s) to the correct input field — single-image models
+     * (`image_url`) and multi-image edit/composition models (`image_urls` /
+     * `image_input`) are both supported.
+     */
+    async imageToImage(images, params) {
+        const apiKey = this.requireApiKey();
+        const imageUrls = await this.uploadImages(apiKey, images);
+        if (imageUrls.length === 0) {
+            throw new Error("The input image is empty.");
         }
         const modelId = params.model.id;
-        log.debug("Kie textToVideo", { model: modelId });
-        const taskId = await submitTask(this.requireApiKey(), modelId, input);
-        await pollUntilDone(this.requireApiKey(), taskId);
-        return downloadResultBytes(this.requireApiKey(), taskId);
+        const fields = getModelInputFields(KIE_MANIFEST_PKG, KIE_MANIFEST_PATH, modelId);
+        const input = {
+            prompt: params.prompt,
+            ...this.imageInput(modelId, imageUrls)
+        };
+        this.applyEditOptions(input, fields, params);
+        log.debug("Kie imageToImage", { model: modelId, images: imageUrls.length });
+        const { pollInterval, maxAttempts } = this.pollConfig(modelId);
+        this.applyRequiredDefaults(input, fields);
+        this.clampToDeclaredMax(input, fields);
+        const taskId = await submitTaskWithWebhook(apiKey, modelId, input);
+        await waitForCompletion(apiKey, taskId, pollInterval, maxAttempts);
+        return downloadResultBytes(apiKey, taskId);
     }
-    async textToImage(params) {
-        const input = { prompt: params.prompt };
-        if (params.width)
-            input.width = params.width;
-        if (params.height)
-            input.height = params.height;
+    /**
+     * Inpaint: regenerate the masked region of one or more source images. The
+     * source image(s) route to the model's primary image field; the mask routes
+     * to whatever mask field the model's schema declares (falling back to
+     * `mask_url`).
+     */
+    async inpaint(images, params) {
+        const apiKey = this.requireApiKey();
+        const imageUrls = await this.uploadImages(apiKey, images);
+        if (imageUrls.length === 0) {
+            throw new Error("The input image is empty.");
+        }
         const modelId = params.model.id;
-        log.debug("Kie textToImage", { model: modelId });
-        const taskId = await submitTask(this.requireApiKey(), modelId, input);
-        await pollUntilDone(this.requireApiKey(), taskId);
-        return downloadResultBytes(this.requireApiKey(), taskId);
+        const fields = getModelInputFields(KIE_MANIFEST_PKG, KIE_MANIFEST_PATH, modelId);
+        const input = {
+            prompt: params.prompt,
+            ...this.imageInput(modelId, imageUrls)
+        };
+        this.applyEditOptions(input, fields, params);
+        if (params.mask && params.mask.length > 0) {
+            const [maskUrl] = await this.uploadImages(apiKey, [params.mask]);
+            if (maskUrl) {
+                const maskField = selectMaskImageInput(getModelImageInputs(KIE_MANIFEST_PKG, KIE_MANIFEST_PATH, modelId));
+                const fieldName = maskField?.apiName ?? "mask_url";
+                input[fieldName] = maskField?.isList ? [maskUrl] : maskUrl;
+            }
+        }
+        log.debug("Kie inpaint", { model: modelId, images: imageUrls.length });
+        const { pollInterval, maxAttempts } = this.pollConfig(modelId);
+        this.applyRequiredDefaults(input, fields);
+        this.clampToDeclaredMax(input, fields);
+        const taskId = await submitTaskWithWebhook(apiKey, modelId, input);
+        await waitForCompletion(apiKey, taskId, pollInterval, maxAttempts);
+        return downloadResultBytes(apiKey, taskId);
+    }
+    /**
+     * Animate one or more source images into a video. The model schema decides
+     * whether the frame goes to a single field (`image_url`) or a list.
+     */
+    async imageToVideo(image, params) {
+        const selected = loadVideoModels(KIE_MANIFEST_PKG, KIE_MANIFEST_PATH, "kie")
+            .find((model) => model.id === params.model.id);
+        if (selected && !selected.supportedTasks?.includes("image_to_video")) {
+            throw new Error(`Kie model ${params.model.id} does not support image_to_video`);
+        }
+        const apiKey = this.requireApiKey();
+        const signal = this.timeoutSignal(params.timeoutSeconds);
+        const imageUrls = await this.uploadImages(apiKey, [image], signal);
+        if (imageUrls.length === 0) {
+            throw new Error("The input image is empty.");
+        }
+        const modelId = params.model.id;
+        const fields = getModelInputFields(KIE_MANIFEST_PKG, KIE_MANIFEST_PATH, modelId);
+        const input = this.imageInput(modelId, imageUrls);
+        if (params.prompt)
+            input.prompt = params.prompt;
+        this.applyEditOptions(input, fields, params);
+        this.applyVideoDuration(input, fields, params);
+        this.applyRequiredDefaults(input, fields);
+        this.clampToDeclaredMax(input, fields);
+        this.assertRequiredTextFields(input, fields, modelId);
+        log.debug("Kie imageToVideo", { model: modelId, images: imageUrls.length });
+        const { pollInterval, maxAttempts } = this.pollConfig(modelId, params.timeoutSeconds);
+        const taskId = await submitTaskWithWebhook(apiKey, modelId, input, signal);
+        await waitForCompletion(apiKey, taskId, pollInterval, maxAttempts, signal);
+        return downloadResultBytes(apiKey, taskId, signal);
+    }
+    async extendVideo(video, params) {
+        if (video.length === 0) {
+            throw new Error("The input video is empty.");
+        }
+        const modelId = params.model.id;
+        const selected = loadVideoModels(KIE_MANIFEST_PKG, KIE_MANIFEST_PATH, "kie").find((model) => model.id === modelId);
+        if (!selected?.supportedTasks?.includes("extend_video")) {
+            throw new Error(`Kie model ${modelId} does not support extend_video`);
+        }
+        if (!selected.supportedTasks.includes(`extend_video_${params.mode}`)) {
+            throw new Error(`Kie model ${modelId} does not support ${params.mode} extension`);
+        }
+        if (!Number.isFinite(params.durationSeconds) ||
+            params.durationSeconds <= 0 ||
+            (selected.durations?.length &&
+                !selected.durations.includes(params.durationSeconds))) {
+            throw new Error("Choose a supported extension duration.");
+        }
+        const fields = getModelInputFields(KIE_MANIFEST_PKG, KIE_MANIFEST_PATH, modelId);
+        const durationField = fields.find((field) => field.name === "duration");
+        if ((durationField?.min !== undefined &&
+            params.durationSeconds < durationField.min) ||
+            (durationField?.max !== undefined &&
+                params.durationSeconds > durationField.max)) {
+            throw new Error("Choose an extension duration within the model's supported range.");
+        }
+        const promptField = fields.find((field) => field.name === "prompt");
+        if (promptField?.required && !params.prompt.trim()) {
+            throw new Error(`Kie model ${modelId} requires a prompt`);
+        }
+        const videoField = getModelMediaInputs(KIE_MANIFEST_PKG, KIE_MANIFEST_PATH, modelId).find((field) => field.kind === "video");
+        if (!videoField) {
+            throw new Error(`Kie model ${modelId} does not accept a source video`);
+        }
+        const qualityField = fields.find((field) => field.name === "quality");
+        const quality = qualityField?.enumValues?.includes("720p")
+            ? "720p"
+            : qualityField?.enumValues?.[0];
+        if (qualityField?.required && !quality) {
+            throw new Error(`Kie model ${modelId} does not declare a usable quality`);
+        }
+        const apiKey = this.requireApiKey();
+        const videoUrl = await uploadMediaBytes(apiKey, video, undefined, "video");
+        const input = {
+            [videoField.apiName]: videoField.isList ? [videoUrl] : videoUrl,
+            prompt: params.prompt
+        };
+        this.applyVideoDuration(input, fields, params);
+        if (quality) {
+            input.quality = quality;
+        }
+        this.clampToDeclaredMax(input, fields);
+        log.debug("Kie extendVideo", { model: modelId, mode: params.mode });
+        const { pollInterval, maxAttempts } = this.pollConfig(modelId);
+        const taskId = await submitTaskWithWebhook(apiKey, modelId, input);
+        await waitForCompletion(apiKey, taskId, pollInterval, maxAttempts);
+        return downloadResultBytes(apiKey, taskId);
+    }
+    /**
+     * Upscale a video. The clip uploads to the model's declared video field and
+     * the requested size is written to whichever of `upscale_factor` /
+     * `resolution` the schema declares — Kie's two upscalers take one each.
+     */
+    async upscaleVideo(video, params) {
+        if (video.length === 0) {
+            throw new Error("The input video is empty.");
+        }
+        const modelId = params.model.id;
+        const supported = loadVideoModels(KIE_MANIFEST_PKG, KIE_MANIFEST_PATH, "kie")
+            .find((model) => model.id === modelId)
+            ?.supportedTasks;
+        if (supported && !supported.includes("upscale_video")) {
+            throw new Error(`Kie model ${modelId} does not support upscale_video`);
+        }
+        const apiKey = this.requireApiKey();
+        const signal = this.timeoutSignal(params.timeoutSeconds);
+        const videoUrl = await uploadMediaBytes(apiKey, video, signal, "video");
+        const fields = getModelInputFields(KIE_MANIFEST_PKG, KIE_MANIFEST_PATH, modelId);
+        const videoField = getModelMediaInputs(KIE_MANIFEST_PKG, KIE_MANIFEST_PATH, modelId)
+            .find((field) => field.kind === "video");
+        const input = {
+            [videoField?.apiName ?? "video_url"]: videoField?.isList
+                ? [videoUrl]
+                : videoUrl
+        };
+        if (params.scale != null && this.declaresField(fields, "upscale_factor")) {
+            input.upscale_factor = params.scale;
+        }
+        if (params.targetResolution &&
+            this.declaresField(fields, "resolution")) {
+            input.resolution = params.targetResolution;
+        }
+        this.applyEditOptions(input, fields, params);
+        this.applyRequiredDefaults(input, fields);
+        this.clampToDeclaredMax(input, fields);
+        log.debug("Kie upscaleVideo", { model: modelId });
+        const { pollInterval, maxAttempts } = this.pollConfig(modelId, params.timeoutSeconds);
+        const taskId = await submitTaskWithWebhook(apiKey, modelId, input, signal);
+        await waitForCompletion(apiKey, taskId, pollInterval, maxAttempts, signal);
+        return downloadResultBytes(apiKey, taskId, signal);
+    }
+    async referenceToVideo(inputs, params) {
+        const images = inputs.images.filter((b) => b.length > 0);
+        const videos = inputs.videos.filter((b) => b.length > 0);
+        if (images.length === 0 && videos.length === 0)
+            throw new Error("reference_to_video requires at least one reference image or video");
+        const apiKey = this.requireApiKey();
+        const signal = combineSignals(params.signal, this.timeoutSignal(params.timeoutSeconds));
+        if (params.useReferenceVideoAudio === true && videos.length === 0)
+            throw new Error(`Kie model ${params.model.id} requires a reference video when audio is enabled`);
+        if (!(loadVideoModels(KIE_MANIFEST_PKG, KIE_MANIFEST_PATH, "kie").find((m) => m.id === params.model.id)?.supportedTasks?.includes("reference_to_video") ?? false))
+            throw new Error(`Kie model ${params.model.id} does not support reference_to_video`);
+        const referenceFields = getModelReferenceInputs(KIE_MANIFEST_PKG, KIE_MANIFEST_PATH, params.model.id);
+        // H3's generated minimum describes clip duration (2 seconds), not video count.
+        if (params.model.id === "minimax-h3/reference-to-video") {
+            for (const field of referenceFields) {
+                if (field.kind === "video")
+                    delete field.min;
+            }
+        }
+        validateReferenceInputs("Kie", params.model.id, inputs, referenceFields);
+        const imageField = referenceFields.find((f) => f.kind === "image");
+        const videoField = referenceFields.find((f) => f.kind === "video");
+        const fieldsForModel = getModelInputFields(KIE_MANIFEST_PKG, KIE_MANIFEST_PATH, params.model.id);
+        if (params.useReferenceVideoAudio === true && !fieldsForModel.some((field) => field.name === "use_reference_video_audio")) {
+            throw new Error(`Kie model ${params.model.id} does not support reference video audio`);
+        }
+        signal?.throwIfAborted();
+        const [imageUrls, videoUrls] = await Promise.all([
+            Promise.all(images.map((b) => uploadMediaBytes(apiKey, b, signal, "image"))),
+            Promise.all(videos.map((b) => uploadMediaBytes(apiKey, b, signal, "video")))
+        ]);
+        const input = {};
+        if (imageField && imageUrls.length > 0)
+            input[imageField.apiName] = imageField.isList ? imageUrls : imageUrls[0];
+        if (videoField && videoUrls.length > 0)
+            input[videoField.apiName] = videoField.isList ? videoUrls : videoUrls[0];
+        if (params.prompt)
+            input.prompt = params.prompt;
+        if (params.negativePrompt && fieldsForModel.some((f) => f.name === "negative_prompt"))
+            input.negative_prompt = params.negativePrompt;
+        this.applyEditOptions(input, fieldsForModel, params);
+        if (params.useReferenceVideoAudio === true) {
+            input.use_reference_video_audio = true;
+        }
+        this.applyVideoDuration(input, fieldsForModel, params);
+        this.applyRequiredDefaults(input, fieldsForModel);
+        this.assertRequiredTextFields(input, fieldsForModel, params.model.id);
+        const taskId = await submitTaskWithWebhook(apiKey, params.model.id, input, signal);
+        const polling = this.pollConfig(params.model.id, params.timeoutSeconds);
+        await waitForCompletion(apiKey, taskId, polling.pollInterval, polling.maxAttempts, signal);
+        return downloadResultBytes(apiKey, taskId, signal);
+    }
+    /**
+     * Map uploaded image URLs to the model's declared input field. Single-image
+     * models get `image_url` (string); multi-image models get `image_urls` /
+     * `image_input` (array). Falls back to KIE's conventions for unknown models.
+     */
+    imageInput(modelId, urls) {
+        const field = selectPrimaryImageInput(getModelImageInputs(KIE_MANIFEST_PKG, KIE_MANIFEST_PATH, modelId), urls.length);
+        if (field) {
+            return { [field.apiName]: field.isList ? urls : urls[0] };
+        }
+        return urls.length === 1
+            ? { image_url: urls[0] }
+            : { image_urls: urls };
+    }
+    /** Upload every non-empty image to KIE's file store, returning hosted URLs. */
+    async uploadImages(apiKey, images, signal) {
+        const valid = images.filter((b) => b && b.length > 0);
+        return Promise.all(valid.map((b) => uploadImageBytes(apiKey, b, signal)));
     }
 }
 //# sourceMappingURL=kie-provider.js.map