kasaframe 0.0.0-stage → 0.1.1

package/packages/gen/src/image/og.ts

@@ -0,0 +1,133 @@
+import { readKey } from "../keys.ts";
+import { KEY_BG, refJpeg } from "../media.ts";
+import type { ImageProvider, ImageRequest, RawResult } from "../types.ts";
+
+const HOST = process.env.KF_OG_HOST ?? "https://apis.opengateway.ai";
+
+// 1M 토큰당 달러. OpenAI 단가표(2026-09) — gpt-image-2 와 2.5 둘 다 같은 값이다.
+const PRICE = { textIn: 5, imageIn: 8, imageOut: 30 };
+
+// 2.5 는 background:transparent 를 직접 받는다(2026-10-08 실측, 알파 61%). 나머지는 단색 바탕 + 키잉.
+const TRANSPARENT_OK = /gpt-image-(2\.5|1\.5)/;
+
+export function costFromUsage(usage: any): number | null {
+  if (!usage) return null;
+  const inD = usage.input_tokens_details ?? {};
+  const outD = usage.output_tokens_details ?? {};
+  const imageIn = inD.image_tokens ?? 0;
+  const textIn = inD.text_tokens ?? Math.max(0, (usage.input_tokens ?? 0) - imageIn);
+  const imageOut = outD.image_tokens ?? usage.output_tokens ?? 0;
+  return (textIn * PRICE.textIn + imageIn * PRICE.imageIn + imageOut * PRICE.imageOut) / 1e6;
+}
+
+// gpt-image-2 계열이 받는 크기: 변이 16의 배수, 긴 변 3840 이하, 비율 3:1 이하, 픽셀 655,360..8,294,400.
+export function apiSize(size: string): { w: number; h: number } {
+  const m = /^(\d+)x(\d+)$/.exec(size);
+  if (!m) throw new Error(`크기는 1536x1024 꼴이어야 한다: ${size}`);
+  let w = Number(m[1]);
+  let h = Number(m[2]);
+  const ratio = Math.max(w, h) / Math.min(w, h);
+  if (ratio > 3) throw new Error(`비율 3:1 을 넘는 크기는 못 만든다: ${size}`);
+  const px = w * h;
+  const k = px < 655_360 ? Math.sqrt(655_360 / px) : px > 8_294_400 ? Math.sqrt(8_294_400 / px) : 1;
+  w *= k;
+  h *= k;
+  const longEdge = Math.max(w, h);
+  if (longEdge > 3840) {
+    w *= 3840 / longEdge;
+    h *= 3840 / longEdge;
+  }
+  const r16 = (v: number, up: boolean) => (up ? Math.ceil(v / 16) : Math.floor(v / 16)) * 16;
+  // 키운 쪽은 올림, 줄인 쪽은 내림 — 반올림하면 픽셀 한도를 살짝 넘어 400 이 난다.
+  return { w: r16(w, k >= 1), h: r16(h, k >= 1) };
+}
+
+async function call(path: string, init: RequestInit): Promise<any> {
+  const key = readKey("opengateway");
+  const r = await fetch(HOST + path, {
+    ...init,
+    headers: { Authorization: `Bearer ${key}`, ...(init.headers ?? {}) },
+  });
+  const text = await r.text();
+  if (!r.ok) {
+    // 413 은 본문이 비어 온다 — 상태 코드가 곧 원인이다.
+    const hint = r.status === 413 ? " (업로드가 크다)" : r.status === 402 ? " (OG 잔액 부족 — 충전하면 키가 자동 복구된다)" : "";
+    throw new Error(`OG ${path} ${r.status}${hint}: ${text.slice(0, 300)}`);
+  }
+  return JSON.parse(text);
+}
+
+function toRaw(j: any, model: string, params: Record<string, unknown>): RawResult {
+  const b64 = j.data?.[0]?.b64_json;
+  if (!b64) throw new Error(`OG 응답에 그림이 없다: ${JSON.stringify(j).slice(0, 200)}`);
+  const cost = costFromUsage(j.usage);
+  return {
+    bytes: Buffer.from(b64, "base64"),
+    ext: "png",
+    model,
+    seed: null,
+    costUsd: cost ?? 0,
+    costEstimated: cost === null,
+    params: { ...params, usage: j.usage },
+  };
+}
+
+export function ogImage(model = "openai/gpt-image-2.5-sunburst"): ImageProvider {
+  const nativeAlpha = TRANSPARENT_OK.test(model);
+
+  function body(o: ImageRequest) {
+    const { w, h } = apiSize(o.size);
+    const keyed = o.transparent && !nativeAlpha;
+    return {
+      keyed,
+      fields: {
+        model,
+        prompt: keyed ? `${o.prompt}\n\n${KEY_BG}` : o.prompt,
+        size: `${w}x${h}`,
+        quality: o.quality ?? "high",
+        output_format: "png",
+        n: 1,
+        ...(o.transparent && nativeAlpha ? { background: "transparent" } : {}),
+      },
+    };
+  }
+
+  return {
+    id: `og-${model.replace(/^openai\//, "")}`,
+    kind: "img",
+    model,
+    license: "OpenAI 이용약관 — 출력물 권리는 사용자에게, 상업 사용 가능",
+    region: "OG live(apis.opengateway.ai) 전 세계, 한국 사용 가능",
+    keyName: "opengateway",
+
+    async generate(o) {
+      const { keyed, fields } = body(o);
+      const j = await call("/v1/images/generations", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(fields),
+      });
+      const raw = toRaw(j, model, { ...fields, prompt: undefined });
+      if (keyed) raw.notes = ["chroma-key"];
+      return raw;
+    },
+
+    // 마스크 없는 참조 편집. 참조가 먹었는지는 usage.input_tokens_details.image_tokens 로만 알 수 있다.
+    async edit(o) {
+      if (!o.refs?.length) throw new Error("edit 에는 refs 가 필요하다");
+      const { keyed, fields } = body(o);
+      const form = new FormData();
+      for (const [k, v] of Object.entries(fields)) form.append(k, String(v));
+      const field = o.refs.length > 1 ? "image[]" : "image";
+      for (const [i, ref] of o.refs.entries()) {
+        const jpg = await refJpeg(ref);
+        form.append(field, new Blob([new Uint8Array(jpg)], { type: "image/jpeg" }), `ref${i}.jpg`);
+      }
+      const j = await call("/v1/images/edits", { method: "POST", body: form });
+      const raw = toRaw(j, model, { ...fields, prompt: undefined, refs: o.refs.length });
+      const used = j.usage?.input_tokens_details?.image_tokens ?? 0;
+      raw.notes = [...(keyed ? ["chroma-key"] : []), ...(used > 0 ? [] : ["refs-ignored"])];
+      return raw;
+    },
+  };
+}

