> ## Documentation Index
> Fetch the complete documentation index at: https://docs.viggle.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Scene Task
> Retrieve the state of a scene task, and its scene, panorama, and image downloads once ready.
`GET /v1/scenes/{task_id}` returns the current state of a task started by [Create Scene](/v1/api-reference/scenes/pano), [Create Scene from Custom Panorama](/v1/api-reference/scenes/custom-pano), [Generate Scene Views](/v1/api-reference/scenes/generate), or [Reconstruct Scene](/v1/api-reference/scenes/reconstruct) — the same Scene Task object the submission answered with. Poll every 5 seconds while `status` is `queued` or `processing`, until it is `ready`, `failed`, or `cancelled`, then download the files under `result`.
Tasks belong to your account — your organization, or your user when the key has no organization — so any API key of the same account can read them. An unknown ID, or one from another account, answers `404 INVALID_REQUEST`.
## Request parameters
| Parameter | Type | Required | Description |
| - | - | :-: | - |
| `task_id` | string | Yes | Full task ID returned by a submission, `scn_` prefix. It has the form `scn_{runId}.{sessionId}`; use it exactly as returned. |
## Response parameters
Returns `200 OK` with a Scene Task object. Field names are camelCase.
| Field | Type | Description |
| - | - | - |
| `id` | string | Task ID, `scn_` prefix. |
| `sessionId` | string | The `sessionId` you submitted the task under. |
| `operation` | string | `pano`, `generate`, or `reconstruct`. A [custom-pano](/v1/api-reference/scenes/custom-pano) task reports `pano`. |
| `status` | string | `queued`, `processing`, `ready`, `failed`, or `cancelled` — see [Status and errors](#status-and-errors). |
| `queuePosition` | integer | Only while `queued`: how many tasks wait ahead of this one, `0` when it is next. |
| `credits` | number | Credits this task is charged — see [Pricing](/v1/pricing#scene-model). Reserved at submission; `0` once a task that didn't finish `ready` has been refunded. |
| `createdAt` | integer | Submission time, Unix milliseconds. |
| `completedAt` | integer or null | End time, Unix milliseconds; `null` while `queued` or `processing`. |
| `result` | object or null | Set only when `status` is `ready` — see [Result](#result). |
| `error` | object or null | Set only when `status` is `failed`. |
### Result
| Field | Type | Description |
| - | - | - |
| `operation` | string | Same as the task's `operation`. |
| `sessionId` | string | Same as the task's `sessionId`. |
| `spz` | object or null | The 3D Gaussian-splat scene, as `{ "url": ... }`, in [SPZ](https://github.com/nianticlabs/spz) format. Produced by `pano` and `reconstruct`. If you sent `spzOutputUrl` (or `outputUris.spz`), the file was uploaded only to your URL and `url` is that URL. |
| `preview` | object or null | A preview image, as `{ "url": ... }`, when the operation produced one. |
| `panorama` | object or null | The 360° panorama the scene was built from, as `{ "url": ... }` — generated from your prompt, or the one you supplied. Produced by `pano`. |
| `outputBatch` | object or null | The image batch this task added to the session — see [Output batch](#output-batch). Produced by `pano` (the initial views) and `generate` (the new views); `null` for `reconstruct`. |
| `referenceViewCount` | integer | Number of reference views the task read from `referenceBatchIds`. `0` for `pano`. |
| `newViewCount` | integer | Number of new views the task produced. `0` for `reconstruct`. |
| `seconds` | object | Processing time by stage, in seconds, for example `{"model": 4.2}`. Keys vary by operation; treat them as informational. |
Every `url` Viggle signs is valid for **3 hours**. Fetch the task again for fresh ones.
### Output batch
A batch is a set of posed images in one session. Its `batchId` is what you pass in `referenceBatchIds` to [generate](/v1/api-reference/scenes/generate) more views or [reconstruct](/v1/api-reference/scenes/reconstruct) the scene.
| Field | Type | Description |
| - | - | - |
| `batchId` | string | Batch ID, a lowercase UUID. |
| `createdAt` | number | Batch creation time, Unix milliseconds. |
| `manifest` | object | The batch's `batch.json` manifest, as `{ "url": ... }`. |
| `kind` | string | `initial` for a batch made by `pano`, `generated` for one made by `generate`. |
| `views` | array | Every image in the batch, in order. |
| `views[].index` | integer | Position in the batch, from 0. |
| `views[].url` | string | Signed download URL of the image. |
| `views[].c2w` | number\[4]\[4] | Camera-to-world matrix of the view. For a custom-pano scene it's in your own world frame — see [Custom panorama](/v1/api-reference/scenes/custom-pano#coordinate-frame). |
| `views[].intrinsic` | number\[] | Camera intrinsics of the view, as recorded in the batch manifest. |
`kind` and `views` can be missing on tasks that finished before they were introduced; `manifest` is always there.
### Ready example
A `pano` task. Signature query parameters shortened:
```json theme={null}
{
"id": "scn_0199f0c2-6a1e-7c3d-9b2a-4f5e6d7c8b9a.living-room-01",
"sessionId": "living-room-01",
"operation": "pano",
"status": "ready",
"credits": 6,
"createdAt": 1791856740000,
"completedAt": 1791856800000,
"result": {
"operation": "pano",
"sessionId": "living-room-01",
"spz": { "url": "https://.../scene.spz?X-Amz-Signature=..." },
"preview": null,
"panorama": { "url": "https://.../panorama.png?X-Amz-Signature=..." },
"outputBatch": {
"batchId": "3f0a6c1e-8d2b-4b7a-9e5c-1a2b3c4d5e6f",
"createdAt": 1791856800000,
"manifest": { "url": "https://.../batch.json?X-Amz-Signature=..." },
"kind": "initial",
"views": [
{
"index": 0,
"url": "https://.../0.png?X-Amz-Signature=...",
"c2w": [[1, 0, 0, 0], [0, 1, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1]],
"intrinsic": [0.5, 0.5, 0.5, 0.5]
}
]
},
"referenceViewCount": 0,
"newViewCount": 6,
"seconds": { "model": 4.2 }
},
"error": null
}
```
### Failed example
```json theme={null}
{
"id": "scn_0199f0c2-6a1e-7c3d-9b2a-4f5e6d7c8b9a.living-room-01",
"sessionId": "living-room-01",
"operation": "generate",
"status": "failed",
"credits": 0,
"createdAt": 1791856740000,
"completedAt": 1791856765000,
"result": null,
"error": {
"code": "PROCESSING_FAILED",
"message": "The request could not be processed.",
"retryable": true,
"request_id": "req_7d3c...",
"details": {},
"remediation": { "action": "retry", "retry_after_ms": null }
}
}
```
## Status and errors
| `status` | Meaning |
| - | - |
| `queued` | Accepted and waiting for a GPU slot; `queuePosition` says how many tasks are ahead. The session accepts no other task until this one ends. |
| `processing` | Running. The session accepts no other task until this one ends. |
| `ready` | Done; `result` is filled in. |
| `failed` | Failed; see `error`. |
| `cancelled` | Stopped by Viggle before it finished. Submit the task again. |
Only a `ready` task keeps its charge. A `failed` or `cancelled` task — including one that never left `queued` — is refunded in full, and its `credits` reads `0` once the refund is made. Retrying means submitting a new task, which reserves its own credits.
`error.code` on a failed task:
| `code` | `retryable` | When | What to do |
| - | :-: | - | - |
| `INVALID_REQUEST` | `false` | The scene model rejected the input — for example, a `referenceBatchIds` entry that isn't a batch of this session. `message` says why. | Fix the input, then submit again. |
| `PROCESSING_FAILED` | `true` | Any other failure: the model, storage, or a timeout. | Submit the same request again. If it keeps happening, contact us with the task `id`. |
HTTP errors from this endpoint:
| HTTP | `code` | Meaning |
| - | - | - |
| `401` | `UNAUTHENTICATED` | Missing or invalid API key. |
| `404` | `INVALID_REQUEST` | No such task in your account, or it is past [retention](#retention). |
| `503` | `SERVICE_BUSY` | The scene model is temporarily unavailable. Retryable. |
These use the same error object as a failed task's `error`, wrapped as `{"error": {...}}`. See [Errors and recovery](/v1/production/errors).
## Retention
* A task can be read for about **72 hours** after it finishes; after that this endpoint answers `404`. Download what you need, or have Viggle upload it straight to your storage with [`outputUris`](/v1/api-reference/scenes/pano#upload-to-your-own-storage).
* Signed URLs last **3 hours** each; fetch the task again for fresh ones while it is still readable.
## Examples
```bash cURL theme={null}
curl https://apis.viggle.ai/v1/scenes/scn_0199f0c2-6a1e-7c3d-9b2a-4f5e6d7c8b9a.living-room-01 \
-H "Authorization: Bearer $VIGGLE_API_KEY"
```
```python Python theme={null}
import os, requests
response = requests.get(
"https://apis.viggle.ai/v1/scenes/scn_0199f0c2-6a1e-7c3d-9b2a-4f5e6d7c8b9a.living-room-01",
headers={"Authorization": f"Bearer {os.environ['VIGGLE_API_KEY']}"},
)
response.raise_for_status()
task = response.json()
```
```javascript JavaScript theme={null}
const response = await fetch("https://apis.viggle.ai/v1/scenes/scn_0199f0c2-6a1e-7c3d-9b2a-4f5e6d7c8b9a.living-room-01", {
headers: { Authorization: `Bearer ${process.env.VIGGLE_API_KEY}` },
});
const task = await response.json();
```
Build a scene, generate new views, and reconstruct it, end to end.
## OpenAPI
````yaml openapi.yaml GET /v1/scenes/{task_id}
openapi: 3.0.3
info:
title: Viggle API
description: Generate AI-powered character animation videos
version: 2.0.0
contact:
name: Viggle Support
url: https://viggle.ai
servers:
- url: https://apis.viggle.ai
description: Production server
security:
- bearerAuth: []
tags:
- name: Renders
description: Prepare inputs, create renders, observe progress, and retrieve results.
- name: Credits
description: Read the credit balance available to the calling principal.
- name: Characters
description: |
Create, list, inspect, and delete reusable character assets. `type`
selects whether creation also extracts a 3D vsplat; export its
download URL separately once ready.
- name: Motions
description: |
Create, list, inspect, and delete reusable motion assets, and import one
from an official motion template. `type` selects whether creation also
extracts or generates a 3D animation; export its download URL
separately once ready.
- name: Videos
description: >
Generate a MiniMax H3 video from text, frames, or references (`vid_`
prefix) or a character-animation video from a character image and/or
driving video
(`anim_` prefix), and read the unified view over every video the
caller owns — H3 generations, character-animation generations, and
character+motion Renders (`render_` prefix) — merged into one
resource.
- name: Images
description: |
Viggle Image — generate 1–6 PNG images from a text prompt with the
`qwen` model, optionally guided by up to 8 reference images
(`img_` prefix), and retrieve them by ID.
- name: Scenes
description: |
Scene model — build a 3D Gaussian-splat scene (`.spz`) from a text
prompt or a 360° panorama, generate new posed views of it, and
reconstruct it from those views. Every operation is an asynchronous
task (`scn_` prefix) read back by ID. A pano from a prompt costs 6
credits; every other scene task costs 1. Credits are refunded in full
unless the task finishes `ready`.
paths:
/v1/scenes/{task_id}:
parameters:
- $ref: '#/components/parameters/SceneTaskId'
- $ref: '#/components/parameters/RequestId'
- $ref: '#/components/parameters/SourceChannel'
get:
tags:
- Scenes
summary: Get a scene task
description: |
Returns a scene task of the caller's account. Signed URLs in `result`
are valid for 3 hours and re-signed on every read. A task stays readable
for about 72 hours after it finishes, then answers `404`.
operationId: getSceneTask
responses:
'200':
description: Current scene task state.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/SceneTask'
'401':
$ref: '#/components/responses/V1Unauthorized'
'404':
$ref: '#/components/responses/SceneTaskNotFound'
'503':
$ref: '#/components/responses/ServiceUnavailable'
components:
parameters:
SceneTaskId:
name: task_id
in: path
required: true
description: >-
Scene task ID (`scn_` prefix, `scn_{runId}.{sessionId}`) returned by a
`/v1/scenes` submission. It must belong to the caller's account.
schema:
type: string
minLength: 1
example: scn_0199f0c2-6a1e-7c3d-9b2a-4f5e6d7c8b9a.living-room-01
RequestId:
name: X-Request-Id
in: header
required: false
description: >-
Optional caller-supplied correlation ID, up to 128 characters. The
service returns the effective value in the response header for tracing
and support.
schema:
type: string
minLength: 1
maxLength: 128
SourceChannel:
name: X-Viggle-Source
in: header
required: false
description: >-
Optional source-channel label, up to 128 characters, used to attribute
traffic to an SDK, integration, product surface, or internal workflow.
schema:
type: string
minLength: 1
maxLength: 128
headers:
RequestId:
description: Stable request identifier for support and tracing.
schema:
type: string
schemas:
SceneTask:
type: object
additionalProperties: false
description: >
A scene task (`scn_` prefix), returned by every `/v1/scenes`
submission and by `GET /v1/scenes/{task_id}`. It starts `queued` (or
`processing` when a GPU slot is free); `ready`, `failed`, and
`cancelled` are terminal. Only a `ready` task keeps its credits. A task
stays readable for about 72 hours
after it finishes.
required:
- id
- sessionId
- operation
- status
- credits
- createdAt
- completedAt
- result
- error
properties:
id:
type: string
description: Task ID, `scn_{runId}.{sessionId}`.
sessionId:
type: string
operation:
type: string
enum:
- pano
- generate
- reconstruct
description: A custom-pano task reports `pano`.
status:
type: string
enum:
- queued
- processing
- ready
- failed
- cancelled
queuePosition:
type: integer
minimum: 0
description: >-
Only while `queued`: tasks waiting ahead of this one, 0 when it is
next.
credits:
type: number
minimum: 0
description: >-
Credits this task is charged: reserved at submission (6 for a pano
from a prompt, 1 for any other task) and 0 once a task that did not
finish `ready` is refunded.
createdAt:
type: integer
format: int64
nullable: true
description: Start time, Unix milliseconds.
completedAt:
type: integer
format: int64
nullable: true
description: End time, Unix milliseconds; null while queued or processing.
result:
description: Set only when `ready`.
nullable: true
allOf:
- $ref: '#/components/schemas/SceneResult'
error:
description: |
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).
nullable: true
allOf:
- $ref: '#/components/schemas/ErrorBody'
SceneResult:
type: object
required:
- operation
- sessionId
- spz
- preview
- panorama
- outputBatch
- referenceViewCount
- newViewCount
- seconds
properties:
operation:
type: string
enum:
- pano
- generate
- reconstruct
sessionId:
type: string
spz:
description: >-
The Gaussian-splat scene in SPZ format; set by `pano` and
`reconstruct`.
nullable: true
allOf:
- $ref: '#/components/schemas/SceneFile'
preview:
description: A preview image, when the operation produced one.
nullable: true
allOf:
- $ref: '#/components/schemas/SceneFile'
panorama:
description: The panorama the scene was built from; set by `pano`.
nullable: true
allOf:
- $ref: '#/components/schemas/SceneFile'
outputBatch:
description: The batch this task added; null for `reconstruct`.
nullable: true
allOf:
- $ref: '#/components/schemas/SceneOutputBatch'
referenceViewCount:
type: integer
description: Views read from `referenceBatchIds`.
newViewCount:
type: integer
description: New views produced.
seconds:
type: object
description: Processing time by stage, in seconds. Informational; keys vary.
additionalProperties:
type: number
ErrorBody:
type: object
additionalProperties: false
required:
- code
- message
- retryable
- request_id
- details
- remediation
properties:
code:
description: Stable error category from the draft-based render error vocabulary.
allOf:
- $ref: '#/components/schemas/ErrorCode'
message:
type: string
description: >-
Human-readable explanation suitable for logs or presentation to a
developer.
retryable:
type: boolean
description: >-
Whether retrying the operation without changing its semantic input
may succeed.
request_id:
type: string
description: >-
Correlation identifier for tracing and support. Include it when
reporting the failure.
details:
type: object
description: Error-specific structured context; available keys depend on `code`.
additionalProperties: true
remediation:
description: Suggested recovery action and optional retry delay.
allOf:
- $ref: '#/components/schemas/ErrorRemediation'
ErrorResponse:
type: object
additionalProperties: false
required:
- error
properties:
error:
description: >-
Top-level draft-flow error payload containing the stable code,
message, retry guidance, correlation ID, and error-specific details.
allOf:
- $ref: '#/components/schemas/ErrorBody'
SceneFile:
type: object
additionalProperties: false
required:
- url
properties:
url:
type: string
format: uri
description: >-
Download URL. Viggle's signed URLs last 3 hours; fetch the task
again for fresh ones. For an `.spz` sent to the caller's own URL,
that URL.
SceneOutputBatch:
type: object
additionalProperties: false
required:
- batchId
- createdAt
- manifest
description: >-
The image batch a `pano` or `generate` task added to the session. `kind`
and `views` are missing on tasks that finished before they were
introduced.
properties:
batchId:
type: string
description: Batch ID, a lowercase UUID; pass it in `referenceBatchIds`.
createdAt:
type: number
description: Batch creation time, Unix milliseconds.
manifest:
$ref: '#/components/schemas/SceneFile'
kind:
type: string
enum:
- initial
- generated
views:
type: array
items:
$ref: '#/components/schemas/SceneView'
ErrorCode:
description: |
The failure vocabulary of the draft-based render flow. The resource
operations project the same vocabulary onto the lower_snake_case codes
described by `ResourceError`.
type: string
enum:
- UNAUTHENTICATED
- INVALID_CREDENTIAL
- FORBIDDEN
- INVALID_REQUEST
- INVALID_CHARACTER
- INVALID_MOTION
- UNSUPPORTED_MEDIA
- CONTENT_POLICY_VIOLATION
- UPLOAD_REQUIRED
- UPLOAD_MISMATCH
- UPLOAD_EXPIRED
- DRAFT_NOT_FOUND
- DRAFT_ALREADY_CONSUMED
- RENDER_NOT_FOUND
- RENDER_NOT_CANCELLABLE
- CHARACTER_NOT_FOUND
- MOTION_NOT_FOUND
- MOTION_NOT_READY
- MOTION_TEMPLATE_NOT_FOUND
- AVATAR_NOT_FOUND
- ANIMATION_NOT_FOUND
- EXTRACTION_UNAVAILABLE
- EXTRACTION_FAILED
- IDEMPOTENCY_KEY_REUSED
- INSUFFICIENT_CREDITS
- RATE_LIMITED
- SERVICE_BUSY
- INTERNAL_ERROR
- NOT_FOUND
- TASK_FAILED
- PROCESSING_FAILED
ErrorRemediation:
type: object
additionalProperties: false
required:
- action
- retry_after_ms
properties:
action:
type: string
description: >-
Suggested machine-readable or human-readable next action, such as
retrying later, uploading media again, or correcting input.
retry_after_ms:
type: integer
description: >-
Recommended delay in milliseconds before retrying; null when no
timed retry is advised.
nullable: true
format: int64
minimum: 0
SceneView:
type: object
additionalProperties: false
required:
- index
- url
- c2w
- intrinsic
properties:
index:
type: integer
minimum: 0
description: Position in the batch, from 0.
url:
type: string
format: uri
description: Signed download URL of the image, valid for 3 hours.
c2w:
$ref: '#/components/schemas/SceneMatrix'
intrinsic:
type: array
description: Camera intrinsics, as recorded in the batch manifest.
items:
type: number
SceneMatrix:
type: array
description: >-
4 × 4 camera-to-world matrix as four rows of four finite numbers; the
last row must be `[0, 0, 0, 1]`.
minItems: 4
maxItems: 4
items:
type: array
minItems: 4
maxItems: 4
items:
type: number
example:
- - 1
- 0
- 0
- 0
- - 0
- 1
- 0
- 0
- - 0
- 0
- 1
- 0
- - 0
- 0
- 0
- 1
responses:
V1Unauthorized:
description: Missing, invalid, or expired credential.
headers:
WWW-Authenticate:
schema:
type: string
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
SceneTaskNotFound:
description: >-
No such scene task in the caller's account, or it is past retention.
Code `INVALID_REQUEST`.
headers:
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
ServiceUnavailable:
description: Service temporarily unavailable.
headers:
Retry-After:
schema:
type: integer
minimum: 0
X-Request-Id:
$ref: '#/components/headers/RequestId'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: API key or OAuth access token
description: |
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.
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.