@vgai/worldlabs-api-compat

World Labs Marble execution modes without a VGAI world-generation API.

npm install --save-dev @vgai/worldlabs-api-compat

World Labs' documented API is ordinary Fetch. Keep the authored upload, generation, polling, and export-download lifecycle unchanged. The host chooses one compatible Fetch implementation:

import { createMockWorldLabsFetch } from '@vgai/worldlabs-api-compat/mock';

const worldLabsFetch = createMockWorldLabsFetch({ fallbackFetch: globalThis.fetch });
const operation = await worldLabsFetch(
  'https://api.worldlabs.ai/marble/v1/worlds:generate',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      display_name: 'Crystal citadel',
      model: 'marble-1.1',
      world_prompt: { type: 'text', text_prompt: 'A floating crystal citadel' },
    }),
  },
).then((response) => response.json());

Mock mode implements credits, media upload preparation and signed upload, world generation, operation polling, and ordinary export downloads. It returns provider-shaped, immediately completed operations with zero credit cost. Its 2:1 PNG panorama, GLB collider, and SPZ scene are deterministic and encode the canonical request in visible color/text patterns and asset metadata.

Direct/BYOK mode observes normal Fetch while leaving the caller's WLT-Api-Key header untouched:

import { createDirectWorldLabsFetch } from '@vgai/worldlabs-api-compat/direct';
const worldLabsFetch = createDirectWorldLabsFetch();

Managed mode keeps the same World Labs URLs and bodies while moving the API credential to the gateway:

import { createManagedWorldLabsFetch } from '@vgai/worldlabs-api-compat/managed';
const worldLabsFetch = createManagedWorldLabsFetch({
  gatewayUrl: 'https://generation.vgai.example',
  accessToken: () => vgaiSession.accessToken(),
});

The provider-issued signed media upload remains a normal direct upload; it already carries its own scoped, temporary authorization and never exposes the World Labs API key. Completed export URLs are rewritten to authenticated VGAI artifact URLs by managed mode. Generation/model/operation facts flow into the project's normal provenance automatically when outputs are committed.