package/packages/gen/src/index.ts

@@ -0,0 +1,18 @@
+export type { Asset, AssetKind, AssetMeta, ImageProvider, ImageRequest, ProviderInfo, RawResult, VideoProvider, VideoRequest } from "./types.ts";
+export { findKey, hasKey, MissingKeyError, readKey, whereToPut } from "./keys.ts";
+export { DEFAULT_IMAGE, imageProviders, pickImage, pickVideo, videoProviders } from "./registry.ts";
+export {
+  cacheDir,
+  cacheKey,
+  DEFAULT_IMAGE_MAX_USD,
+  DEFAULT_MAX_USD,
+  estimateImageUsd,
+  genImage,
+  genVideo,
+  NeedsApproval,
+  planVideo,
+  type GenContext,
+} from "./generate.ts";
+export { aspectOf, seam, seamFrames, still, type SeamOptions } from "./seam.ts";
+export { genSpecs, referencedIds, resolvePlan, type GenReport, type GenSpec } from "./plan.ts";
+export { retime } from "./media.ts";

package/packages/gen/src/keys.ts

@@ -0,0 +1,60 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+// 값은 이 모듈 밖으로 헤더에 실릴 때만 나간다. 오류 글에는 어디를 찾았는지만 적는다.
+const SOURCES: Record<string, { env: string[]; files: string[] }> = {
+  opengateway: { env: ["OPENGATEWAY_API_KEY", "OG_API_KEY"], files: ["~/.config/opengateway.key"] },
+  fal: { env: ["FAL_KEY"], files: ["~/.config/fal.key", "~/.secrets/gcp-sm/fal-ai-api-key"] },
+  minimax: { env: ["MINIMAX_API_KEY"], files: ["~/.config/minimax.key"] },
+  gemini: { env: ["GEMINI_API_KEY", "GOOGLE_API_KEY"], files: ["~/.config/gemini.key"] },
+  ltx: { env: ["LTX_API_KEY"], files: ["~/.config/ltx.key"] },
+  h3: { env: ["KF_H3_URL"], files: [] },
+};
+
+export class MissingKeyError extends Error {
+  keyName: string;
+  constructor(keyName: string) {
+    super(`키 없음: ${keyName} — ${whereToPut(keyName)}`);
+    this.keyName = keyName;
+  }
+}
+
+function expand(p: string): string {
+  return p.startsWith("~/") ? join(homedir(), p.slice(2)) : p;
+}
+
+function sources(name: string): { env: string[]; files: string[] } {
+  const s = SOURCES[name] ?? { env: [], files: [] };
+  return { env: s.env, files: [...s.files, `~/.config/kasaframe/keys/${name}`] };
+}
+
+export function whereToPut(name: string): string {
+  const s = sources(name);
+  return `환경 변수 ${s.env.join("·") || "(없음)"} 또는 파일 ${s.files.join("·")}`;
+}
+
+export function findKey(name: string): string | null {
+  const s = sources(name);
+  for (const e of s.env) {
+    const v = process.env[e]?.trim();
+    if (v) return v;
+  }
+  for (const f of s.files) {
+    const p = expand(f);
+    if (!existsSync(p)) continue;
+    const v = readFileSync(p, "utf8").trim();
+    if (v) return v;
+  }
+  return null;
+}
+
+export function hasKey(name: string): boolean {
+  return findKey(name) !== null;
+}
+
+export function readKey(name: string): string {
+  const v = findKey(name);
+  if (!v) throw new MissingKeyError(name);
+  return v;
+}

