Add a BYOK AI splat-generation workflow

Background

SuperSplat currently supports importing existing splat files into the editor. We want to add a signed-in creation flow that lets users generate a new splat from text, image, or panorama inputs using their own API key.

The first provider is SpAItial API, but the implementation should be generic enough to support other world/splat generation APIs later.

Important repo boundary: the signed-in gallery page and Upload Splat button appear to live in the host app, while this repository is the standalone SuperSplat editor mounted at /editor.

Goal

Add a Create action next to Upload Splat in the signed-in host UI. The flow should open a BYOK modal where users can provide a provider API key, create a splat, track generation progress, and import the generated result into SuperSplat.

Proposed Architecture

Introduce a generic world-generation provider interface in the editor layer, with Spaitial as the first adapter.

Provider responsibilities:

• Validate or accept a user-provided API key.
• Expose available models.
• Create a generation job.
• Poll job status.
• Download the generated splat artifact.
• Optionally cancel the remote job.
• Return a browser File/Blob that can be passed into the existing SuperSplat import pipeline.

The existing editor import path should be reused:

events.invoke('import', [{ filename, contents }])

This is preferred over URL import for SpAItial because SpAItial artifact URLs require Authorization: Bearer <user key>, and the existing URL import path cannot attach BYOK auth headers.

SpAItial MVP

Support these inputs:

• Text prompt.
• Image URL.
• Local image upload.

Spaitial API mapping:

• Text: POST /v1/worlds with { input: { type: "text", prompt } }
• Image URL: { input: { type: "url", image_url } }
• Panorama URL: { input: { type: "url", image_url, is_pano: true } }
• Local image/pano: POST /v1/files, then use { input: { type: "file_id", file_id, is_pano? } }
• Poll: GET /v1/worlds/requests/:request_id/status
• Result: fetch /v1/worlds/requests/:request_id/splat with auth, follow redirect, import downloaded .spz or .sog

Use output_format: "spz" initially because SuperSplat already supports .spz imports.

BYOK Requirements

• API key is provided by the user.
• Key must not be sent to PlayCanvas/SuperSplat publish APIs.
• Key must not be placed in URLs or query params.
• Default storage should be session-only.
• Optional “Remember on this device” can be added later or behind explicit approval.
• Errors should expose provider error code/message where available.

UI Scope

Host app:

• Add Create button next to Upload Splat.
• Decide whether the modal lives in the host app or opens the editor create flow.

Editor repo:

• Add Create Splat... entry to the File menu.
• Add create dialog using existing PCUI settings-dialog patterns.
• Add provider selector, API key field, input mode fields, title, model selector, and create action.
• Reuse existing progress overlay and popup error patterns.
• Import the completed .spz into the current scene.

Acceptance Criteria

• Signed-in users can start a Create flow from the gallery host UI.
• Users can generate a splat using Spaitial BYOK from text, image, or panorama.
• Local files are uploaded to Spaitial via /v1/files.
• Job progress/status is shown while polling.
• User can cancel local waiting; if possible, remote cancellation is attempted.
• On completion, the generated .spz is loaded into SuperSplat automatically.
• API keys are never put in URLs.
• The implementation uses a provider abstraction so future APIs can be added without rewriting the modal/import pipeline.

Open Questions

• Which repo owns the gallery host UI with Upload Splat?
• Should the MVP modal live in the host app or inside the editor?
• Should generated splats be imported only, or also uploaded/published to the user’s SuperSplat gallery?