> ## 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.

# Generate Scene Views

> Generate new images of a scene from a camera pose you choose, as a new image batch.

Generate new views of a session's scene from a camera you place. The model reads the image batches you list in `referenceBatchIds` and renders new images as seen from the camera you give — a `targetC2w` matrix, or a `targetPosition` with yaw and pitch angles — which become a new `generated` batch in the session. Use them to fill in parts of the scene the existing views don't cover, then pass the new `batchId`, together with the earlier ones, to [Reconstruct Scene](/v1/api-reference/scenes/reconstruct) for an updated `.spz`.

The request is asynchronous: it answers with a `queued` [Scene Task](/v1/api-reference/scenes/get); poll it until it finishes.

<Note>
  **Pricing** (1 credit = $0.01): **1 credit ($0.01)\*\* per task, reserved when it is submitted and refunded in full unless it finishes `ready`. See [Pricing](/v1/pricing#scene-model).
</Note>

## Request parameters

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

| Parameter | Type | Required | Default | Description |
| - | - | :-: | - | - |
| `sessionId` | string | Yes | — | The session whose scene to extend — see [Sessions](/v1/api-reference/scenes/pano#sessions). |
| `referenceBatchIds` | string\[] | Yes | — | 1–35 batch IDs from this session, as returned in `result.outputBatch.batchId`. Lowercase UUIDs, no repeats. |
| `targetC2w` | number\[4]\[4] | One of `targetC2w` / `targetPosition` | — | Camera-to-world matrix to render from, in the same frame as the views' `c2w`. The last row must be `[0, 0, 0, 1]`. |
| `targetPosition` | object | One of `targetC2w` / `targetPosition` | — | The camera as a position and two angles instead of a matrix: `{"position": [x, y, z], "yaw": degrees, "pitch": degrees}` — see [Target position](#target-position). |
| `projection` | string | No | `perspective` | `perspective` for regular camera images, `pano` for a 360° panorama at the target camera. |
| `fov` | number | No | model default | Field of view in degrees, 20–140. |
| `seed` | integer | No | `1` | 0–4294967295. The same inputs and seed give the same images. |
| `spzOutputUrl` | string | No | — | Accepted as on every scene operation — see [Upload to your own storage](/v1/api-reference/scenes/pano#upload-to-your-own-storage). |
| `outputUris` | object | No | — | Your own upload URLs per file: `spz`, `preview`, `panorama`. Can't be combined with `spzOutputUrl`. |

<Tip>
  The easiest way to get a valid `targetC2w` is to start from a view's `c2w` in a batch you already have and move or turn it. A camera close to the existing views gives the most consistent images.
</Tip>

## Target position

`targetPosition` places the camera without writing a matrix. Send exactly one of `targetC2w` and `targetPosition`; sending both, or neither, is rejected.

| Field | Type | Required | Default | Description |
| - | - | :-: | - | - |
| `position` | number\[3] | Yes | — | The camera's position `[x, y, z]`, in the same frame as the views' `c2w`. |
| `yaw` | number | No | `0` | Turn about the world's +Y axis, in degrees. Positive turns left. |
| `pitch` | number | No | `0` | Tilt up or down, in degrees, from `-90` to `90`. Positive looks up. |

No other fields are accepted, and a `null` angle counts as `0`. The angles use the same OpenGL convention as `c2w`: world +Y is up, and the camera looks down its own −Z axis with +X to its right. With `yaw` and `pitch` both `0` the camera looks down world −Z; `yaw: 90` looks down −X, and `pitch: 90` looks straight up.

The request is turned into the `targetC2w` it stands for, with rotation `R = Ry(yaw) · Rx(pitch)` and `position` as the translation:

```text theme={null}
| cos(yaw)   sin(yaw)·sin(pitch)   sin(yaw)·cos(pitch)   x |
| 0          cos(pitch)            −sin(pitch)           y |
| −sin(yaw)  cos(yaw)·sin(pitch)   cos(yaw)·cos(pitch)   z |
| 0          0                     0                     1 |
```

Roll isn't expressible: the camera's horizon stays level. Use `targetC2w` for a rolled camera.

## Response parameters

Returns `200 OK` with a `queued` (or already `processing`) Scene Task:

```json theme={null}
{
  "id": "scn_0199f0c4-1b2c-7d3e-8f4a-5b6c7d8e9f0a.living-room-01",
  "sessionId": "living-room-01",
  "operation": "generate",
  "status": "queued",
  "credits": 1,
  "queuePosition": 0,
  "createdAt": 1791856900000,
  "completedAt": null,
  "result": null,
  "error": null
}
```

When it's `ready`, `result.outputBatch` is the new `generated` batch, with every new image and its camera in `views`, and `result.newViewCount` is how many there are. `result.spz` is `null` — run [Reconstruct Scene](/v1/api-reference/scenes/reconstruct) to fold the new views into the scene.

## Common errors

| Error | Cause |
| - | - |
| `400 INVALID_REQUEST` | A field is missing, invalid, or unknown — for example `referenceBatchIds` is empty, has more than 35 IDs or a repeat, `targetC2w` isn't a 4 × 4 matrix whose last row is `[0, 0, 0, 1]`, both or neither of `targetC2w` and `targetPosition` are sent, or `targetPosition` has a missing `position`, an unknown field, or a `pitch` outside `-90`–`90`. |
| `401 UNAUTHENTICATED` | Missing or invalid API key. |
| `402 INSUFFICIENT_CREDITS` | The balance can't cover the task's price. Nothing is queued. |
| `409 INVALID_REQUEST` | The session already has a task `queued` or `processing`; see `error.details.running_task_id`. |
| `429 RATE_LIMITED` | Too many concurrent submissions on the same key. Retry shortly. |
| `503 SERVICE_BUSY` | The scene model is temporarily unavailable. Retryable. |

A batch ID that's well-formed but not from this session is caught by the model: the task starts and then fails with `INVALID_REQUEST`.

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://apis.viggle.ai/v1/scenes/generate \
    -H "Authorization: Bearer $VIGGLE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "sessionId": "living-room-01",
      "referenceBatchIds": ["3f0a6c1e-8d2b-4b7a-9e5c-1a2b3c4d5e6f"],
      "targetC2w": [[1, 0, 0, 0.5], [0, 1, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1]],
      "projection": "perspective",
      "fov": 75,
      "seed": 7
    }'
  ```

  ```python Python theme={null}
  import os, requests
  response = requests.post(
      "https://apis.viggle.ai/v1/scenes/generate",
      headers={"Authorization": f"Bearer {os.environ['VIGGLE_API_KEY']}"},
      json={
          "sessionId": "living-room-01",
          "referenceBatchIds": ["3f0a6c1e-8d2b-4b7a-9e5c-1a2b3c4d5e6f"],
          "targetC2w": [[1, 0, 0, 0.5], [0, 1, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1]],
          "projection": "perspective",
          "fov": 75,
          "seed": 7,
      },
  )
  response.raise_for_status()
  task = response.json()
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://apis.viggle.ai/v1/scenes/generate", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.VIGGLE_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      sessionId: "living-room-01",
      referenceBatchIds: ["3f0a6c1e-8d2b-4b7a-9e5c-1a2b3c4d5e6f"],
      targetC2w: [[1, 0, 0, 0.5], [0, 1, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1]],
      projection: "perspective",
      fov: 75,
      seed: 7,
    }),
  });
  const task = await response.json();
  ```
</CodeGroup>

### From a position and angles

The same session, with a camera at `[0.5, 1.2, 0]` turned 30° to the left and tilted 10° down:

```bash theme={null}
curl -X POST https://apis.viggle.ai/v1/scenes/generate \
  -H "Authorization: Bearer $VIGGLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "living-room-01",
    "referenceBatchIds": ["3f0a6c1e-8d2b-4b7a-9e5c-1a2b3c4d5e6f"],
    "targetPosition": { "position": [0.5, 1.2, 0], "yaw": 30, "pitch": -10 }
  }'