package/packages/gen/src/media.ts

@@ -0,0 +1,150 @@
+import { spawn } from "node:child_process";
+import { renameSync } from "node:fs";
+
+export function run(cmd: string, args: string[], input?: Uint8Array): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    const p = spawn(cmd, args, { stdio: ["pipe", "pipe", "pipe"] });
+    const out: Buffer[] = [];
+    const err: Buffer[] = [];
+    p.stdout.on("data", (b: Buffer) => out.push(b));
+    p.stderr.on("data", (b: Buffer) => err.push(b));
+    p.on("error", reject);
+    p.on("close", (code) => {
+      if (code === 0) return resolve(Buffer.concat(out));
+      const tail = Buffer.concat(err).toString().trim().split("\n").slice(-4).join("\n");
+      reject(new Error(`${cmd} 실패(${code}): ${tail}`));
+    });
+    if (input) p.stdin.end(input);
+    else p.stdin.end();
+  });
+}
+
+const ff = (args: string[], input?: Uint8Array) => run("ffmpeg", ["-v", "error", "-y", ...args], input);
+
+export interface Probe {
+  width: number;
+  height: number;
+  duration?: number;
+  fps?: number;
+}
+
+export async function probe(path: string): Promise<Probe> {
+  const out = await run("ffprobe", [
+    "-v", "error", "-select_streams", "v:0",
+    "-show_entries", "stream=width,height,r_frame_rate:format=duration",
+    "-of", "json", path,
+  ]);
+  const j = JSON.parse(out.toString());
+  const s = j.streams?.[0] ?? {};
+  const [n, d] = String(s.r_frame_rate ?? "0/1").split("/").map(Number);
+  const duration = Number(j.format?.duration);
+  return {
+    width: s.width,
+    height: s.height,
+    duration: Number.isFinite(duration) ? duration : undefined,
+    fps: d ? n / d : undefined,
+  };
+}
+
+// 64x64 로 줄인 알파에서 거의 투명한 칸의 비율. 0 이면 투명 배경이 안 먹은 것이다.
+export async function transparentRatio(path: string): Promise<number> {
+  const raw = await ff(["-i", path, "-vf", "format=rgba,alphaextract,scale=64:64", "-f", "rawvideo", "-pix_fmt", "gray", "-"]);
+  let n = 0;
+  for (const v of raw) if (v < 250) n++;
+  return raw.length ? n / raw.length : 0;
+}
+
+// chromaKey 와 짝 — 투명 배경을 못 받는 모델에 이 문장을 붙여 그리게 한 뒤 키잉한다.
+export const KEY_BG =
+  "Place the subject on a perfectly flat, uniform pure green (#00FF00) background with no shadow, gradient or texture.";
+
+// ffmpeg 은 읽는 파일에 바로 쓰지 못한다 — 같은 경로면 옆 파일에 쓰고 바꿔 끼운다.
+async function toFile(src: string, dst: string, args: (out: string) => string[]): Promise<void> {
+  const out = src === dst ? dst.replace(/(\.[a-z0-9]+)$/i, ".work$1") : dst;
+  await ff(args(out));
+  if (out !== dst) renameSync(out, dst);
+}
+
+export async function chromaKey(src: string, dst: string, color = "0x00FF00"): Promise<void> {
+  await toFile(src, dst, (out) => ["-i", src, "-vf", `colorkey=${color}:0.28:0.08,despill=type=green,format=rgba`, "-frames:v", "1", out]);
+}
+
+// 참조 그림은 실루엣만 전하면 되고 OG 는 큰 업로드를 413 으로 자른다 — 흰 바탕에 얹은 512px JPEG 로 보낸다.
+export async function refJpeg(src: string, maxEdge = 512): Promise<Buffer> {
+  return ff([
+    "-i", src,
+    "-filter_complex",
+    `[0]format=rgba,scale='min(${maxEdge},iw)':'min(${maxEdge},ih)':force_original_aspect_ratio=decrease[fg];` +
+      `color=white:s=16x16[bg0];[bg0][fg]scale2ref[bg][fg2];[bg][fg2]overlay=format=auto,format=yuvj420p`,
+    "-frames:v", "1", "-q:v", "4", "-f", "image2", "-c:v", "mjpeg", "-",
+  ]);
+}
+
+export async function fitImage(src: string, dst: string, w: number, h: number): Promise<void> {
+  await toFile(src, dst, (out) => [
+    "-i", src,
+    "-vf", `scale=${w}:${h}:force_original_aspect_ratio=increase:flags=lanczos,crop=${w}:${h}`,
+    "-frames:v", "1", out,
+  ]);
+}
+
+// 생성 클립(16·24fps, 5초 남짓)을 장면 틈 길이·프로젝트 fps 에 정확히 맞춘다. 미디어 어댑터는 seek 만 하면 된다.
+// size 를 주면 비율을 무시하고 늘린다 — H3 는 16:9 입력을 1344x768(1.75:1)로 잘라 내지 않고 늘려 받으니,
+// 되늘려야 첫·끝 프레임이 앞뒤 장면과 픽셀 자리까지 겹친다(2026-10-08 실측).
+export async function retime(src: string, dst: string, dur: number, fps: number, o: { smooth?: boolean; size?: { w: number; h: number } } = {}): Promise<void> {
+  const p = await probe(src);
+  if (!p.duration) throw new Error(`길이를 못 읽음: ${src}`);
+  const factor = dur / p.duration;
+  const rate = o.smooth ? `minterpolate=fps=${fps}:mi_mode=mci` : `fps=${fps}`;
+  const scale = o.size && (o.size.w !== p.width || o.size.h !== p.height) ? `,scale=${o.size.w}:${o.size.h}:flags=lanczos,setsar=1` : "";
+  await toFile(src, dst, (out) => [
+    "-i", src, "-an",
+    "-vf", `setpts=${factor.toFixed(6)}*PTS,${rate}${scale}`,
+    "-t", dur.toFixed(4),
+    "-c:v", "libx264", "-pix_fmt", "yuv420p", "-crf", "16", "-preset", "medium", "-movflags", "+faststart",
+    out,
+  ]);
+}
+
+// 모델은 첫 키프레임은 꽉 붙잡지만 끝 키프레임은 몇 픽셀 밀리고 빛이 달라진다(H3 실측 PSNR 37.8 대 24.6 dB).
+// 양 끝 몇 프레임을 진짜 앞뒤 장면 프레임으로 녹여 넘겨 경계 프레임을 픽셀까지 같게 만든다.
+export async function snapEnds(
+  src: string,
+  dst: string,
+  o: { first?: string; last?: string; frames: number; fps: number; dur: number; w: number; h: number },
+): Promise<void> {
+  if (!o.first && !o.last) return;
+  const ramp = Math.max(1, o.frames - 1) / o.fps;
+  const inputs = ["-i", src];
+  const chains: string[] = [];
+  let cur = "[0]";
+  let n = 1;
+  if (o.first) {
+    inputs.push("-loop", "1", "-framerate", String(o.fps), "-t", o.dur.toFixed(4), "-i", o.first);
+    chains.push(`[${n}]scale=${o.w}:${o.h},format=rgba,fade=t=out:st=0:d=${ramp.toFixed(4)}:alpha=1[f]`, `${cur}[f]overlay=eof_action=pass[v${n}]`);
+    cur = `[v${n}]`;
+    n++;
+  }
+  if (o.last) {
+    inputs.push("-loop", "1", "-framerate", String(o.fps), "-t", o.dur.toFixed(4), "-i", o.last);
+    const st = o.dur - 1 / o.fps - ramp;
+    chains.push(`[${n}]scale=${o.w}:${o.h},format=rgba,fade=t=in:st=${st.toFixed(4)}:d=${ramp.toFixed(4)}:alpha=1[l]`, `${cur}[l]overlay=eof_action=pass[v${n}]`);
+    cur = `[v${n}]`;
+  }
+  await toFile(src, dst, (out) => [
+    ...inputs,
+    "-filter_complex", chains.join(";"),
+    "-map", cur, "-r", String(o.fps), "-frames:v", String(Math.round(o.dur * o.fps)),
+    "-c:v", "libx264", "-pix_fmt", "yuv420p", "-crf", "16", "-preset", "medium", "-movflags", "+faststart",
+    out,
+  ]);
+}
+
+export async function dataUri(src: string, maxEdge = 1280): Promise<string> {
+  const jpg = await ff([
+    "-i", src,
+    "-vf", `scale='min(${maxEdge},iw)':'min(${maxEdge},ih)':force_original_aspect_ratio=decrease,format=yuvj420p`,
+    "-frames:v", "1", "-q:v", "3", "-f", "image2", "-c:v", "mjpeg", "-",
+  ]);
+  return `data:image/jpeg;base64,${jpg.toString("base64")}`;
+}

