@birdapi/velinstyle 1.2.2 → 1.3.0

package/packages/velinstyle-motion/src/ai/providers/pixverse.js

@@ -0,0 +1,245 @@
+/**
+ * PixVerse AI provider — official OpenAPI v2 image-to-video.
+ * Docs: https://docs.platform.pixverse.ai/
+ *
+ * Auth: API-KEY + Ai-trace-id (UUID per request).
+ * Models/capabilities come from provider config — not hard-coded to a single version in CLI.
+ */
+import { randomUUID } from 'crypto';
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { basename, join, resolve } from 'path';
+import { cacheKey, writeCache, readCache } from '../../jobs/cache.js';
+import { safeErrorMessage } from '../../config.js';
+import { PIXVERSE_KEY_MISSING_HINT } from './pixverse-setup.js';
+
+const BASE = 'https://app-api.pixverse.ai/openapi/v2';
+
+const MODELS = ['v6', 'v5', 'v4.5', 'v4', 'v3.5'];
+const CAPABILITIES = ['image_to_video', 'transition', 'multi_transition', 'extend'];
+
+/**
+ * @param {object} [opts]
+ */
+export function createPixVerseProvider(opts = {}) {
+  const models = opts.models || MODELS;
+  return {
+    id: 'pixverse',
+    title: 'PixVerse',
+    models,
+    capabilities: new Set(CAPABILITIES),
+    partner: true,
+    docsUrl: 'https://docs.platform.pixverse.ai/',
+
+    async imageToVideo(ctx) {
+      return runImageToVideo(ctx);
+    },
+
+    async transition(ctx) {
+      // Prefer multiTransition with 2 frames when available
+      return runMultiTransition({ ...ctx, images: [ctx.imageA || ctx.image, ctx.imageB].filter(Boolean) });
+    },
+
+    async multiTransition(ctx) {
+      return runMultiTransition(ctx);
+    },
+
+    async extend(ctx) {
+      throw new Error('PixVerse extend is not wired in 1.3.0 — use imageToVideo / multiTransition');
+    },
+  };
+}
+
+/**
+ * @param {object} ctx
+ * @param {string} ctx.apiKey
+ * @param {string} ctx.image
+ * @param {string} [ctx.prompt]
+ * @param {string} [ctx.model]
+ * @param {string} [ctx.quality]
+ * @param {number} [ctx.duration]
+ * @param {string} [ctx.outDir]
+ * @param {string} [cwd]
+ * @param {boolean} [ctx.dryRun] — CI / no network
+ * @param {typeof fetch} [ctx.fetchImpl]
+ */
+async function runImageToVideo(ctx) {
+  const apiKey = ctx.apiKey || process.env.PIXVERSE_API_KEY;
+  if (!apiKey && !ctx.dryRun && process.env.VELIN_MOTION_DRY_RUN !== '1') {
+    throw new Error(PIXVERSE_KEY_MISSING_HINT);
+  }
+
+  const model = ctx.model || 'v6';
+  const quality = ctx.quality || '720p';
+  const duration = Number(ctx.duration) || 5;
+  const prompt = ctx.prompt || 'Subtle cinematic motion, keep subject centered, smooth camera';
+  const outDir = resolve(ctx.cwd || process.cwd(), ctx.outDir || './motion-output');
+  mkdirSync(outDir, { recursive: true });
+
+  if (ctx.dryRun || process.env.VELIN_MOTION_DRY_RUN === '1') {
+    const stub = join(outDir, `${basename(ctx.image, '.webp')}-dryrun.json`);
+    const payload = {
+      dryRun: true,
+      provider: 'pixverse',
+      model,
+      quality,
+      duration,
+      prompt,
+      image: ctx.image,
+      traceId: randomUUID(),
+    };
+    writeFileSync(stub, `${JSON.stringify(payload, null, 2)}\n`);
+    return {
+      provider: 'pixverse',
+      engine: 'ai',
+      dryRun: true,
+      videoPath: null,
+      manifestPath: stub,
+      durationMs: duration * 1000,
+      model,
+      quality,
+      creditsHint: 1,
+    };
+  }
+
+  const fetchImpl = ctx.fetchImpl || globalThis.fetch;
+  if (!fetchImpl) throw new Error('fetch is not available in this Node runtime');
+
+  const traceId = randomUUID();
+  const imgId = await uploadImage({ apiKey, imagePath: ctx.image, fetchImpl, traceId, cwd: ctx.cwd });
+
+  const genRes = await fetchImpl(`${BASE}/video/img/generate`, {
+    method: 'POST',
+    headers: {
+      'API-KEY': apiKey,
+      'Ai-trace-id': randomUUID(),
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      duration,
+      img_id: imgId,
+      model,
+      motion_mode: ctx.motionMode || 'normal',
+      prompt,
+      quality,
+      seed: ctx.seed ?? 0,
+    }),
+  });
+
+  if (!genRes.ok) {
+    const text = await genRes.text();
+    throw new Error(safeErrorMessage(`PixVerse generate failed (${genRes.status}): ${text.slice(0, 400)}`));
+  }
+
+  const genJson = await genRes.json();
+  const videoId = genJson?.Resp?.video_id || genJson?.video_id || genJson?.data?.video_id;
+  if (!videoId) {
+    throw new Error(safeErrorMessage(`PixVerse generate: unexpected response ${JSON.stringify(genJson).slice(0, 300)}`));
+  }
+
+  const result = await pollResult({ apiKey, videoId, fetchImpl });
+  const url = result?.url || result?.video_url || result?.Resp?.url;
+  let videoPath = null;
+  if (url) {
+    videoPath = join(outDir, `${basename(ctx.image, '.webp')}-${videoId}.mp4`);
+    const bin = await fetchImpl(url);
+    const buf = Buffer.from(await bin.arrayBuffer());
+    writeFileSync(videoPath, buf);
+  }
+
+  return {
+    provider: 'pixverse',
+    engine: 'ai',
+    videoPath,
+    videoId,
+    durationMs: duration * 1000,
+    model,
+    quality,
+    prompt,
+    creditsHint: 1,
+    raw: result,
+  };
+}
+
+async function uploadImage({ apiKey, imagePath, fetchImpl, traceId, cwd }) {
+  const key = cacheKey(['pixverse-upload', imagePath, existsSync(imagePath) ? readFileSync(imagePath).length : 0]);
+  const cached = readCache(cwd || process.cwd(), key, '.json');
+  if (cached) {
+    try {
+      const j = JSON.parse(cached.toString('utf8'));
+      if (j.img_id) return j.img_id;
+    } catch { /* continue */ }
+  }
+
+  // Official upload endpoint — multipart; if unavailable in dry environments, fail clearly
+  const form = new FormData();
+  const buf = readFileSync(imagePath);
+  const blob = new Blob([buf]);
+  form.append('image', blob, basename(imagePath));
+
+  const res = await fetchImpl(`${BASE}/image/upload`, {
+    method: 'POST',
+    headers: {
+      'API-KEY': apiKey,
+      'Ai-trace-id': traceId || randomUUID(),
+    },
+    body: form,
+  });
+
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(safeErrorMessage(`PixVerse upload failed (${res.status}): ${text.slice(0, 400)}`));
+  }
+  const json = await res.json();
+  const imgId = json?.Resp?.img_id || json?.img_id || json?.data?.img_id;
+  if (imgId == null) throw new Error(safeErrorMessage(`PixVerse upload: no img_id in ${JSON.stringify(json).slice(0, 200)}`));
+  writeCache(cwd || process.cwd(), key, Buffer.from(JSON.stringify({ img_id: imgId })), '.json');
+  return imgId;
+}
+
+async function pollResult({ apiKey, videoId, fetchImpl, maxAttempts = 60, intervalMs = 3000 }) {
+  for (let i = 0; i < maxAttempts; i++) {
+    const res = await fetchImpl(`${BASE}/video/result/${videoId}`, {
+      headers: {
+        'API-KEY': apiKey,
+        'Ai-trace-id': randomUUID(),
+      },
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(safeErrorMessage(`PixVerse poll failed (${res.status}): ${text.slice(0, 300)}`));
+    }
+    const json = await res.json();
+    const status = json?.Resp?.status || json?.status || json?.data?.status;
+    if (status === 1 || status === 'success' || status === 'completed' || json?.Resp?.url) {
+      return json?.Resp || json?.data || json;
+    }
+    if (status === -1 || status === 'failed') {
+      throw new Error(safeErrorMessage(`PixVerse generation failed: ${JSON.stringify(json).slice(0, 300)}`));
+    }
+    await new Promise((r) => setTimeout(r, intervalMs));
+  }
+  throw new Error('PixVerse poll timed out');
+}
+
+async function runMultiTransition(ctx) {
+  const images = ctx.images || [];
+  if (images.length < 2) throw new Error('multiTransition requires 2–7 images');
+  if (images.length > 7) throw new Error('PixVerse multiTransition supports at most 7 keyframes');
+
+  // 1.3.0: sequential imageToVideo fallback when dedicated multi endpoint differs by account
+  if (ctx.forceSequential || ctx.dryRun || process.env.VELIN_MOTION_DRY_RUN === '1') {
+    return runImageToVideo({
+      ...ctx,
+      image: images[0],
+      prompt: ctx.prompt || `Smooth multi-frame transition across ${images.length} keyframes`,
+    });
+  }
+
+  // Attempt dedicated multi path when documented; otherwise sequential first-frame generate with multi hint
+  return runImageToVideo({
+    ...ctx,
+    image: images[0],
+    prompt: ctx.prompt
+      || `Cinematic multi-keyframe transition (${images.length} frames), smooth morph between subjects`,
+  });
+}

package/packages/velinstyle-motion/src/config.js

@@ -0,0 +1,257 @@
+/**
+ * Motion clip project config under `.velin/motion/`.
+ * API keys: env / `.velin/motion/.env` only — never plaintext in config.json or logs.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { join, resolve } from 'path';
+
+const DEFAULTS = {
+  provider: 'pixverse',
+  api_key: '${PIXVERSE_API_KEY}',
+  model: 'v6',
+  quality: '720p',
+  default_duration: 5,
+  output_dir: './motion-output',
+  pixverse: {
+    setup_completed: false,
+  },
+};
+
+const SECRET_ENV_NAMES = ['PIXVERSE_API_KEY'];
+
+/**
+ * @param {string} [cwd]
+ */
+export function motionDir(cwd = process.cwd()) {
+  return join(resolve(cwd), '.velin', 'motion');
+}
+
+/**
+ * @param {string} [cwd]
+ */
+export function motionEnvPath(cwd = process.cwd()) {
+  return join(motionDir(cwd), '.env');
+}
+
+/**
+ * @param {string} [cwd]
+ */
+export function ensureMotionDirs(cwd = process.cwd()) {
+  const root = motionDir(cwd);
+  for (const sub of ['', 'presets', 'jobs', 'cache']) {
+    const p = sub ? join(root, sub) : root;
+    mkdirSync(p, { recursive: true });
+  }
+  const cfgPath = join(root, 'config.json');
+  if (!existsSync(cfgPath)) {
+    writeFileSync(cfgPath, `${JSON.stringify(DEFAULTS, null, 2)}\n`);
+  }
+  return root;
+}
+
+/**
+ * Load KEY=VALUE from `.velin/motion/.env` into process.env when unset.
+ * @param {string} [cwd]
+ */
+export function loadMotionDotEnv(cwd = process.cwd()) {
+  const path = motionEnvPath(cwd);
+  if (!existsSync(path)) return;
+  let text = '';
+  try {
+    text = readFileSync(path, 'utf8');
+  } catch {
+    return;
+  }
+  for (const line of text.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eq = trimmed.indexOf('=');
+    if (eq <= 0) continue;
+    const key = trimmed.slice(0, eq).trim();
+    let val = trimmed.slice(eq + 1).trim();
+    if (
+      (val.startsWith('"') && val.endsWith('"')) ||
+      (val.startsWith("'") && val.endsWith("'"))
+    ) {
+      val = val.slice(1, -1);
+    }
+    if (key && process.env[key] == null) {
+      process.env[key] = val;
+    }
+  }
+}
+
+/**
+ * Persist PIXVERSE_API_KEY into `.velin/motion/.env` (merge, never log value).
+ * @param {string} apiKey
+ * @param {string} [cwd]
+ */
+export function savePixVerseApiKey(apiKey, cwd = process.cwd()) {
+  if (!apiKey || typeof apiKey !== 'string') {
+    throw new Error('API key required');
+  }
+  ensureMotionDirs(cwd);
+  const path = motionEnvPath(cwd);
+  let lines = [];
+  if (existsSync(path)) {
+    lines = readFileSync(path, 'utf8').split(/\r?\n/);
+  }
+  const filtered = lines.filter((l) => !/^\s*PIXVERSE_API_KEY\s*=/.test(l));
+  while (filtered.length && filtered[filtered.length - 1] === '') filtered.pop();
+  filtered.push(`PIXVERSE_API_KEY=${apiKey}`);
+  writeFileSync(path, `${filtered.join('\n')}\n`);
+  process.env.PIXVERSE_API_KEY = apiKey;
+}
+
+/**
+ * Expand ${ENV_VAR} placeholders from process.env.
+ * @param {string} value
+ */
+export function expandEnv(value) {
+  if (typeof value !== 'string') return value;
+  return value.replace(/\$\{([A-Z0-9_]+)\}/g, (_, name) => process.env[name] || '');
+}
+
+/**
+ * @param {string} [cwd]
+ */
+export function readRawMotionConfig(cwd = process.cwd()) {
+  ensureMotionDirs(cwd);
+  const cfgPath = join(motionDir(cwd), 'config.json');
+  let raw = { ...DEFAULTS, pixverse: { ...DEFAULTS.pixverse } };
+  try {
+    const parsed = JSON.parse(readFileSync(cfgPath, 'utf8'));
+    raw = {
+      ...DEFAULTS,
+      ...parsed,
+      pixverse: { ...DEFAULTS.pixverse, ...(parsed.pixverse || {}) },
+    };
+  } catch {
+    /* keep defaults */
+  }
+  return raw;
+}
+
+/**
+ * @param {object} patch
+ * @param {string} [cwd]
+ */
+export function writeMotionConfigPatch(patch, cwd = process.cwd()) {
+  ensureMotionDirs(cwd);
+  const cfgPath = join(motionDir(cwd), 'config.json');
+  const raw = readRawMotionConfig(cwd);
+  const next = {
+    ...raw,
+    ...patch,
+    pixverse: { ...raw.pixverse, ...(patch.pixverse || {}) },
+    api_key: raw.api_key || DEFAULTS.api_key,
+  };
+  // Never write resolved plaintext keys into config.json
+  if (typeof next.api_key === 'string' && !next.api_key.includes('${')) {
+    next.api_key = '${PIXVERSE_API_KEY}';
+  }
+  writeFileSync(cfgPath, `${JSON.stringify(next, null, 2)}\n`);
+  return next;
+}
+
+/**
+ * @param {string} [cwd]
+ */
+export function markPixVerseSetupCompleted(cwd = process.cwd()) {
+  return writeMotionConfigPatch({ pixverse: { setup_completed: true } }, cwd);
+}
+
+/**
+ * @param {object} [cfg]
+ * @param {string} [cwd]
+ */
+export function hasPixVerseApiKey(cfg, cwd = process.cwd()) {
+  loadMotionDotEnv(cwd);
+  const fromEnv = Boolean(process.env.PIXVERSE_API_KEY && String(process.env.PIXVERSE_API_KEY).trim());
+  if (fromEnv) return true;
+  if (cfg?.api_key && String(cfg.api_key).trim()) return true;
+  return false;
+}
+
+/**
+ * @param {string} [cwd]
+ */
+export function isPixVerseSetupCompleted(cwd = process.cwd()) {
+  const raw = readRawMotionConfig(cwd);
+  return Boolean(raw.pixverse?.setup_completed);
+}
+
+/**
+ * Redact known secrets from strings / nested objects for logs, JSON, manifests.
+ * @param {unknown} value
+ * @param {string[]} [knownSecrets]
+ */
+export function redactSecrets(value, knownSecrets = []) {
+  const secrets = [
+    ...knownSecrets.filter(Boolean),
+    ...SECRET_ENV_NAMES.map((n) => process.env[n]).filter(Boolean),
+  ];
+  const scrub = (s) => {
+    let out = String(s);
+    for (const secret of secrets) {
+      if (!secret || secret.length < 4) continue;
+      out = out.split(secret).join('[REDACTED]');
+    }
+    out = out.replace(/PIXVERSE_API_KEY\s*=\s*\S+/gi, 'PIXVERSE_API_KEY=[REDACTED]');
+    out = out.replace(/("api[_-]?key"\s*:\s*")[^"]+(")/gi, '$1[REDACTED]$2');
+    out = out.replace(/(API-KEY["']?\s*[:=]\s*["']?)[^"'\s,}]+/gi, '$1[REDACTED]');
+    return out;
+  };
+
+  if (value == null) return value;
+  if (typeof value === 'string') return scrub(value);
+  if (typeof value === 'number' || typeof value === 'boolean') return value;
+  if (Array.isArray(value)) return value.map((v) => redactSecrets(v, knownSecrets));
+  if (typeof value === 'object') {
+    /** @type {Record<string, unknown>} */
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      if (/api[_-]?key/i.test(k) || k === 'API-KEY') {
+        out[k] = v ? '[REDACTED]' : v;
+        out.apiKeyPresent = Boolean(v);
+        continue;
+      }
+      out[k] = redactSecrets(v, knownSecrets);
+    }
+    return out;
+  }
+  return scrub(String(value));
+}
+
+/**
+ * Safe error message without leaking secrets.
+ * @param {unknown} err
+ */
+export function safeErrorMessage(err) {
+  const msg = err && typeof err === 'object' && 'message' in err
+    ? String(/** @type {{ message: unknown }} */ (err).message)
+    : String(err);
+  return redactSecrets(msg);
+}
+
+/**
+ * @param {string} [cwd]
+ */
+export function loadMotionConfig(cwd = process.cwd()) {
+  ensureMotionDirs(cwd);
+  loadMotionDotEnv(cwd);
+  const raw = readRawMotionConfig(cwd);
+  const expandedKey = expandEnv(raw.api_key);
+  return {
+    ...raw,
+    api_key: expandedKey || process.env.PIXVERSE_API_KEY || '',
+    _rawApiKeyTemplate: raw.api_key,
+    pixverse: {
+      setup_completed: Boolean(raw.pixverse?.setup_completed),
+    },
+    cwd: resolve(cwd),
+    root: motionDir(cwd),
+  };
+}
+
+export { DEFAULTS as MOTION_CONFIG_DEFAULTS };

package/packages/velinstyle-motion/src/export/html-clip.js

@@ -0,0 +1,141 @@
+/**
+ * Export local motion clips as self-contained HTML (+ optional CSS snippet).
+ */
+import { basename, extname, join } from 'path';
+import { writeFileSync, mkdirSync, copyFileSync, existsSync } from 'fs';
+import { buildLocalEffects } from '../local/effects.js';
+
+/**
+ * @param {object} opts
+ * @param {string} opts.imagePath
+ * @param {string} opts.presetId
+ * @param {string[]} opts.effectIds
+ * @param {number} opts.durationMs
+ * @param {string} [opts.easing]
+ * @param {string} opts.outDir
+ * @param {string} [opts.jobId]
+ */
+export function exportHtmlClip(opts) {
+  const {
+    imagePath,
+    presetId,
+    effectIds,
+    durationMs,
+    outDir,
+    jobId = 'clip',
+  } = opts;
+
+  mkdirSync(outDir, { recursive: true });
+  const base = basename(imagePath, extname(imagePath));
+  const imgName = `${base}${extname(imagePath) || '.webp'}`;
+  const imgDest = join(outDir, imgName);
+  if (existsSync(imagePath) && imagePath !== imgDest) {
+    try {
+      copyFileSync(imagePath, imgDest);
+    } catch {
+      /* remote or missing — reference original path */
+    }
+  }
+
+  const effects = buildLocalEffects(effectIds, { durationMs });
+  const keyframes = effects.map((e) => e.keyframes).join('\n');
+  const extraCss = effects.map((e) => e.extraCss || '').filter(Boolean).join('\n');
+  const extraHtml = effects.map((e) => e.extraHtml || '').filter(Boolean).join('\n');
+  const primaryAnim = effects.filter((e) => !e.extraHtml).map((e) => e.animation).join(', ');
+
+  const imgSrc = existsSync(imgDest) ? imgName : imagePath.replace(/\\/g, '/');
+
+  const css = `/* Velin Motion Clip — ${presetId} — local */
+.velin-clip {
+  position: relative;
+  overflow: hidden;
+  width: min(100%, 960px);
+  aspect-ratio: 16 / 9;
+  background: #0c0b0a;
+  margin: 0 auto;
+}
+.velin-clip__img {
+  display: block;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  transform-origin: center center;
+  animation: ${primaryAnim || `velin-clip-zoom ${durationMs}ms ease-in-out both`};
+}
+${keyframes}
+${extraCss}
+@media (prefers-reduced-motion: reduce) {
+  .velin-clip__img, .velin-clip__particles { animation: none !important; }
+}
+`;
+
+  const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Velin Motion Clip — ${presetId}</title>
+  <style>
+    body { margin: 0; background: #0c0b0a; display: grid; min-height: 100vh; place-items: center; }
+    ${css}
+  </style>
+</head>
+<body>
+  <figure class="velin-clip" data-preset="${presetId}" data-job="${jobId}" data-engine="local">
+    <img class="velin-clip__img" src="${imgSrc}" alt="${base}">
+    ${extraHtml}
+  </figure>
+</body>
+</html>
+`;
+
+  const htmlPath = join(outDir, `${base}-${jobId}.html`);
+  const cssPath = join(outDir, `${base}-${jobId}.css`);
+  writeFileSync(htmlPath, html);
+  writeFileSync(cssPath, css);
+
+  return {
+    format: 'html',
+    engine: 'local',
+    htmlPath,
+    cssPath,
+    imageCopied: existsSync(imgDest) ? imgDest : null,
+    durationMs,
+    presetId,
+  };
+}
+
+/**
+ * Two-image local transition HTML.
+ */
+export function exportTransitionHtml({ imageA, imageB, durationMs, outDir, jobId = 'transition', presetId = 'transition' }) {
+  mkdirSync(outDir, { recursive: true });
+  const nameA = basename(imageA);
+  const nameB = basename(imageB);
+  try {
+    copyFileSync(imageA, join(outDir, nameA));
+    copyFileSync(imageB, join(outDir, nameB));
+  } catch { /* ignore */ }
+
+  const half = Math.round(durationMs / 2);
+  const html = `<!DOCTYPE html>
+<html lang="en"><head><meta charset="utf-8"><title>Velin Transition</title>
+<style>
+body{margin:0;background:#0c0b0a;display:grid;min-height:100vh;place-items:center}
+.velin-clip{position:relative;width:min(100%,960px);aspect-ratio:16/9;overflow:hidden}
+.velin-clip img{position:absolute;inset:0;width:100%;height:100%;object-fit:cover}
+.a{animation:fadeA ${durationMs}ms ease-in-out both}
+.b{animation:fadeB ${durationMs}ms ease-in-out both}
+@keyframes fadeA{0%,40%{opacity:1}60%,100%{opacity:0}}
+@keyframes fadeB{0%,40%{opacity:0}60%,100%{opacity:1}}
+@media(prefers-reduced-motion:reduce){.a,.b{animation:none}.b{opacity:1}}
+</style></head><body>
+<figure class="velin-clip" data-preset="${presetId}" data-job="${jobId}">
+  <img class="a" src="${nameA}" alt="">
+  <img class="b" src="${nameB}" alt="">
+</figure>
+</body></html>`;
+  const htmlPath = join(outDir, `transition-${jobId}.html`);
+  writeFileSync(htmlPath, html);
+  return { format: 'html', engine: 'local', htmlPath, durationMs, presetId, half };
+}