```

<Card title="Quick Start: Scene Model" icon="rocket" href="/v1/guides/quickstart-scene">
  See generate in the full build, generate, and reconstruct flow.
</Card>


## OpenAPI

````yaml openapi.yaml POST /v1/scenes/generate
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/generate:
    post:
      tags:
        - Scenes
      summary: Generate scene views
      description: >
        Generates new views of the session's scene from `targetC2w` or

        `targetPosition`, using

        the batches in `referenceBatchIds`. A ready result's `outputBatch` is
        the

        new `generated` batch; `spz` is null. Costs 1 credit.
      operationId: generateSceneViews
      parameters:
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/SourceChannel'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SceneGenerateRequest'
      responses:
        '200':
          description: Scene task started.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SceneTask'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/V1Unauthorized'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '409':
          $ref: '#/components/responses/SceneSessionBusy'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  parameters:
    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
  schemas:
    SceneGenerateRequest:
      type: object
      additionalProperties: false
      description: >-
        Body of `POST /v1/scenes/generate`. Send exactly one of `targetC2w` and
        `targetPosition`. `spzOutputUrl` and `outputUris` are mutually
        exclusive.
      required:
        - sessionId
        - referenceBatchIds
      properties:
        sessionId:
          $ref: '#/components/schemas/SceneSessionId'
        referenceBatchIds:
          $ref: '#/components/schemas/SceneBatchIds'
        targetC2w:
          allOf:
            - $ref: '#/components/schemas/SceneMatrix'
          description: >-
            Camera to render from, in the frame of the views' `c2w`. Exactly one
            of `targetC2w` and `targetPosition`.
        targetPosition:
          allOf:
            - $ref: '#/components/schemas/SceneTargetPosition'
          description: >-
            Camera as a position, yaw, and pitch. Exactly one of `targetC2w` and
            `targetPosition`.
        projection:
          type: string
          enum:
            - perspective
            - pano
          default: perspective
          description: >-
            `perspective` for camera images, `pano` for a 360° panorama at the
            target camera.
        fov:
          type: number
          nullable: true
          minimum: 20
          maximum: 140
          description: Field of view in degrees. Omitted or null, the model's default.
        seed:
          type: integer
          format: int64
          minimum: 0
          maximum: 4294967295
          default: 1
        spzOutputUrl:
          type: string
          format: uri
          description: Same as `outputUris.spz`.
        outputUris:
          $ref: '#/components/schemas/SceneOutputUris'
    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'
    SceneSessionId:
      type: string
      minLength: 1
      maxLength: 128
      pattern: ^[A-Za-z0-9_-]+$
      description: |
        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`.
      example: living-room-01
    SceneBatchIds:
      type: array
      description: >-
        1–35 distinct batch IDs from the same session, as returned in
        `result.outputBatch.batchId`. A well-formed ID from another session
        fails the task with `INVALID_REQUEST`.
      minItems: 1
      maxItems: 35
      uniqueItems: true
      items:
        type: string
        pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
    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
    SceneTargetPosition:
      type: object
      additionalProperties: false
      description: |
        `generate`'s camera as a position and two angles instead of
        `targetC2w`, in the same frame and OpenGL convention: world +Y up,
        the camera looking down its −Z with +X to its right. The rotation is
        `R = Ry(yaw) · Rx(pitch)`: a positive yaw turns left about world +Y,
        a positive pitch looks up, and both `0` look down −Z.
      required:
        - position
      properties:
        position:
          type: array
          minItems: 3
          maxItems: 3
          items:
            type: number
          description: Camera position `[x, y, z]`.
        yaw:
          type: number
          nullable: true
          default: 0
          description: Degrees about world +Y; positive turns left. Null counts as `0`.
        pitch:
          type: number
          nullable: true
          minimum: -90
          maximum: 90
          default: 0
          description: >-
            Degrees up or down, `-90` to `90`; positive looks up. Null counts as
            `0`.
      example:
        position:
          - 0.5
          - 1.2
          - 0
        yaw: 30
        pitch: -10
    SceneOutputUris:
      type: object
      additionalProperties: false
      description: |
        The caller's own upload URLs; Viggle `PUT`s 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.
      properties:
        spz:
          type: string
          format: uri
          nullable: true
        preview:
          type: string
          format: uri
          nullable: true
        panorama:
          type: string
          format: uri
          nullable: true
    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
  headers:
    RequestId:
      description: Stable request identifier for support and tracing.
      schema:
        type: string
  responses:
    BadRequest:
      description: Invalid request.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    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'
    PaymentRequired:
      description: Insufficient credits.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    SceneSessionBusy:
      description: >-
        The session already has a task queued or running;
        `error.details.running_task_id` names it. Code `INVALID_REQUEST`.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: Rate limit exceeded.
      headers:
        Retry-After:
          schema:
            type: integer
            minimum: 0
        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.