package/packages/gen/src/plan.ts

@@ -0,0 +1,106 @@
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { genImage, genVideo, NeedsApproval, type GenContext } from "./generate.ts";
+import { seam } from "./seam.ts";
+
+// plan.json 의 gen — 장면 assets 의 "gen:img:<id>"·"gen:vid:<id>" 가 가리키는 만들 거리.
+export interface GenSpec {
+  id?: string;
+  kind: "img" | "vid";
+  scene?: string;
+  prompt: string;
+  size?: string; // img
+  transparent?: boolean;
+  quality?: string;
+  refs?: string[]; // 프로젝트 기준 경로
+  seam?: boolean; // vid: 이 id 가 kf.json 의 이음매 장면이다
+  dur?: number; // vid(이음매가 아닐 때)
+  first?: string;
+  last?: string;
+  provider?: string;
+}
+
+export interface GenReport {
+  id: string;
+  kind: "img" | "vid";
+  status: "made" | "cached" | "needs-approval" | "error";
+  path?: string;
+  costUsd?: number;
+  estimateUsd?: number;
+  provider?: string;
+  error?: string;
+}
+
+export function referencedIds(plan: any): { kind: "img" | "vid"; id: string }[] {
+  const out: { kind: "img" | "vid"; id: string }[] = [];
+  for (const s of plan.scenes ?? []) {
+    for (const a of s.assets ?? []) {
+      const m = /^gen:(img|vid):(.+)$/.exec(a);
+      if (m && !out.some((x) => x.id === m[2])) out.push({ kind: m[1] as "img" | "vid", id: m[2] });
+    }
+  }
+  return out;
+}
+
+// 정본은 id 를 품은 배열. id 를 키로 쓴 객체도 받는다.
+export function genSpecs(plan: any): Record<string, GenSpec> {
+  const g = plan.gen ?? {};
+  if (!Array.isArray(g)) return g;
+  const out: Record<string, GenSpec> = {};
+  for (const [i, spec] of g.entries()) {
+    if (typeof spec?.id !== "string") throw new Error(`plan.json gen[${i}] 에 id 가 없다`);
+    out[spec.id] = spec;
+  }
+  return out;
+}
+
+function aspectSize(aspect: string | undefined): string {
+  return aspect === "9:16" ? "1080x1920" : aspect === "1:1" ? "1080x1080" : "1920x1080";
+}
+
+export async function resolvePlan(project: string, ctx: Omit<GenContext, "outDir">): Promise<GenReport[]> {
+  const dir = resolve(project);
+  const plan = JSON.parse(readFileSync(join(dir, "plan.json"), "utf8"));
+  const specs = genSpecs(plan);
+  const at = (p?: string) => (p ? (isAbsolute(p) ? p : join(dir, p)) : undefined);
+  const outDir = join(dir, "assets", "gen");
+  const full = { ...ctx, outDir };
+  const reports: GenReport[] = [];
+  const ids = referencedIds(plan);
+  for (const id of Object.keys(specs)) if (!ids.some((x) => x.id === id)) ids.push({ kind: specs[id].kind, id });
+  // 이음매는 앞뒤 장면을 찍어 만든다 — 그 장면들이 쓰는 그림·영상이 먼저 있어야 한다.
+  const rank = (id: string) => (specs[id]?.kind === "img" ? 0 : specs[id]?.seam ? 2 : 1);
+  ids.sort((a, b) => rank(a.id) - rank(b.id));
+
+  for (const { kind, id } of ids) {
+    const spec = specs[id];
+    if (!spec) {
+      reports.push({ id, kind, status: "error", error: `plan.json gen.${id} 이 없다 — prompt 를 적어야 만든다` });
+      continue;
+    }
+    try {
+      if (spec.kind === "img") {
+        const a = await genImage(
+          id,
+          { prompt: spec.prompt, size: spec.size ?? aspectSize(plan.aspect), transparent: spec.transparent, quality: spec.quality, refs: spec.refs?.map((r) => at(r)!) },
+          full,
+          spec.provider,
+        );
+        reports.push({ id, kind, status: a.cached ? "cached" : "made", path: a.path, costUsd: a.cached ? 0 : a.meta.costUsd, provider: a.meta.provider });
+      } else if (spec.seam) {
+        const a = await seam({ project: dir, scene: id, prompt: spec.prompt, provider: spec.provider, first: at(spec.first), last: at(spec.last) }, full);
+        reports.push({ id, kind, status: a.cached ? "cached" : "made", path: a.path, costUsd: a.cached ? 0 : a.meta.costUsd, provider: a.meta.provider });
+      } else {
+        const first = at(spec.first);
+        if (first && !existsSync(first)) throw new Error(`첫 프레임 없음: ${spec.first} — 그림을 먼저 만든다(gen 순서)`);
+        const req = { prompt: spec.prompt, duration: spec.dur ?? 5, aspect: plan.aspect ?? "16:9", firstFrame: first, lastFrame: at(spec.last) };
+        const a = await genVideo(id, req, full, spec.provider);
+        reports.push({ id, kind, status: a.cached ? "cached" : "made", path: a.path, costUsd: a.cached ? 0 : a.meta.costUsd, provider: a.meta.provider });
+      }
+    } catch (e) {
+      if (e instanceof NeedsApproval) reports.push({ id, kind, status: "needs-approval", estimateUsd: e.estimateUsd, provider: e.provider, error: e.message });
+      else reports.push({ id, kind, status: "error", error: e instanceof Error ? e.message : String(e) });
+    }
+  }
+  return reports;
+}

