@vgai/fal-client-compat

Fal execution modes without a VGAI generation API.

npm install --save-dev @fal-ai/[email protected] @vgai/fal-client-compat

The package follows VGAI's source-readable package doctrine and publishes its TypeScript src/ directly. It is author-time tooling; projects that do not generate through Fal do not install it.

Game code continues to use the upstream package and upstream endpoint types:

import { fal } from '@fal-ai/client';

const result = await fal.subscribe('fal-ai/nano-banana-2', {
  input: { prompt: 'a brass owl game icon', output_format: 'png', resolution: '1K' },
});

Reference-conditioned editing uses Fal's native edit endpoint and passes the reference images directly:

const result = await fal.run('fal-ai/nano-banana-2/edit', {
  input: {
    prompt: 'preserve the composition and apply the material reference',
    image_urls: [compositionDataUrl, materialReferenceUrl],
    output_format: 'png',
    resolution: '1K',
  },
});

The host selects execution before game setup. Mock mode replaces only standard Fetch and performs no network I/O:

import { fal } from '@fal-ai/client';
import { createMockFalFetch } from '@vgai/fal-client-compat/mock';

fal.config({ credentials: 'vgai-mock', fetch: createMockFalFetch() });

Direct/BYOK mode is Fal's normal credentials configuration. An optional Fetch observer makes its request id automatic provenance without touching the credential or authored call:

import { createFalClient } from '@fal-ai/client';
import { createDirectFalFetch } from '@vgai/fal-client-compat/direct';

const fal = createFalClient({
  credentials: userFalKey,
  fetch: createDirectFalFetch(),
});

Managed mode is also configured through Fal's native client options:

import { createFalClient } from '@fal-ai/client';
import { createManagedFalFetch } from '@vgai/fal-client-compat/managed';

const gatewayUrl = 'https://generation.vgai.example';
const fal = createFalClient({
  credentials: undefined,
  proxyUrl: { url: `${gatewayUrl}/fal/proxy`, when: 'always' },
  fetch: createManagedFalFetch({
    gatewayUrl,
    accessToken: () => vgaiSession.accessToken(),
  }),
});

The helper does not add a generation API. It only authenticates Fal's normal proxy and artifact requests and observes the gateway's audit headers. When generated bytes are committed through the project output writer, those facts are consumed automatically into the one .vgai/provenance.json transaction.

The mock compatibility surface currently implements these native Fal endpoints for fal.run, fal.subscribe, and the corresponding queue calls:

• fal-ai/nano-banana-2 emits deterministic PNGs containing readable request parameters and a hash-derived visual pattern. fal-ai/nano-banana-2/edit does the same while requiring at least one reference image and including the ordered image_urls list in artifact identity. The original Nano Banana endpoints remain supported for existing authored calls, but are not VGAI's first-party defaults.
• fal-ai/stable-audio emits deterministic PCM WAV files. The request is embedded as standard WAV metadata and encoded into an audible hash-derived tone pattern, so parameter changes produce visibly and audibly distinct artifacts.
• fal-ai/sam-3/3d-objects emits deterministic 3DGS-style ASCII PLY with position, color, opacity, scale, and rotation properties. Three.js's real PLYLoader parses the same bytes used by project output.
• fal-ai/minimax/hailuo-02/standard/text-to-video emits a genuine VP8/WebM motion clip. Request hash selects its visible palette/motion design and the canonical request is retained in an ignorable EBML element; Chromium decode and playback are exercised by the heavy integration proof.
• fal-ai/hunyuan_world/image-to-world returns the endpoint's native world_file record. Its bytes mirror the live Hunyuan ZIP: deterministic source/full/sky PNGs plus indexed, vertex-colored mesh_layer0.ply and mesh_layer1.ply, both parsed by Three.js's real PLYLoader. World-to-scene conversion remains an explicit author-time import step; the mock does not pretend Fal returns a VGAI scene document.
• fal-ai/hunyuan_world returns the endpoint's native image record as a deterministic 2:1 equirectangular PNG panorama.

Unsupported endpoints and unsupported compatibility subsets fail loudly.