kingkont 0.7.39 → 0.7.41

package/lib/providers.js

@@ -0,0 +1,689 @@
+// Провайдер-агностичная библиотека генерации.
+// Используется и из HTTP-сервера (server.js), и из CLI (bin/kingkont.js).
+// Не использует req/res — только чистые функции с input → output.
+//
+// Все экспортируемые функции принимают `settings` как параметр (caller сам
+// решает откуда их взять — main.js берёт live, CLI берёт через loadSettings).
+// Прямые API-ключи (kieKey/elevenKey/openrouterKey) либо через
+// applySettingsToEnv() уже в env, либо берём напрямую из settings.
+
+'use strict';
+
+const KIE_BASE = 'https://api.kie.ai';
+const ELEVEN_BASE = 'https://api.elevenlabs.io';
+
+const CHATIUM_PATHS = {
+  text:  '/app/spaces/server/api/text',
+  audio: '/app/spaces/server/api/audio',
+  image: '/app/spaces/server/api/image',
+  video: '/app/spaces/server/api/video',
+  poll:  '/app/spaces/server/api/poll',
+  balance: '/app/spaces/server/api/balance',
+  transactions: '/app/spaces/server/api/transactions',
+  uploadUrl: '/app/spaces/server/api/upload_url',
+};
+
+const CHATIUM_CDN = 'https://fs.chatium.ru/get';
+
+// =============================================================================
+// Логирование исходящих запросов (общее для server.js и CLI).
+// =============================================================================
+
+function logCall(method, provider, target, extra = '') {
+  const ts = new Date().toLocaleTimeString();
+  console.log(`[${ts}] → ${method.padEnd(4)} ${provider.padEnd(11)} ${target}${extra ? '  ' + extra : ''}`);
+}
+
+function summarizeBody(body) {
+  if (!body) return '';
+  const parts = [];
+  if (body.model) parts.push(`model=${body.model}`);
+  if (body.kind) parts.push(`kind=${body.kind}`);
+  if (typeof body.prompt === 'string') parts.push(`prompt=${body.prompt.length}ch`);
+  if (typeof body.text === 'string') parts.push(`text=${body.text.length}ch`);
+  if (Array.isArray(body.imageInputs)) parts.push(`imgs=${body.imageInputs.length}`);
+  return parts.join(' ');
+}
+
+// =============================================================================
+// Маппинги моделей: короткий ключ → полный slug провайдера.
+// Источники: spaces/api/execImageRunners.ts, execVideoRunners.ts.
+// =============================================================================
+
+const KIE_IMAGE_MODELS = {
+  'nano-banana-2':   'nano-banana-2',
+  'grok':            'grok-imagine/text-to-image',
+  'seedream':        'seedream/4.5-text-to-image',
+  'seedream-5-lite': 'seedream/5-lite-text-to-image',
+  'flux-schnell':    'flux/schnell',
+  'sdxl-lightning':  'sdxl/lightning',
+};
+const KIE_VIDEO_MODELS = {
+  'seedance-2': 'bytedance/seedance-2',
+};
+
+const CHATIUM_IMAGE_MODELS = {
+  'nano-banana-2':    'nano-banana-2',
+  'nano-banana-pro':  'nano-banana-pro',
+  'grok':             'grok-imagine/text-to-image',
+  'grok-i2i':         'grok-imagine/image-to-image',
+  'seedream-5-lite':  'bytedance/seedream-5-lite',
+};
+const CHATIUM_VIDEO_MODELS = {
+  'seedance-2':       'bytedance/seedance-2',
+  'seedance-2-fast':  'bytedance/seedance-2-fast',
+  'veo-3.1':          'google/veo-3.1',
+  'kling-o1':         'kwaivgi/kling-o1',
+  'kling-3.0':        'kling-3.0/video',
+  'kling-v3-omni':    'kwaivgi/kling-v3-omni-video',
+  'wan-2.7-i2v':      'wan/2-7-image-to-video',
+  'runway':           'runway',
+  'grok-i2v':         'grok-imagine/image-to-video',
+  'grok-t2v':         'grok-imagine/text-to-video',
+};
+
+function resolveModel(map, key, fallback) {
+  if (!key) return fallback;
+  return map[key] || (Object.values(map).includes(key) ? key : null);
+}
+
+// =============================================================================
+// Chatium HTTP helpers (text/audio/image/video дёргают одни и те же).
+// =============================================================================
+
+function chatiumBase(s) {
+  if (!s.chatium?.base) throw new Error('Нет Chatium base URL');
+  return s.chatium.base.replace(/\/$/, '');
+}
+
+async function chatiumStart(s, kind, body) {
+  if (!s.chatium?.token) throw new Error('Нет Chatium token (войдите в KingKont в настройках)');
+  const url = chatiumBase(s) + CHATIUM_PATHS[kind];
+  logCall('POST', 'Chatium', url, summarizeBody(body));
+  const r = await fetch(url, {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${s.chatium.token}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(body),
+  });
+  const text = await r.text();
+  let data; try { data = JSON.parse(text); } catch { data = { raw: text }; }
+  if (!r.ok) {
+    const reason = data?.reason || data?.error || data?.raw || `HTTP ${r.status}`;
+    throw new Error(`Chatium /api/${kind} HTTP ${r.status}: ${String(reason).slice(0, 800)}`);
+  }
+  if (!data.taskId) throw new Error(`Chatium /api/${kind} вернул без taskId: ${text.slice(0, 200)}`);
+  return data.taskId;
+}
+
+async function chatiumPoll(s, taskId) {
+  const url = `${chatiumBase(s)}${CHATIUM_PATHS.poll}?taskId=${encodeURIComponent(taskId)}`;
+  const r = await fetch(url, { headers: { 'Authorization': `Bearer ${s.chatium.token}` } });
+  const text = await r.text();
+  let data; try { data = JSON.parse(text); } catch { data = { raw: text }; }
+  if (!r.ok) {
+    const reason = data?.reason || data?.error || data?.raw || `HTTP ${r.status}`;
+    throw new Error(`Chatium /api/poll HTTP ${r.status}: ${String(reason).slice(0, 300)}`);
+  }
+  return data;
+}
+
+/**
+ * Поллит Chatium-таск до готовности. Для media (audio/image/video) cost
+ * приходит ОТДЕЛЬНЫМ /onMediaBilled callback, иногда позже /onCompleted.
+ * Если completed но creditsCharged ещё null — даём grace-период.
+ *
+ * @returns {Promise<object>} { status, result, creditsCharged, error }
+ */
+async function chatiumWait(s, taskId, opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? 600000;            // 10 минут (для видео)
+  const billedGraceMs = opts.billedGraceMs ?? 5000;
+  const onProgress = opts.onProgress || (() => {});
+  const deadline = Date.now() + timeoutMs;
+  let lastStatus = null;
+  while (Date.now() < deadline) {
+    const d = await chatiumPoll(s, taskId);
+    if (d.status !== lastStatus) {
+      onProgress(d.status, d);
+      lastStatus = d.status;
+    }
+    if (d.status === 'completed') {
+      if (typeof d.creditsCharged === 'number') return d;
+      const graceUntil = Date.now() + billedGraceMs;
+      while (Date.now() < graceUntil) {
+        await new Promise(r => setTimeout(r, 800));
+        const d2 = await chatiumPoll(s, taskId);
+        if (typeof d2.creditsCharged === 'number') return d2;
+      }
+      return d;
+    }
+    if (d.status === 'failed') throw new Error(d.error || 'chatium task failed');
+    await new Promise(r => setTimeout(r, 1500));
+  }
+  throw new Error(`chatium poll timeout after ${timeoutMs / 1000}s`);
+}
+
+// =============================================================================
+// KIE HTTP helpers.
+// =============================================================================
+
+async function kieFetch(path, options = {}) {
+  const key = process.env.KIE_API_KEY;
+  if (!key) throw new Error('KIE_API_KEY не задан');
+  const r = await fetch(KIE_BASE + path, {
+    ...options,
+    headers: {
+      'Authorization': `Bearer ${key}`,
+      'Content-Type': 'application/json',
+      ...(options.headers || {}),
+    },
+  });
+  const text = await r.text();
+  let data; try { data = JSON.parse(text); } catch { data = { raw: text }; }
+  if (!r.ok) throw new Error(`KIE ${r.status}: ${(data.msg || text).slice(0, 300)}`);
+  if (data.code && data.code !== 200) throw new Error(`KIE: ${data.msg || 'unknown error'}`);
+  return data;
+}
+
+async function kiePoll(taskId) {
+  return await kieFetch(`/api/v1/jobs/recordInfo?taskId=${encodeURIComponent(taskId)}`);
+}
+
+// =============================================================================
+// PUBLIC API: image / video generation (async — возвращает taskId).
+// =============================================================================
+
+/**
+ * @param {object} args
+ * @param {'image'|'video'} args.kind
+ * @param {string} args.prompt
+ * @param {string} [args.modelKey]      Короткий ключ (nano-banana-2) или полный slug.
+ * @param {string[]} [args.imageInputs] URL'ы reference-картинок.
+ * @param {string[]} [args.videoInputs] URL'ы reference-видео.
+ * @param {string} [args.firstFrame]    URL первого кадра (i2v).
+ * @param {string} [args.lastFrame]     URL последнего кадра.
+ * @param {string} [args.aspectRatio]   '16:9' | '9:16' | '1:1' | ...
+ * @param {string} [args.resolution]    '720p' | '1080p' | '1K' | ...
+ * @param {number|string} [args.duration]
+ * @param {object} args.settings
+ * @returns {Promise<{ taskId: string, provider: 'kingkont'|'kie' }>}
+ */
+async function startGeneration(args) {
+  const { kind, prompt, modelKey, imageInputs, videoInputs, firstFrame, lastFrame,
+          aspectRatio, resolution, duration, settings: s } = args;
+  if (kind !== 'image' && kind !== 'video') throw new Error(`unknown kind: ${kind}`);
+  if (!prompt && kind !== 'video') throw new Error('prompt обязателен');
+
+  // Chatium-путь.
+  if (s.useChatium && s.chatium?.token && s.chatium?.base) {
+    const map = kind === 'video' ? CHATIUM_VIDEO_MODELS : CHATIUM_IMAGE_MODELS;
+    const fullModel = resolveModel(map, modelKey, kind === 'video' ? 'bytedance/seedance-2-fast' : 'nano-banana-2');
+    if (!fullModel) {
+      const known = Object.keys(map).join(', ');
+      throw new Error(`Модель "${modelKey}" не поддерживается KingKont для ${kind}. Доступны: ${known}`);
+    }
+    let body;
+    if (kind === 'video') {
+      body = { prompt, model: fullModel, imageInputs, videoInputs, firstFrame, lastFrame, aspectRatio, resolution, duration };
+    } else {
+      const isSeedream = fullModel.includes('seedream');
+      body = {
+        prompt, model: fullModel, aspectRatio, resolution,
+        outputFormat: isSeedream ? 'jpeg' : 'jpg',
+      };
+      if (!isSeedream && Array.isArray(imageInputs) && imageInputs.length) {
+        body.imageInputs = imageInputs;
+      }
+    }
+    const taskId = await chatiumStart(s, kind, body);
+    return { taskId: 'chatium:' + taskId, provider: 'kingkont' };
+  }
+
+  // KIE-путь.
+  if (!s.useKie) {
+    throw new Error(kind === 'video'
+      ? 'Войдите в KingKont или KIE для видео.'
+      : 'Войдите в KingKont или KIE для картинок.');
+  }
+  const map = kind === 'video' ? KIE_VIDEO_MODELS : KIE_IMAGE_MODELS;
+  const key = modelKey || (kind === 'video' ? 'seedance-2' : 'nano-banana-2');
+  const fullModel = map[key];
+  if (!fullModel) throw new Error(`unknown ${kind} model: ${key}`);
+
+  const input = { prompt };
+  if (kind === 'image') {
+    if (key === 'nano-banana-2') {
+      if (imageInputs?.length) input.image_input = imageInputs;
+      if (aspectRatio) input.aspect_ratio = aspectRatio;
+      input.resolution = resolution || '1K';
+      input.output_format = 'jpg';
+    } else if (key === 'grok') {
+      if (aspectRatio) input.aspect_ratio = aspectRatio;
+      input.nsfw_checker = false;
+      input.enable_pro = false;
+    } else if (key === 'seedream' || key === 'seedream-5-lite') {
+      input.aspect_ratio = aspectRatio || '16:9';
+      input.quality = 'high';
+      input.nsfw_checker = false;
+    } else if (key === 'flux-schnell' || key === 'sdxl-lightning') {
+      if (aspectRatio) input.aspect_ratio = aspectRatio;
+      input.output_format = 'jpg';
+    }
+  } else {
+    if (imageInputs?.length) input.reference_image_urls = imageInputs;
+    if (videoInputs?.length) input.reference_video_urls = videoInputs;
+    if (aspectRatio) input.aspect_ratio = aspectRatio;
+    if (resolution) input.resolution = resolution;
+    if (duration) input.duration = +duration;
+  }
+
+  logCall('POST', 'KIE', `${KIE_BASE}/api/v1/jobs/createTask`, `model=${fullModel} kind=${kind}`);
+  const data = await kieFetch('/api/v1/jobs/createTask', {
+    method: 'POST',
+    body: JSON.stringify({ model: fullModel, input }),
+  });
+  return { taskId: data.data?.taskId, provider: 'kie' };
+}
+
+/**
+ * Опросить статус таска. Возвращает унифицированный формат.
+ * @returns {Promise<{ status: 'done'|'pending'|'error', url?: string, error?: string, cost?: number, state?: string, provider: string }>}
+ */
+async function pollGeneration(taskId, settings) {
+  if (taskId.startsWith('chatium:')) {
+    const realId = taskId.slice('chatium:'.length);
+    if (!settings.chatium?.token) return { status: 'error', error: 'Нет Chatium-сессии', provider: 'kingkont' };
+    let d;
+    try { d = await chatiumPoll(settings, realId); }
+    catch (e) { return { status: 'error', error: 'KingKont: ' + e.message, provider: 'kingkont' }; }
+    if (d.status === 'completed') {
+      const url = d.result?.urls?.[0];
+      if (!url) return { status: 'error', error: 'KingKont вернул без URL', provider: 'kingkont' };
+      // Grace для billed.
+      let cost = typeof d.creditsCharged === 'number' ? d.creditsCharged : null;
+      if (cost == null) {
+        const graceUntil = Date.now() + 5000;
+        while (Date.now() < graceUntil) {
+          await new Promise(r => setTimeout(r, 800));
+          try {
+            const d2 = await chatiumPoll(settings, realId);
+            if (typeof d2.creditsCharged === 'number') { cost = d2.creditsCharged; break; }
+          } catch {}
+        }
+      }
+      return { status: 'done', url, cost, provider: 'kingkont' };
+    }
+    if (d.status === 'failed') return { status: 'error', error: d.error || 'failed', provider: 'kingkont' };
+    return { status: 'pending', state: d.status, provider: 'kingkont' };
+  }
+
+  // KIE.
+  let data;
+  try { data = await kiePoll(taskId); }
+  catch (e) { return { status: 'error', error: e.message, provider: 'kie' }; }
+  const d = data.data || {};
+  if (d.state === 'success') {
+    let urls = [];
+    try { urls = JSON.parse(d.resultJson || '{}').resultUrls || []; } catch {}
+    if (!urls.length) return { status: 'error', error: 'KIE вернул успех без URL', provider: 'kie' };
+    return { status: 'done', url: urls[0], provider: 'kie' };
+  }
+  if (d.state === 'fail') return { status: 'error', error: d.failMsg || d.failCode || 'failed', provider: 'kie' };
+  return { status: 'pending', state: d.state, provider: 'kie' };
+}
+
+/**
+ * Ждать завершения таска (для CLI). Поллит каждые 4 секунды.
+ * @returns {Promise<{ url, cost?, provider }>}
+ */
+async function waitForGeneration(taskId, settings, opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? 600000;       // 10 мин
+  const intervalMs = opts.intervalMs ?? 4000;
+  const onProgress = opts.onProgress || (() => {});
+  const deadline = Date.now() + timeoutMs;
+  let lastState = null;
+  while (Date.now() < deadline) {
+    const r = await pollGeneration(taskId, settings);
+    if (r.state !== lastState) { onProgress(r); lastState = r.state; }
+    if (r.status === 'done') return r;
+    if (r.status === 'error') throw new Error(r.error || 'generation failed');
+    await new Promise(s => setTimeout(s, intervalMs));
+  }
+  throw new Error(`Generation timeout after ${timeoutMs / 1000}s`);
+}
+
+// =============================================================================
+// PUBLIC API: text generation (sync).
+// =============================================================================
+
+/**
+ * @returns {Promise<{ text, model, cost?, provider }>}
+ */
+async function generateText({ prompt, model = 'anthropic/claude-sonnet-4', system, images, settings: s }) {
+  if (!prompt) throw new Error('нужен prompt');
+
+  if (s.useChatium && s.chatium?.token && s.chatium?.base) {
+    const body = {
+      prompt, model, system,
+      images: Array.isArray(images) ? images.filter(i => i?.url) : undefined,
+    };
+    const taskId = await chatiumStart(s, 'text', body);
+    const result = await chatiumWait(s, taskId, { timeoutMs: 120000 });
+    return {
+      text: result.result?.text || '',
+      model,
+      cost: typeof result.creditsCharged === 'number' ? result.creditsCharged : null,
+      provider: 'kingkont',
+    };
+  }
+
+  if (!s.useOpenrouter) throw new Error('Войдите в KingKont или OpenRouter для генерации текста.');
+  const key = process.env.OPENROUTER_API_KEY;
+  if (!key) throw new Error('OPENROUTER_API_KEY не задан');
+
+  const messages = [];
+  if (system) messages.push({ role: 'system', content: system });
+  if (Array.isArray(images) && images.length) {
+    const content = [{ type: 'text', text: prompt }];
+    for (const img of images) {
+      if (!img?.url) continue;
+      content.push({ type: 'image_url', image_url: { url: img.url } });
+    }
+    messages.push({ role: 'user', content });
+  } else {
+    messages.push({ role: 'user', content: prompt });
+  }
+  logCall('POST', 'OpenRouter', 'https://openrouter.ai/api/v1/chat/completions', `model=${model} prompt=${prompt.length}ch`);
+  const r = await fetch('https://openrouter.ai/api/v1/chat/completions', {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${key}`,
+      'Content-Type': 'application/json',
+      'HTTP-Referer': 'http://localhost',
+      'X-Title': 'KingKont',
+    },
+    body: JSON.stringify({ model, messages }),
+  });
+  const text = await r.text();
+  let data; try { data = JSON.parse(text); } catch { data = { raw: text }; }
+  if (!r.ok) throw new Error(data?.error?.message || data?.raw || `HTTP ${r.status}`);
+  return {
+    text: data?.choices?.[0]?.message?.content || '',
+    model: data?.model || model,
+    cost: null,
+    provider: 'openrouter',
+  };
+}
+
+// =============================================================================
+// PUBLIC API: TTS / SFX / music (sync — возвращает Buffer аудио).
+// =============================================================================
+
+const TTS_PASSTHROUGH = new Set([
+  'voice', 'voiceId', 'voice_id', 'speaker',
+  'language', 'language_code', 'language_boost',
+  'speed', 'pitch', 'volume',
+  'stability', 'similarity_boost', 'style', 'style_instruction',
+  'audio_format', 'sample_rate', 'bitrate', 'channel', 'emotion',
+  'subtitle_enable', 'english_normalization',
+  'voice_description', 'reference_audio', 'reference_text', 'mode',
+  'previous_text', 'next_text',
+]);
+
+/**
+ * @returns {Promise<{ buffer: Buffer, mime: string, cost?: number, provider: string }>}
+ */
+async function generateTts(args) {
+  const { text, settings: s } = args;
+  if (!text) throw new Error('нужен text');
+
+  const directElevenAvailable = s.useElevenlabs && process.env.ELEVENLABS_API_KEY;
+  if (s.useChatium && s.chatium?.token && s.chatium?.base && !directElevenAvailable) {
+    const body = { kind: 'tts', text };
+    if (args.ttsModel) body.model = args.ttsModel;
+    else if (args.modelId === 'eleven_v3') body.model = 'elevenlabs/v3';
+    else if (args.modelId) body.model = args.modelId;
+    if (args.voice) body.voice = args.voice;
+    else if (args.voiceId) body.voice = args.voiceId;
+    for (const k of Object.keys(args)) {
+      if (['text', 'voice', 'voiceId', 'ttsModel', 'modelId', 'settings'].includes(k)) continue;
+      if (TTS_PASSTHROUGH.has(k)) body[k] = args[k];
+    }
+    return await audioViaChatium(s, body);
+  }
+
+  if (!s.useElevenlabs) throw new Error('Войдите в KingKont или ElevenLabs для аудио.');
+  const key = process.env.ELEVENLABS_API_KEY;
+  if (!key) throw new Error('ELEVENLABS_API_KEY не задан');
+  const voiceId = args.voiceId || args.voice || 'JBFqnCBsd6RMkjVDRZzb';
+  logCall('POST', 'ElevenLabs', `${ELEVEN_BASE}/v1/text-to-speech/${voiceId}`, `model=eleven_v3 text=${text.length}ch`);
+  const r = await fetch(`${ELEVEN_BASE}/v1/text-to-speech/${voiceId}`, {
+    method: 'POST',
+    headers: { 'xi-api-key': key, 'Content-Type': 'application/json', 'Accept': 'audio/mpeg' },
+    body: JSON.stringify({ text, model_id: 'eleven_v3' }),
+  });
+  if (!r.ok) throw new Error((await r.text()).slice(0, 300));
+  const buf = Buffer.from(await r.arrayBuffer());
+  return { buffer: buf, mime: 'audio/mpeg', cost: null, provider: 'elevenlabs' };
+}
+
+async function generateSfx(args) {
+  const { text, durationSeconds, promptInfluence = 0.3, settings: s } = args;
+  if (!text) throw new Error('нужен text');
+
+  if (s.useChatium && s.chatium?.token && s.chatium?.base) {
+    return await audioViaChatium(s, { kind: 'sfx', text, durationSeconds });
+  }
+  if (!s.useElevenlabs) throw new Error('Войдите в KingKont или ElevenLabs для аудио.');
+  const key = process.env.ELEVENLABS_API_KEY;
+  if (!key) throw new Error('ELEVENLABS_API_KEY не задан');
+  const body = { text, prompt_influence: promptInfluence };
+  if (durationSeconds) body.duration_seconds = +durationSeconds;
+  logCall('POST', 'ElevenLabs', `${ELEVEN_BASE}/v1/sound-generation`, `text=${text.length}ch dur=${durationSeconds || '-'}`);
+  const r = await fetch(`${ELEVEN_BASE}/v1/sound-generation`, {
+    method: 'POST',
+    headers: { 'xi-api-key': key, 'Content-Type': 'application/json', 'Accept': 'audio/mpeg' },
+    body: JSON.stringify(body),
+  });
+  if (!r.ok) throw new Error((await r.text()).slice(0, 400));
+  return { buffer: Buffer.from(await r.arrayBuffer()), mime: 'audio/mpeg', cost: null, provider: 'elevenlabs' };
+}
+
+async function generateMusic(args) {
+  const { prompt, durationMs, settings: s } = args;
+  if (!prompt) throw new Error('нужен prompt');
+
+  if (s.useChatium && s.chatium?.token && s.chatium?.base) {
+    return await audioViaChatium(s, { kind: 'music', prompt, durationMs });
+  }
+  if (!s.useElevenlabs) throw new Error('Войдите в KingKont или ElevenLabs для аудио.');
+  const key = process.env.ELEVENLABS_API_KEY;
+  if (!key) throw new Error('ELEVENLABS_API_KEY не задан');
+  const body = { prompt };
+  if (durationMs) body.music_length_ms = +durationMs;
+  logCall('POST', 'ElevenLabs', `${ELEVEN_BASE}/v1/music`, `prompt=${prompt.length}ch dur_ms=${durationMs || '-'}`);
+  const r = await fetch(`${ELEVEN_BASE}/v1/music`, {
+    method: 'POST',
+    headers: { 'xi-api-key': key, 'Content-Type': 'application/json', 'Accept': 'audio/mpeg' },
+    body: JSON.stringify(body),
+  });
+  if (!r.ok) throw new Error((await r.text()).slice(0, 400));
+  return { buffer: Buffer.from(await r.arrayBuffer()), mime: 'audio/mpeg', cost: null, provider: 'elevenlabs' };
+}
+
+/**
+ * Внутренний helper: шлём audio-задачу в Chatium, ждём, скачиваем URL → Buffer.
+ */
+async function audioViaChatium(s, body) {
+  const taskId = await chatiumStart(s, 'audio', body);
+  const result = await chatiumWait(s, taskId, { timeoutMs: 180000 });
+  const url = result.result?.urls?.[0];
+  if (!url) throw new Error('Chatium завершил аудио-задачу без URL');
+  logCall('GET ', 'Chatium', url, '(downloading audio)');
+  const r = await fetch(url);
+  if (!r.ok) throw new Error(`download ${r.status}`);
+  const buf = Buffer.from(await r.arrayBuffer());
+  return {
+    buffer: buf,
+    mime: 'audio/mpeg',
+    cost: typeof result.creditsCharged === 'number' ? result.creditsCharged : null,
+    provider: 'kingkont',
+  };
+}
+
+// =============================================================================
+// PUBLIC API: file upload (Chatium-storage с fallback на KIE).
+// =============================================================================
+
+/**
+ * @returns {Promise<{ url, fileName, size, hash?: string, provider }>}
+ */
+async function uploadFile({ buffer, filename = 'upload.bin', mime = 'application/octet-stream', settings: s }) {
+  if (!buffer || !buffer.length) throw new Error('пустой файл');
+  if (buffer.length > 50 * 1024 * 1024) {
+    throw new Error(`файл слишком большой (${(buffer.length/1024/1024).toFixed(1)} MB), лимит 50MB`);
+  }
+
+  if (s.useChatium && s.chatium?.token && s.chatium?.base) {
+    const urlReq = chatiumBase(s) + CHATIUM_PATHS.uploadUrl;
+    const ru = await fetch(urlReq, { headers: { 'Authorization': `Bearer ${s.chatium.token}` } });
+    if (!ru.ok) throw new Error('KingKont upload-url: ' + (await ru.text()).slice(0, 200));
+    const { uploadUrl } = await ru.json();
+    if (!uploadUrl) throw new Error('KingKont не вернул uploadUrl');
+    logCall('POST', 'Chatium', uploadUrl, `file=${filename} size=${buffer.length}`);
+    const fd = new FormData();
+    fd.append('Filedata', new Blob([buffer], { type: mime }), filename);
+    const ru2 = await fetch(uploadUrl, { method: 'POST', body: fd });
+    const hash = (await ru2.text()).trim();
+    if (!ru2.ok || !hash) throw new Error(`Chatium upload HTTP ${ru2.status}: ${hash.slice(0, 200)}`);
+    return { url: `${CHATIUM_CDN}/${hash}`, fileName: filename, size: buffer.length, hash, provider: 'kingkont' };
+  }
+
+  if (!s.useKie) throw new Error('Войдите в KingKont или KIE для загрузки файлов.');
+  if (buffer.length > 10 * 1024 * 1024) {
+    throw new Error(`файл слишком большой для KIE (${(buffer.length/1024/1024).toFixed(1)} MB), лимит 10MB`);
+  }
+  const dataUrl = `data:${mime};base64,${buffer.toString('base64')}`;
+  const key = process.env.KIE_API_KEY;
+  if (!key) throw new Error('KIE_API_KEY не задан');
+  logCall('POST', 'KIE', 'https://kieai.redpandaai.co/api/file-base64-upload', `file=${filename} size=${buffer.length}`);
+  const r = await fetch('https://kieai.redpandaai.co/api/file-base64-upload', {
+    method: 'POST',
+    headers: { 'Authorization': `Bearer ${key}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ base64Data: dataUrl, uploadPath: 'images', fileName: filename }),
+  });
+  const text = await r.text();
+  let data; try { data = JSON.parse(text); } catch { data = { raw: text }; }
+  if (!r.ok || !data.success) throw new Error(data.msg || `upload failed: ${text.slice(0, 200)}`);
+  return { url: data.data.downloadUrl, fileName: data.data.fileName, size: data.data.fileSize, provider: 'kie' };
+}
+
+/** Скачать URL → Buffer (для CLI чтобы сохранить файл на диск). */
+async function downloadUrl(url) {
+  const r = await fetch(url);
+  if (!r.ok) throw new Error(`download ${r.status} for ${url.slice(0, 100)}`);
+  return Buffer.from(await r.arrayBuffer());
+}
+
+// =============================================================================
+// PUBLIC API: info (balance / transactions / voices).
+// =============================================================================
+
+async function fetchBalances(s) {
+  const out = {};
+  if (s.useChatium && s.chatium?.token && s.chatium?.base) {
+    try {
+      const r = await fetch(chatiumBase(s) + CHATIUM_PATHS.balance, {
+        headers: { 'Authorization': `Bearer ${s.chatium.token}` },
+      });
+      const d = await r.json().catch(() => ({}));
+      if (r.ok && typeof d.balance === 'number') out.kingkont = { unit: 'credits', amount: d.balance };
+    } catch {}
+  }
+  if (s.useElevenlabs && process.env.ELEVENLABS_API_KEY) {
+    try {
+      const r = await fetch(`${ELEVEN_BASE}/v1/user/subscription`, {
+        headers: { 'xi-api-key': process.env.ELEVENLABS_API_KEY },
+      });
+      const d = await r.json().catch(() => ({}));
+      if (r.ok && typeof d.character_count === 'number' && typeof d.character_limit === 'number') {
+        out.elevenlabs = {
+          unit: 'chars',
+          amount: Math.max(0, d.character_limit - d.character_count),
+          limit: d.character_limit,
+        };
+      }
+    } catch {}
+  }
+  if (s.useOpenrouter && process.env.OPENROUTER_API_KEY) {
+    try {
+      const r = await fetch('https://openrouter.ai/api/v1/credits', {
+        headers: { 'Authorization': `Bearer ${process.env.OPENROUTER_API_KEY}` },
+      });
+      const d = await r.json().catch(() => ({}));
+      if (r.ok && d.data && typeof d.data.total_credits === 'number') {
+        out.openrouter = {
+          unit: 'usd',
+          amount: Math.max(0, (d.data.total_credits || 0) - (d.data.total_usage || 0)),
+        };
+      }
+    } catch {}
+  }
+  return out;
+}
+
+async function fetchTransactions(s) {
+  if (!s.useChatium || !s.chatium?.token || !s.chatium?.base) {
+    throw new Error('KingKont не подключён');
+  }
+  const r = await fetch(chatiumBase(s) + CHATIUM_PATHS.transactions, {
+    headers: { 'Authorization': `Bearer ${s.chatium.token}` },
+  });
+  const text = await r.text();
+  let data; try { data = JSON.parse(text); } catch { data = { raw: text }; }
+  if (!r.ok) throw new Error(data?.reason || data?.error || `HTTP ${r.status}`);
+  return data;
+}
+
+async function listElevenVoices() {
+  const key = process.env.ELEVENLABS_API_KEY;
+  if (!key) throw new Error('ELEVENLABS_API_KEY не задан');
+  logCall('GET ', 'ElevenLabs', `${ELEVEN_BASE}/v1/voices`);
+  const r = await fetch(`${ELEVEN_BASE}/v1/voices`, { headers: { 'xi-api-key': key } });
+  const text = await r.text();
+  let data; try { data = JSON.parse(text); } catch { data = {}; }
+  if (!r.ok) throw new Error(data?.detail?.message || `HTTP ${r.status}`);
+  return (data.voices || []).map(v => ({
+    id: v.voice_id,
+    name: v.name,
+    category: v.category,
+    labels: v.labels || {},
+    preview: v.preview_url,
+  }));
+}
+
+module.exports = {
+  // Длительные генерации (image/video)
+  startGeneration,
+  pollGeneration,
+  waitForGeneration,
+  // Синхронные
+  generateText,
+  generateTts,
+  generateSfx,
+  generateMusic,
+  // Storage
+  uploadFile,
+  downloadUrl,
+  // Info
+  fetchBalances,
+  fetchTransactions,
+  listElevenVoices,
+  // Constants (для server.js / тестов)
+  KIE_IMAGE_MODELS,
+  KIE_VIDEO_MODELS,
+  CHATIUM_IMAGE_MODELS,
+  CHATIUM_VIDEO_MODELS,
+};