package/packages/gen/src/registry.ts

@@ -0,0 +1,51 @@
+import { ogImage } from "./image/og.ts";
+import { hasKey } from "./keys.ts";
+import type { ImageProvider, VideoProvider, VideoRequest } from "./types.ts";
+import { FAL_MODELS, falVideo } from "./video/fal.ts";
+import { h3Video } from "./video/h3.ts";
+import { ltxVideo } from "./video/ltx.ts";
+import { minimaxVideo } from "./video/minimax.ts";
+import { veoVideo } from "./video/veo.ts";
+
+export const DEFAULT_IMAGE = "og-gpt-image-2.5-sunburst";
+
+export function imageProviders(): ImageProvider[] {
+  return [ogImage("openai/gpt-image-2.5-sunburst"), ogImage("openai/gpt-image-2.5-flare"), ogImage("openai/gpt-image-2")];
+}
+
+export function videoProviders(): VideoProvider[] {
+  return [
+    h3Video(),
+    ...FAL_MODELS.map((m) => falVideo(m.id)),
+    minimaxVideo(),
+    veoVideo("veo-3.1-lite-generate-preview"),
+    veoVideo("veo-3.1-fast-generate-preview"),
+    ltxVideo(),
+  ];
+}
+
+// id 는 앞뒤 접두 없이도 찾는다 — "wan-2.2-turbo" 와 "fal-wan-2.2-turbo" 가 같은 것.
+function find<T extends { id: string }>(list: T[], id: string): T | undefined {
+  return list.find((p) => p.id === id) ?? list.find((p) => p.id.endsWith(`-${id}`) || p.id.replace(/^[a-z]+-/, "") === id);
+}
+
+export function pickImage(id = DEFAULT_IMAGE): ImageProvider {
+  const p = find(imageProviders(), id);
+  if (!p) throw new Error(`그림 공급자 없음: ${id} (있는 것: ${imageProviders().map((x) => x.id).join(" ")})`);
+  return p;
+}
+
+// 이름을 안 주면 키가 있는 것 중 가장 싼 것. 끝 프레임이 필요하면 그걸 받는 것만.
+export function pickVideo(id: string | undefined, req: VideoRequest): VideoProvider {
+  const all = videoProviders();
+  if (id) {
+    const p = find(all, id);
+    if (!p) throw new Error(`영상 공급자 없음: ${id} (있는 것: ${all.map((x) => x.id).join(" ")})`);
+    return p;
+  }
+  const usable = all
+    .filter((p) => hasKey(p.keyName) && (!req.lastFrame || p.firstLast))
+    .sort((a, b) => a.estimateUsd(req) - b.estimateUsd(req));
+  if (!usable.length) throw new Error("키가 있는 영상 공급자가 없다 — kf gen models 로 무엇이 필요한지 본다");
+  return usable[0];
+}

