Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

feat(forge): add /api/forge-batch to fan out and poll N generations as a group

nirholaseb0c6322327b
diff --git a/api/_lib/rate-limit.js b/api/_lib/rate-limit.js
index 233b468c7..e9b8965bb 100644
--- a/api/_lib/rate-limit.js
+++ b/api/_lib/rate-limit.js
@@ -1009,6 +1009,23 @@ export const limits = {
limit: Math.max(FREE_HOURLY_BASE, Math.round(FREE_HOURLY_BASE * (Number(multiplier) || 1))),
window: '1 h',
}).limit(key),
+ // Batch submit (api/forge-batch.js): one call fans out to N /forge
+ // submissions internally, so it needs its own, much tighter ceiling than
+ // mcp3dGenerateFreeTiered guards per-item spend already (each fanned-out
+ // item still passes through the free lane's own per-IP limiter). This
+ // bucket just caps how many BATCH calls a principal can open per hour; the
+ // same $THREE tier multiplier that raises the free lane also raises this.
+ forgeBatchSubmit: (key, multiplier = 1) =>
+ getLimiter('forge:batch:submit', {
+ limit: Math.max(10, Math.round(10 * (Number(multiplier) || 1))),
+ window: '1 h',
+ }).limit(key),
+ // Batch group polling (GET /api/forge-batch?batch=) fans out to N
+ // /forge?job= status checks per call, same high-frequency shape as
+ // mcp3dStatus, so it gets the same per-instance (`local`) treatment: a
+ // distributed Redis command per poll buys no real protection here.
+ forgeBatchStatus: (key) =>
+ getLimiter('forge:batch:status', { limit: 120, window: '1 m', local: true }).limit(key),
// Material Studio (api/material-studio.js): non-destructive material edits,
// AI restyle (one watsonx call + one gltf-transform mutation pass — cheap,
// no GPU job), and seeded variant fan-out. Free, hosted, and non-critical
diff --git a/api/forge-batch.js b/api/forge-batch.js
new file mode 100644
index 000000000..4cd1e45fc
--- /dev/null
+++ b/api/forge-batch.js
@@ -0,0 +1,269 @@
+/**
+ * Forge batch: submit up to MAX_ITEMS /api/forge generations in one call,
+ * concurrency-capped by the caller's $THREE holder tier, and poll the group.
+ *
+ * POST /api/forge-batch { items: [ <any /api/forge POST body>, ... ] }
+ * -> { batch_id, items: [{ index, ok, job_id?, status?, glb_url?, error? }] }
+ * GET /api/forge-batch?batch=<id>
+ * -> { batch_id, status: 'queued'|'running'|'done'|'partial', items: [...] }
+ *
+ * Each item is a full, independent /api/forge submission (api/forge.js),
+ * called over HTTP against this deployment's own origin (the same self-call
+ * idiom api/_mcp-studio/forge-client.js uses), so every lane-selection,
+ * gating, and caching rule /api/forge already enforces applies per item
+ * unchanged. This endpoint adds only the fan-out, the concurrency cap, and
+ * the group bookkeeping: it never touches the database directly, since each
+ * item's /api/forge call already persists its own durable forge_creations row.
+ *
+ * Concurrency cap: the $THREE holder-tier rate multiplier that already lifts
+ * the free generation ceiling (freeLaneMultiplier in forge.js) also lifts how
+ * many items of one batch submit at once (BASE_CONCURRENCY * multiplier,
+ * capped at MAX_CONCURRENCY): the resolution is re-implemented locally from
+ * the same primitives (three-tier.js, comp-access.js) rather than imported
+ * from forge.js, which keeps the multiplier private to that module.
+ *
+ * Per-item isolation: one item's failure never fails the batch (mirrors
+ * api/x402/mint-to-mesh-batch.js's convention): a submit error on item 2
+ * still returns items 0, 1, 3... with their own real job ids.
+ *
+ * Group state lives in Redis only (fr:batch: prefix, mirrors the best-effort,
+ * fail-open pattern in forge-job-options.js): a Redis outage at submit time
+ * degrades to an un-grouped response (every item still carries a real job id
+ * the caller can poll individually via GET /api/forge?job=); at poll time it
+ * is a 404 for the group endpoint specifically, never a broken item result.
+ */
+
+import { randomUUID } from 'node:crypto';
+import { cors, json, method, readJson, wrap, rateLimited } from './_lib/http.js';
+import { limits, clientIp } from './_lib/rate-limit.js';
+import { getRedis } from './_lib/redis.js';
+import { selfOrigin } from './_lib/self-origin.js';
+import { TIERS, verifyTierPass } from './_lib/three-tier.js';
+import { resolveCompAccess, COMP_TIER } from './_lib/comp-access.js';
+
+const PREFIX = 'fr:batch:';
+const TTL_S = 3600;
+const MAX_ITEMS = 8;
+const BASE_CONCURRENCY = 2;
+const MAX_CONCURRENCY = 8;
+const SUBMIT_TIMEOUT_MS = 90_000;
+const TERMINAL_STATUSES = new Set(['done', 'failed']);
+
+// Same resolution as forge.js's private freeLaneMultiplier: a verified $THREE
+// tier pass wins outright; a comped account (cookie-guarded, zero cost on the
+// anonymous path) is the fallback. Re-implemented here rather than imported
+// because freeLaneMultiplier is private to forge.js.
+async function batchConcurrency(req, body) {
+ const token = req.headers?.['x-three-tier-pass'] || body?.tier_pass || null;
+ let multiplier = 1;
+ if (token) {
+ const payload = verifyTierPass(token);
+ const tier = payload ? TIERS.find((t) => t.level === payload.level) : null;
+ multiplier = tier?.rateMultiplier || 1;
+ }
+ if (multiplier <= 1) {
+ const { comped } = await resolveCompAccess(req);
+ if (comped) multiplier = COMP_TIER.rateMultiplier || 1;
+ }
+ const concurrency = Math.min(MAX_CONCURRENCY, Math.max(BASE_CONCURRENCY, Math.round(BASE_CONCURRENCY * multiplier)));
+ return { multiplier, concurrency };
+}
+
+// Concurrency-capped fan-out: no p-limit-style utility exists in api/_lib, so
+// a small inline worker pool runs `limit` workers pulling from a shared index.
+async function runPool(items, limit, worker) {
+ const results = new Array(items.length);
+ let next = 0;
+ async function runner() {
+ for (;;) {
+ const i = next++;
+ if (i >= items.length) return;
+ results[i] = await worker(items[i], i);
+ }
+ }
+ await Promise.all(Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, runner));
+ return results;
+}
+
+async function submitOne(base, headers, item, index) {
+ let res;
+ try {
+ res = await fetch(`${base}/api/forge`, {
+ method: 'POST',
+ headers,
+ body: JSON.stringify(item),
+ signal: AbortSignal.timeout(SUBMIT_TIMEOUT_MS),
+ });
+ } catch (err) {
+ const timedOut = err?.name === 'TimeoutError' || err?.name === 'AbortError';
+ return {
+ index,
+ ok: false,
+ error: timedOut ? 'timeout' : 'provider_error',
+ message: timedOut
+ ? 'the 3D generator took too long to accept this item'
+ : `the 3D generator is unreachable: ${err?.message || err}`,
+ };
+ }
+ const data = await res.json().catch(() => ({}));
+ if (!res.ok) {
+ return {
+ index,
+ ok: false,
+ error: data?.error || 'provider_error',
+ message: data?.message || `the 3D generator returned ${res.status} for this item`,
+ };
+ }
+ return {
+ index,
+ ok: true,
+ job_id: data.job_id ?? null,
+ creation_id: data.creation_id ?? null,
+ status: data.status || (data.job_id ? 'queued' : 'done'),
+ glb_url: data.glb_url ?? null,
+ path: data.path ?? null,
+ tier: data.tier ?? null,
+ backend: data.backend ?? null,
+ };
+}
+
+async function pollOne(base, item) {
+ if (!item.ok || !item.job_id || TERMINAL_STATUSES.has(item.status)) return item;
+ let res;
+ try {
+ res = await fetch(`${base}/api/forge?job=${encodeURIComponent(item.job_id)}`, {
+ signal: AbortSignal.timeout(15_000),
+ });
+ } catch {
+ return item; // transient poll failure: keep the last known status, try again next poll
+ }
+ const data = await res.json().catch(() => null);
+ if (!data) return item;
+ return {
+ ...item,
+ status: data.status || item.status,
+ glb_url: data.glb_url ?? item.glb_url,
+ ...(data.status === 'failed' && data.error ? { error: 'generation_failed', message: data.error } : {}),
+ };
+}
+
+function itemTerminal(item) {
+ return item.ok === false || TERMINAL_STATUSES.has(item.status);
+}
+
+function groupStatus(items) {
+ if (items.every(itemTerminal)) {
+ return items.every((i) => i.ok && i.status === 'done') ? 'done' : 'partial';
+ }
+ return items.some((i) => i.ok && i.status && i.status !== 'queued') ? 'running' : 'queued';
+}
+
+async function storeBatch(batchId, record) {
+ const r = getRedis();
+ if (!r) return;
+ try {
+ await r.set(`${PREFIX}${batchId}`, JSON.stringify(record), { ex: TTL_S });
+ } catch {
+ /* best-effort: items already carry their own job ids */
+ }
+}
+
+async function loadBatch(batchId) {
+ const r = getRedis();
+ if (!r) return null;
+ try {
+ const raw = await r.get(`${PREFIX}${batchId}`);
+ if (!raw) return null;
+ return typeof raw === 'string' ? JSON.parse(raw) : raw;
+ } catch {
+ return null;
+ }
+}
+
+async function startBatch(req, res) {
+ const body = await readJson(req, 64_000).catch(() => null);
+ const rawItems = Array.isArray(body?.items) ? body.items : null;
+ if (!rawItems || !rawItems.length) {
+ return json(res, 400, {
+ error: 'missing_items',
+ message: `Pass items: an array of 1..${MAX_ITEMS} /api/forge request bodies.`,
+ });
+ }
+ if (rawItems.length > MAX_ITEMS) {
+ return json(res, 400, {
+ error: 'too_many_items',
+ message: `A batch holds at most ${MAX_ITEMS} items; split into multiple batches.`,
+ max_items: MAX_ITEMS,
+ });
+ }
+ for (let i = 0; i < rawItems.length; i++) {
+ if (!rawItems[i] || typeof rawItems[i] !== 'object' || Array.isArray(rawItems[i])) {
+ return json(res, 400, {
+ error: 'invalid_item',
+ message: `items[${i}] must be an object, the same shape as a /api/forge POST body.`,
+ });
+ }
+ }
+
+ const ip = clientIp(req);
+ const { multiplier, concurrency } = await batchConcurrency(req, body);
+ const rl = await limits.forgeBatchSubmit(ip, multiplier);
+ if (!rl.success) return rateLimited(res, rl);
+
+ const base = selfOrigin(req);
+ // Forward the real caller's IP as x-forwarded-for so /api/forge's own
+ // per-IP free-lane limiter and $THREE tier gate attribute to the actual
+ // caller rather than this server's own egress address; forward the
+ // session cookie and tier pass so the holder/comp perk this endpoint
+ // already resolved for the concurrency cap also applies inside each
+ // item's own /api/forge submission. Never the internal seed header: a
+ // batch submit is never platform-funded.
+ const forwardHeaders = {
+ 'content-type': 'application/json',
+ 'x-forwarded-for': ip,
+ ...(req.headers.cookie ? { cookie: req.headers.cookie } : {}),
+ ...(req.headers['x-three-tier-pass'] ? { 'x-three-tier-pass': req.headers['x-three-tier-pass'] } : {}),
+ ...(req.headers['x-forge-client'] ? { 'x-forge-client': req.headers['x-forge-client'] } : {}),
+ };
+
+ const items = await runPool(rawItems, concurrency, (item, index) => submitOne(base, forwardHeaders, item, index));
+
+ const batchId = randomUUID();
+ await storeBatch(batchId, { batch_id: batchId, created_at: Date.now(), items });
+
+ return json(res, 200, { batch_id: batchId, status: groupStatus(items), items });
+}
+
+async function pollBatch(req, res, batchId) {
+ const rl = await limits.forgeBatchStatus(clientIp(req));
+ if (!rl.success) return rateLimited(res, rl);
+
+ const record = await loadBatch(batchId);
+ if (!record) {
+ return json(res, 404, {
+ error: 'batch_not_found',
+ message: 'Unknown or expired batch id. Poll each item individually via GET /api/forge?job=<id> instead.',
+ });
+ }
+
+ const base = selfOrigin(req);
+ const items = await Promise.all(record.items.map((item) => pollOne(base, item)));
+ const status = groupStatus(items);
+ await storeBatch(batchId, { ...record, items });
+
+ return json(res, 200, { batch_id: batchId, status, items });
+}
+
+export default wrap(async (req, res) => {
+ if (cors(req, res, { methods: 'GET,POST,OPTIONS' })) return;
+ if (!method(req, res, ['GET', 'POST'])) return;
+
+ if (req.method === 'POST') return startBatch(req, res);
+
+ const url = new URL(req.url, 'http://localhost');
+ const batchId = (url.searchParams.get('batch') || '').trim();
+ if (!batchId) {
+ return json(res, 400, { error: 'missing_batch', message: 'Pass ?batch=<id> to poll a batch.' });
+ }
+ return pollBatch(req, res, batchId);
+});
diff --git a/tests/api/forge-batch.test.js b/tests/api/forge-batch.test.js
new file mode 100644
index 000000000..f46507ae7
--- /dev/null
+++ b/tests/api/forge-batch.test.js
@@ -0,0 +1,198 @@
+/**
+ * POST/GET /api/forge-batch: fan out N /api/forge submissions from one call
+ * and poll them as a group (api/forge-batch.js).
+ *
+ * /api/forge itself is never exercised here: every self-call is a mocked
+ * `fetch`, so these tests pin forge-batch.js's own contract (validation,
+ * per-item isolation, group status, Redis-backed retrieval) independent of
+ * the real generation pipeline.
+ */
+
+import { describe, it, expect, vi, beforeAll, beforeEach } from 'vitest';
+
+beforeAll(() => {
+ Object.assign(process.env, {
+ APP_ORIGIN: 'https://three.ws',
+ JWT_SECRET: 'test-jwt-secret-at-least-32-characters-long',
+ });
+});
+
+const store = new Map();
+function fakeRedis() {
+ return {
+ async set(key, value) {
+ store.set(key, value);
+ },
+ async get(key) {
+ return store.has(key) ? store.get(key) : null;
+ },
+ };
+}
+
+vi.mock('../../api/_lib/redis.js', () => ({
+ getRedis: () => fakeRedis(),
+}));
+
+vi.mock('../../api/_lib/rate-limit.js', async (importActual) => {
+ const actual = await importActual();
+ return {
+ ...actual,
+ limits: {
+ ...actual.limits,
+ forgeBatchSubmit: vi.fn(async () => ({ success: true, reset: Date.now() + 1000 })),
+ forgeBatchStatus: vi.fn(async () => ({ success: true, reset: Date.now() + 1000 })),
+ },
+ clientIp: () => '203.0.113.9',
+ };
+});
+
+const { default: handler } = await import('../../api/forge-batch.js');
+
+function makePostReq(body, { headers = {} } = {}) {
+ return {
+ method: 'POST',
+ url: '/api/forge-batch',
+ headers: { 'content-type': 'application/json', ...headers },
+ on(event, cb) {
+ if (event === 'data') cb(Buffer.from(JSON.stringify(body)));
+ if (event === 'end') cb();
+ },
+ };
+}
+
+function makeGetReq(url, { headers = {} } = {}) {
+ return { method: 'GET', url, headers };
+}
+
+function makeRes() {
+ return {
+ statusCode: 200,
+ headers: {},
+ body: null,
+ setHeader(name, value) {
+ this.headers[String(name).toLowerCase()] = value;
+ },
+ getHeader(name) {
+ return this.headers[String(name).toLowerCase()];
+ },
+ end(body) {
+ this.body = body ? JSON.parse(body) : null;
+ },
+ };
+}
+
+function mockFetchSequence(impl) {
+ vi.stubGlobal('fetch', vi.fn(impl));
+}
+
+function jsonResponse(status, data) {
+ return { ok: status >= 200 && status < 300, status, json: async () => data };
+}
+
+describe('POST /api/forge-batch', () => {
+ beforeEach(() => {
+ store.clear();
+ vi.unstubAllGlobals();
+ });
+
+ it('submits every item and returns a retrievable batch id', async () => {
+ let n = 0;
+ mockFetchSequence(async (url) => {
+ expect(String(url)).toBe('https://three.ws/api/forge');
+ n += 1;
+ return jsonResponse(200, { job_id: `job-${n}`, status: 'queued', path: 'image', tier: 'draft', backend: 'nvidia' });
+ });
+
+ const req = makePostReq({ items: [{ prompt: 'a' }, { prompt: 'b' }, { prompt: 'c' }, { prompt: 'd' }] });
+ const res = makeRes();
+ await handler(req, res);
+
+ expect(res.statusCode).toBe(200);
+ expect(res.body.batch_id).toBeTruthy();
+ expect(res.body.items).toHaveLength(4);
+ expect(res.body.items.every((i) => i.ok && i.job_id)).toBe(true);
+ expect(res.body.status).toBe('queued');
+ });
+
+ it('isolates one failing item: the rest still submit with real job ids', async () => {
+ mockFetchSequence(async (url, init) => {
+ const body = JSON.parse(init.body);
+ if (body.prompt === 'bad') return jsonResponse(400, { error: 'invalid_options', message: 'nope' });
+ return jsonResponse(200, { job_id: `job-${body.prompt}`, status: 'queued' });
+ });
+
+ const req = makePostReq({ items: [{ prompt: 'good1' }, { prompt: 'bad' }, { prompt: 'good2' }] });
+ const res = makeRes();
+ await handler(req, res);
+
+ expect(res.statusCode).toBe(200);
+ expect(res.body.items[0]).toMatchObject({ ok: true, job_id: 'job-good1' });
+ expect(res.body.items[1]).toMatchObject({ ok: false, error: 'invalid_options' });
+ expect(res.body.items[2]).toMatchObject({ ok: true, job_id: 'job-good2' });
+ });
+
+ it('rejects an empty items array', async () => {
+ const req = makePostReq({ items: [] });
+ const res = makeRes();
+ await handler(req, res);
+ expect(res.statusCode).toBe(400);
+ expect(res.body.error).toBe('missing_items');
+ });
+
+ it('rejects a batch larger than the max', async () => {
+ const items = Array.from({ length: 9 }, (_, i) => ({ prompt: `p${i}` }));
+ const req = makePostReq({ items });
+ const res = makeRes();
+ await handler(req, res);
+ expect(res.statusCode).toBe(400);
+ expect(res.body.error).toBe('too_many_items');
+ });
+});
+
+describe('GET /api/forge-batch?batch=', () => {
+ beforeEach(() => {
+ store.clear();
+ vi.unstubAllGlobals();
+ });
+
+ it('completes a 4-item batch and retrieves it as a group', async () => {
+ let n = 0;
+ mockFetchSequence(async (url) => {
+ n += 1;
+ return jsonResponse(200, { job_id: `job-${n}`, status: 'queued' });
+ });
+ const submit = makePostReq({ items: [{ prompt: 'a' }, { prompt: 'b' }, { prompt: 'c' }, { prompt: 'd' }] });
+ const submitRes = makeRes();
+ await handler(submit, submitRes);
+ const { batch_id } = submitRes.body;
+
+ mockFetchSequence(async (url) => {
+ const jobId = decodeURIComponent(String(url).split('job=')[1]);
+ return jsonResponse(200, { job_id: jobId, status: 'done', glb_url: `https://cdn.example/${jobId}.glb` });
+ });
+ const poll = makeGetReq(`/api/forge-batch?batch=${batch_id}`);
+ const pollRes = makeRes();
+ await handler(poll, pollRes);
+
+ expect(pollRes.statusCode).toBe(200);
+ expect(pollRes.body.status).toBe('done');
+ expect(pollRes.body.items).toHaveLength(4);
+ expect(pollRes.body.items.every((i) => i.status === 'done' && i.glb_url)).toBe(true);
+ });
+
+ it('404s on an unknown batch id', async () => {
+ const req = makeGetReq('/api/forge-batch?batch=does-not-exist');
+ const res = makeRes();
+ await handler(req, res);
+ expect(res.statusCode).toBe(404);
+ expect(res.body.error).toBe('batch_not_found');
+ });
+
+ it('400s when no batch id is passed', async () => {
+ const req = makeGetReq('/api/forge-batch');
+ const res = makeRes();
+ await handler(req, res);
+ expect(res.statusCode).toBe(400);
+ expect(res.body.error).toBe('missing_batch');
+ });
+});