Skip to main content
POST
Create a scene
Send a JSON body with a sessionId and either a prompt or a panoramaUri. With a prompt, the scene model first generates a 360° panorama — optionally guided by reference images — and then builds the scene from it; with panoramaUri, it builds the scene from your panorama. The request is asynchronous: it answers immediately with a processing Scene Task whose ID starts with scn_, and you poll Get Scene Task until it finishes. A ready pano task gives you the scene as an .spz Gaussian splat, the panorama, and an initial image batch of posed views. Pass that batch’s batchId to Generate Scene Views and Reconstruct Scene to extend the scene.
Pricing: scene tasks don’t currently consume credits.

Sessions

Every scene request names a sessionId of your choosing. A session holds one scene and every image batch made for it:
  • sessionId is 1–128 ASCII letters, digits, underscores, or hyphens. It is scoped to your account, so it can’t collide with another customer’s.
  • A session runs one task at a time. Submitting while a task is still processing answers 409 with that task’s ID in error.details.running_task_id — poll it, then submit again.
  • referenceBatchIds on generate and reconstruct only accept batches made in the same session; a batch from another session fails the task with INVALID_REQUEST.

Request parameters

Send application/json, up to 1 MiB. Unknown fields are rejected.

URL rules

panoramaUri, referenceImages, spzOutputUrl, and outputUris are fetched or written by Viggle’s servers, so each must be:
  • http or https, without a username or password, with a valid port if one is given;
  • on a host that resolves only to public internet addresses. Private, loopback, link-local, and carrier-grade NAT addresses are rejected with 400.

Upload to your own storage

spzOutputUrl, or outputUris.spz / outputUris.preview / outputUris.panorama, are URLs Viggle uploads the finished file to with an HTTP PUT — typically presigned upload URLs from S3, R2, or GCS. They are optional; without them, download the files from the task result while it is readable.
  • spzOutputUrl is the same as outputUris.spz; send one or the other.
  • An .spz sent to your URL is not kept by Viggle: the result’s spz.url is your URL.
  • A preview or panorama sent to your URL is also kept by Viggle, and the result still links to Viggle’s signed copy.
  • A null entry in outputUris is ignored. The same fields are accepted by every scene operation.

Response parameters

Returns 200 OK with a Scene Task in processing state — the same shape Get Scene Task returns:

Common errors

A task that starts can still fail later; see Status and errors.

Examples

From an existing panorama

To place the panorama at a known position and scale in your own world, use Create Scene from Custom Panorama instead.

With reference images and your own storage

Next step

Get Scene Task

Poll the task and read the result.

Quick Start: Scene Model

The full build, generate, and reconstruct flow.

Authorizations

Authorization
string
header
required

Server-side SDK clients use a project API key. Remote MCP clients use an OAuth access token. Never expose a project API key in browser code.

Headers

X-Request-Id
string

Optional caller-supplied correlation ID, up to 128 characters. The service returns the effective value in the response header for tracing and support.

Required string length: 1 - 128
X-Viggle-Source
string

Optional source-channel label, up to 128 characters, used to attribute traffic to an SDK, integration, product surface, or internal workflow.

Required string length: 1 - 128

Body

application/json

Body of POST /v1/scenes/pano. Send either prompt (optionally with referenceImages and quality) or panoramaUri, not both. spzOutputUrl and outputUris are mutually exclusive. Input URLs must be http(s), without credentials, on a host that resolves only to public addresses.

sessionId
string
required

Session chosen by the caller, scoped to the caller's account. A session holds one scene and its image batches, and runs one task at a time: a submission while a task is still processing answers 409 with that task in error.details.running_task_id.

Required string length: 1 - 128
Pattern: ^[A-Za-z0-9_-]+$
Example:

"living-room-01"

prompt
string

Scene description; a 360° panorama is generated from it. Must not be blank.

Required string length: 1 - 1000
referenceImages
string<uri>[]

Image URLs that guide panorama generation. Only with prompt.

Maximum array length: 8
quality
enum<string>
default:low

Panorama generation quality. Only with prompt.

Available options:
fast,
low,
medium,
high
panoramaUri
string<uri>

URL of an existing 360° panorama to build the scene from. Not combinable with prompt, referenceImages, or quality.

spzOutputUrl
string<uri>

Same as outputUris.spz.

outputUris
object

The caller's own upload URLs; Viggle PUTs each finished file to its URL. Null entries are ignored. An .spz sent here is not kept by Viggle, and the result's spz.url is this URL; a preview or panorama sent here is also kept, and the result links to Viggle's copy. Each URL must be http(s), without credentials, on a host that resolves only to public addresses.

Response

Scene task started.

A scene task (scn_ prefix), returned by every /v1/scenes submission and by GET /v1/scenes/{task_id}. ready, failed, and cancelled are terminal. A task stays readable for about 72 hours after it finishes.

id
string
required

Task ID, scn_{runId}.{sessionId}.

sessionId
string
required
operation
enum<string>
required

A custom-pano task reports pano.

Available options:
pano,
generate,
reconstruct
status
enum<string>
required
Available options:
processing,
ready,
failed,
cancelled
createdAt
integer<int64> | null
required

Start time, Unix milliseconds.

completedAt
integer<int64> | null
required

End time, Unix milliseconds; null while processing.

result
object | null
required

Set only when ready.

error
object | null
required

Set only when failed. code is INVALID_REQUEST (not retryable — the model rejected the input, such as a batch from another session) or PROCESSING_FAILED (retryable).