package/packages/gen/src/seam.ts

@@ -0,0 +1,103 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { genVideo, type GenContext } from "./generate.ts";
+import { retime, run, snapEnds } from "./media.ts";
+import type { Asset } from "./types.ts";
+
+interface KfScene {
+  id: string;
+  from: number;
+  dur: number;
+  role?: string;
+}
+
+interface KfJson {
+  fps: number;
+  width: number;
+  height: number;
+  scenes: KfScene[];
+}
+
+export function aspectOf(w: number, h: number): string {
+  const r = w / h;
+  if (Math.abs(r - 16 / 9) < 0.05) return "16:9";
+  if (Math.abs(r - 9 / 16) < 0.05) return "9:16";
+  if (Math.abs(r - 1) < 0.05) return "1:1";
+  return r > 1 ? "16:9" : "9:16";
+}
+
+// 이음매 장면(role "seam")은 앞 장면의 마지막 프레임에서 시작해 뒤 장면의 첫 프레임에서 끝난다.
+// 프레임 번호로 다룬다 — 초를 소수로 넘기면 반올림에 따라 앞뒤 장면이 한 프레임씩 바뀐다.
+export function seamFrames(kf: KfJson, sceneId: string): { scene: KfScene; firstFrame?: number; lastFrame?: number } {
+  const i = kf.scenes.findIndex((s) => s.id === sceneId);
+  if (i < 0) throw new Error(`kf.json 에 장면 없음: ${sceneId}`);
+  const scene = kf.scenes[i];
+  const start = Math.round(scene.from * kf.fps);
+  return {
+    scene,
+    firstFrame: i > 0 ? Math.max(0, start - 1) : undefined,
+    lastFrame: i < kf.scenes.length - 1 ? Math.round((scene.from + scene.dur) * kf.fps) : undefined,
+  };
+}
+
+const KF = fileURLToPath(new URL("../../cli/src/kf.ts", import.meta.url));
+
+export async function still(project: string, frame: number, out: string): Promise<void> {
+  await run(process.execPath, [KF, "still", project, "--frame", String(frame), "--out", out]);
+  if (!existsSync(out)) throw new Error(`kf still 이 ${out} 을 안 만들었다`);
+}
+
+export interface SeamOptions {
+  project: string;
+  scene: string;
+  prompt: string;
+  provider?: string;
+  first?: string; // 주면 kf still 대신 이 그림
+  last?: string;
+  smooth?: boolean;
+  resolution?: string;
+  snapFrames?: number; // 양 끝을 진짜 앞뒤 프레임으로 녹이는 프레임 수. 기본 0.15초어치, 0 이면 끈다
+}
+
+// 받은 클립은 장면 길이·fps 에 맞춰 assets/gen/<장면>.mp4 로 둔다. 장면 파일은 media 어댑터로 seek 만 한다.
+export async function seam(o: SeamOptions, ctx: Omit<GenContext, "outDir"> & { outDir?: string }): Promise<Asset> {
+  const project = resolve(o.project);
+  const kf = JSON.parse(readFileSync(join(project, "kf.json"), "utf8")) as KfJson;
+  const { scene, firstFrame, lastFrame } = seamFrames(kf, o.scene);
+  const framesDir = join(project, "out", "seam");
+  mkdirSync(framesDir, { recursive: true });
+  let first = o.first;
+  let last = o.last;
+  if (!first && firstFrame !== undefined) {
+    first = join(framesDir, `${scene.id}-first.png`);
+    await still(project, firstFrame, first);
+  }
+  if (!last && lastFrame !== undefined) {
+    last = join(framesDir, `${scene.id}-last.png`);
+    await still(project, lastFrame, last);
+  }
+  const outDir = ctx.outDir ?? join(project, "assets", "gen");
+  const raw = await genVideo(
+    `${scene.id}.raw`,
+    { prompt: o.prompt, firstFrame: first, lastFrame: last, duration: scene.dur, aspect: aspectOf(kf.width, kf.height), resolution: o.resolution },
+    { ...ctx, outDir },
+    o.provider,
+  );
+  const fitted = join(outDir, `${scene.id}.mp4`);
+  await retime(raw.path, fitted, scene.dur, kf.fps, { smooth: o.smooth, size: { w: kf.width, h: kf.height } });
+  const snap = o.snapFrames ?? Math.round(kf.fps * 0.15);
+  if (snap > 0) await snapEnds(fitted, fitted, { first, last, frames: snap, fps: kf.fps, dur: scene.dur, w: kf.width, h: kf.height });
+  const meta = {
+    ...raw.meta,
+    id: scene.id,
+    file: `${scene.id}.mp4`,
+    width: kf.width,
+    height: kf.height,
+    duration: scene.dur,
+    fps: kf.fps,
+    notes: [...(raw.meta.notes ?? []), `retimed from ${raw.meta.file}`, ...(snap > 0 ? [`snap ${snap}f`] : []), ...(first ? [] : ["no-first-frame"]), ...(last ? [] : ["no-last-frame"])],
+  };
+  writeFileSync(join(outDir, `${scene.id}.json`), JSON.stringify(meta, null, 2) + "\n");
+  return { path: fitted, meta, cached: raw.cached };
+}