Skip to content

Photoreal Blender scenes from a one-paragraph brief, built by AI agents: image→3D props on fal, scripted layout, lighting, camera and grade.

Python
9.5 KB
Raw Blame
// fal client for AnyScene: GPT Image 2.5 references + Tripo / Meshy image-to-3D, with a spend log.
// Adapted from character-lab/generate/fal.mjs.
//
// The key comes from the user environment variable FAL_KEY (machine-wide; never print it):
//   node generate/fal.mjs <command> [flags]
//
// Commands
//   image --out refs/tokyo-electronics-repair/concept_a --prompt "..." [--variant flare|sunburst] [--size landscape_16_9] [--quality high] [--n 1]
//         -> <out>_<i>.png + <out>.json (keeps the fal URL so 3D endpoints can reuse it)
//   3d    --model tripo-h31|tripo-p2|meshy --ref refs/props/x.json --out assets/gen/<model>/<id> [--face-limit 150000]
//         -> <out>/model.glb + result.json
//   spend -> totals so far
//
// All paid calls append {time, endpoint, est_usd, request_id, ...} to generate/spend.jsonl.

import { appendFile, mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
import { existsSync } from 'node:fs';
import { execFileSync } from 'node:child_process';
import { dirname, join, resolve } from 'node:path';
import { parseArgs } from 'node:util';

// The machine-wide key lives in the user environment (FAL_KEY). Read it from the registry so shells started
// before it was set still pick it up; fall back to the process env / --env-file.
function globalKey() {
  if (process.platform !== 'win32') return undefined;
  try {
    const out = execFileSync('reg', ['query', 'HKCU\\Environment', '/v', 'FAL_KEY'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
    return out.match(/FAL_KEY\s+REG_\w+\s+(\S+)/)?.[1];
  } catch {
    return undefined;
  }
}
const KEY = globalKey() || process.env.FAL_KEY || process.env.FAL_API_KEY;
const HERE = dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/, '$1'));
const REPO = resolve(HERE, '..');
const SPEND_LOG = join(REPO, 'generate', 'spend.jsonl');

/** Budget is unlimited per the user; this only guards against runaway loops. */
const TOTAL_CAP = 1000;

/** Rough per-call estimates for the log (fal pricing API, 2026-10-27; GPT Image is token-billed, so estimated). */
const EST = { image: 0.25, 'tripo-h31': 0.6, 'tripo-p2': 0.6, meshy: 0.8 };

const MODELS3D = {
  'tripo-h31': {
    endpoint: 'tripo3d/h3.1/image-to-3d',
    input: { pbr: true, texture: true, geometry_quality: 'detailed', texture_quality: 'detailed', auto_size: true, orientation: 'align_image' },
  },
  'tripo-p2': {
    endpoint: 'tripo3d/p2/image-to-3d',
    input: { pbr: true, texture: true, texture_quality: 'extreme', texture_version: 'v3.5-20260815', delight: true, auto_size: true, export_uv: true },
  },
  meshy: {
    endpoint: 'meshy/v7.1/image-to-3d',
    input: { enable_pbr: true, should_texture: true, geometry_resolution: '4k', topology: 'triangle', should_remesh: true, target_polycount: 150000, symmetry_mode: 'auto' },
  },
};

const { positionals, values: a } = parseArgs({
  allowPositionals: true,
  options: {
    out: { type: 'string' }, prompt: { type: 'string' }, variant: { type: 'string', default: 'flare' },
    size: { type: 'string', default: 'landscape_16_9' }, quality: { type: 'string', default: 'high' }, n: { type: 'string', default: '1' },
    model: { type: 'string' }, ref: { type: 'string' }, 'face-limit': { type: 'string' }, force: { type: 'boolean' },
  },
});

async function readSpend() {
  if (!existsSync(SPEND_LOG)) return [];
  return (await readFile(SPEND_LOG, 'utf8')).split('\n').filter(Boolean).map((l) => JSON.parse(l));
}

async function logSpend(row) {
  await mkdir(dirname(SPEND_LOG), { recursive: true });
  await appendFile(SPEND_LOG, JSON.stringify({ time: new Date().toISOString(), ...row }) + '\n');
}

async function call(url, init = {}) {
  const res = await fetch(url, { ...init, headers: { authorization: `Key ${KEY}`, 'content-type': 'application/json' } });
  const text = await res.text();
  if (!res.ok) throw new Error(`${res.status} ${url}: ${text.slice(0, 600)}`);
  return text ? JSON.parse(text) : null;
}

/** Queue-submit, poll, return result. Logs spend as soon as the request is accepted.
 *  With `pending` (a file path), the submitted job is recorded there until its result is in. If a run is cut off (the
 *  process or the whole worker dies) and the same command runs again, it picks the recorded job back up instead of
 *  paying for a new one. */
async function run(endpoint, input, { est, meta = {}, timeoutMin = 30, pending = null }) {
  if (!KEY) throw new Error('FAL_KEY is not set (user environment variable)');
  const t0 = performance.now();
  let job = null;
  if (pending && existsSync(pending)) {
    try {
      job = JSON.parse(await readFile(pending, 'utf8'));
      await call(job.status_url);  // still known to the queue?
      console.log(`resuming ${endpoint} ${job.request_id}`);
    } catch {
      job = null;  // expired or unknown: submit again
    }
  }
  if (!job) {
    const spent = (await readSpend()).reduce((s, r) => s + r.est_usd, 0);
    if (spent + est > TOTAL_CAP) throw new Error(`BUDGET: total would reach $${(spent + est).toFixed(2)} > $${TOTAL_CAP}. Stop and report.`);
    job = await call(`https://queue.fal.run/${endpoint}`, { method: 'POST', body: JSON.stringify(input) });
    await logSpend({ endpoint, est_usd: est, request_id: job.request_id, ...meta });
    if (pending) {
      await mkdir(dirname(pending), { recursive: true });
      await writeFile(pending, JSON.stringify(job));
    }
    console.log(`queued ${endpoint} ${job.request_id}`);
  }
  for (;;) {
    await new Promise((r) => setTimeout(r, 4000));
    const st = await call(job.status_url);
    if (st.status === 'COMPLETED') break;
    if (performance.now() - t0 > timeoutMin * 60_000) throw new Error(`timed out; request ${job.request_id}`);
  }
  const result = await call(job.response_url);
  const seconds = (performance.now() - t0) / 1000;
  console.log(`done ${endpoint} in ${seconds.toFixed(0)} s`);
  return { result, request_id: job.request_id, seconds };
}

async function download(url, out) {
  const res = await fetch(url);
  if (!res.ok) throw new Error(`download ${res.status} ${url}`);
  await mkdir(dirname(out), { recursive: true });
  await writeFile(out, Buffer.from(await res.arrayBuffer()));
  return out;
}

function need(name) {
  if (!a[name]) throw new Error(`--${name} is required`);
  return a[name];
}

async function cmdImage() {
  const out = resolve(REPO, need('out'));
  // already made (a resumed build re-running its batch): never pay twice. --force regenerates.
  if (!a.force && existsSync(`${out}.json`) && [...Array(+a.n).keys()].every((i) => existsSync(`${out}_${i}.png`))) {
    console.log(`exists ${a.out}_0.png (skipped; --force to regenerate)`);
    return;
  }
  const endpoint = `openai/gpt-image-2.5/${a.variant}/text-to-image`;
  const input = { prompt: need('prompt'), image_size: a.size, quality: a.quality, num_images: +a.n, output_format: 'png' };
  const { result, request_id, seconds } = await run(endpoint, input, { est: EST.image * +a.n, meta: { kind: 'image', out: a.out },
                                                                   pending: `${out}.pending.json` });
  const files = [];
  for (const [i, img] of (result.images ?? []).entries()) {
    const f = `${out}_${i}.png`;
    await download(img.url, f);
    files.push({ file: f, url: img.url, width: img.width, height: img.height });
  }
  await writeFile(`${out}.json`, JSON.stringify({ endpoint, request_id, seconds, input, files }, null, 2));
  await unlink(`${out}.pending.json`).catch(() => {});
  console.log(`saved ${files.map((f) => f.file).join(', ')}`);
}

async function cmd3d() {
  const spec = MODELS3D[need('model')];
  if (!spec) throw new Error(`--model must be one of ${Object.keys(MODELS3D).join(', ')}`);
  const ref = JSON.parse(await readFile(resolve(REPO, need('ref')), 'utf8'));
  const out = resolve(REPO, need('out'));
  if (!a.force && existsSync(join(out, 'model.glb'))) {
    console.log(`exists ${a.out}/model.glb (skipped; --force to regenerate)`);
    return;
  }
  const input = { ...spec.input, image_url: ref.files[0].url };
  // Tripo otherwise returns ~2M triangles per prop: slow to import, compare and decimate. Meshy ignores it.
  if (a['face-limit'] && a.model.startsWith('tripo')) input.face_limit = Number(a['face-limit']);
  const { result, request_id, seconds } = await run(spec.endpoint, input, { est: EST[a.model], meta: { kind: '3d', model: a.model, out: a.out },
                                                                         pending: join(out, 'pending.json') });
  await mkdir(out, { recursive: true });
  await writeFile(join(out, 'result.json'), JSON.stringify({ endpoint: spec.endpoint, request_id, seconds, input, result }, null, 2));
  // Tripo returns model_mesh / pbr_model, Meshy returns model_glb; take the first GLB we find.
  const glb = JSON.stringify(result).match(/https:\/\/[^"]+?\.glb[^"]*/)?.[0];
  if (!glb) throw new Error('no GLB in response: ' + JSON.stringify(result).slice(0, 500));
  await download(glb, join(out, 'model.glb'));
  await unlink(join(out, 'pending.json')).catch(() => {});
  console.log(`saved ${a.out}/model.glb (${seconds.toFixed(0)} s)`);
}

async function cmdSpend() {
  const rows = await readSpend();
  const by = {};
  for (const r of rows) by[r.endpoint] = (by[r.endpoint] ?? 0) + r.est_usd;
  for (const [e, v] of Object.entries(by)) console.log(`${e.padEnd(48)} $${v.toFixed(2)}`);
  console.log(`${'total'.padEnd(48)} $${rows.reduce((s, r) => s + r.est_usd, 0).toFixed(2)}  (${SPEND_LOG})`);
}

const cmds = { image: cmdImage, '3d': cmd3d, spend: cmdSpend };
const cmd = cmds[positionals[0]];
if (!cmd) {
  console.error(`usage: fal.mjs <${Object.keys(cmds).join('|')}> [flags]  (see header)`);
  process.exit(1);
}
await cmd();