@vgai/tripo-openapi-compat

Tripo execution modes without a VGAI model-generation API.

npm install --save-dev @vgai/tripo-openapi-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 use Tripo do not install it.

Tripo's current JavaScript API is ordinary Fetch against its v3 OpenAPI. Keep that authored call unchanged:

const created = await fetch('https://openapi.tripo3d.ai/v3/generation/image-to-model', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    file_token: uploadedReferenceToken,
    model: 'P1-20260311',
    face_limit: 5000,
    texture: true,
  }),
});
const { data } = await created.json();

The host selects mock mode by installing the compatible Fetch implementation:

import { createMockTripoFetch } from '@vgai/tripo-openapi-compat/mock';

const tripoFetch = createMockTripoFetch({ fallbackFetch: globalThis.fetch });

The deterministic compatibility slice implements the current v3 text-to-model, image-to-model, multiview-to-model, rig-check, rig, and batched retarget lifecycle, including /v3/tasks/:id polling and ordinary GLB download. Every mock task immediately reports native success with zero credit use. Static GLBs contain request-derived geometry and vertex colors plus canonical input in glTF extras. Rig tasks return a real skinned biped GLB. Each retarget task adds its requested animation presets as named clips with sampled limb animation, explicit -Z gameplay forward, and no root motion. Forced FBX and other unimplemented output modes fail loudly.

Direct/BYOK uses normal Fetch and Tripo's bearer credential. To capture its task/model facts automatically, use the pass-through observer as that Fetch:

import { createDirectTripoFetch } from '@vgai/tripo-openapi-compat/direct';

const tripoFetch = createDirectTripoFetch();

It neither adds nor owns the Authorization header. Managed mode keeps the same URLs and request bodies, changing only the Fetch implementation:

import { createManagedTripoFetch } from '@vgai/tripo-openapi-compat/managed';

const tripoFetch = createManagedTripoFetch({
  gatewayUrl: 'https://generation.vgai.example',
  accessToken: () => vgaiSession.accessToken(),
});

const created = await tripoFetch('https://openapi.tripo3d.ai/v3/generation/image-to-model', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ file_token: uploadedReferenceToken, model: 'P1-20260311' }),
});

Only the current openapi.tripo3d.ai/v3/* and returned VGAI artifact URLs are redirected and authenticated. Other Fetch traffic is passed through. Task and managed-job facts flow automatically into project provenance when outputs are committed. Unsupported task types and output features fail loudly in mock mode.