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

# 重建场景

> 用会话的图像批次重建 3D 场景，生成新的 .spz。

用你列出的图像批次重建场景的 `.spz` 高斯泼溅，通常是[创建场景](/zh/v1/api-reference/scenes/pano)产生的 `initial` 批次，加上[生成场景视图](/zh/v1/api-reference/scenes/generate)产生的 `generated` 批次。视图覆盖的场景越多，结果越完整。

接口是异步的：返回 `queued` 状态的[场景任务](/zh/v1/api-reference/scenes/get)，轮询直到任务结束。

<Note>
  **计费**（1 积分 = \$0.01）：每个任务 **1 积分（\$0.01）**，提交时预扣，任务未以 `ready` 结束则全额退回。见[计费](/zh/v1/pricing#scene-model)。
</Note>

## 请求参数

使用 `application/json`，最大 1 MiB。不接受未知字段。

| 参数 | 类型 | 必填 | 默认值 | 说明 |
| - | - | :-: | - | - |
| `sessionId` | string | 是 | — | 要重建其场景的会话，见[创建场景](/zh/v1/api-reference/scenes/pano)中的“会话”一节。 |
| `referenceBatchIds` | string\[] | 是 | — | 1–35 个本会话的批次 ID，即 `result.outputBatch.batchId` 中返回的值。小写 UUID，不能重复。 |
| `spzOutputUrl` | string | 否 | — | 你自己的 `.spz` 场景上传地址，见[创建场景](/zh/v1/api-reference/scenes/pano)中的“上传到自己的存储”一节。 |
| `outputUris` | object | 否 | — | 按文件指定你自己的上传地址：`spz`、`preview`、`panorama`。不能与 `spzOutputUrl` 同时使用。 |

`targetC2w`、`projection`、`fov` 和 `seed` 属于[生成场景视图](/zh/v1/api-reference/scenes/generate)，在本接口中会被拒绝。

## 响应参数

返回 `200 OK` 和 `queued`（或已经是 `processing`）状态的场景任务：

```json theme={null}
{
  "id": "scn_0199f0c6-9a8b-7c6d-8e5f-4a3b2c1d0e9f.living-room-01",
  "sessionId": "living-room-01",
  "operation": "reconstruct",
  "status": "queued",
  "credits": 1,
  "queuePosition": 0,
  "createdAt": 1791857000000,
  "completedAt": null,
  "result": null,
  "error": null
}
```

任务 `ready` 后，`result.spz.url` 即重建后的场景，`result.referenceViewCount` 为使用的视图数量。`result.outputBatch` 为 `null`：重建不会向会话添加图像。

## 常见错误

| 错误 | 原因 |
| - | - |
| `400 INVALID_REQUEST` | 字段缺失、不合法或未知，例如 `referenceBatchIds` 为空、超过 35 个 ID 或有重复，或某个 ID 不是小写 UUID。 |
| `401 UNAUTHENTICATED` | 缺少或无效的 API 密钥。 |
| `402 INSUFFICIENT_CREDITS` | 余额不足以支付该任务，任务不会进入队列。 |
| `409 INVALID_REQUEST` | 该会话已有任务处于 `queued` 或 `processing`，见 `error.details.running_task_id`。 |
| `429 RATE_LIMITED` | 同一密钥的并发提交过多，请稍后重试。 |
| `503 SERVICE_BUSY` | 场景模型暂时不可用，可重试。 |

格式正确但不属于本会话的批次 ID 由模型检查：任务会先开始，随后以 `INVALID_REQUEST` 失败。

## 示例

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://apis.viggle.ai/v1/scenes/reconstruct \
    -H "Authorization: Bearer $VIGGLE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "sessionId": "living-room-01",
      "referenceBatchIds": [
        "3f0a6c1e-8d2b-4b7a-9e5c-1a2b3c4d5e6f",
        "9b8a7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"
      ]
    }'
  ```

  ```python Python theme={null}
  import os, requests
  response = requests.post(
      "https://apis.viggle.ai/v1/scenes/reconstruct",
      headers={"Authorization": f"Bearer {os.environ['VIGGLE_API_KEY']}"},
      json={
          "sessionId": "living-room-01",
          "referenceBatchIds": [
              "3f0a6c1e-8d2b-4b7a-9e5c-1a2b3c4d5e6f",
              "9b8a7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
          ],
      },
  )
  response.raise_for_status()
  task = response.json()
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://apis.viggle.ai/v1/scenes/reconstruct", {
    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",
        "9b8a7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
      ],
    }),
  });
  const task = await response.json();
  ```
</CodeGroup>

<Card title="快速入门：场景模型" icon="rocket" href="/zh/v1/guides/quickstart-scene">
  在完整的构建、生成和重建流程中查看重建。
</Card>


## OpenAPI

````yaml zh/openapi.yaml POST /v1/scenes/reconstruct
openapi: 3.0.3
info:
  title: Viggle API
  description: 使用 AI 生成角色动画视频。
  version: 2.0.0
  contact:
    name: Viggle Support
    url: https://viggle.ai
servers:
  - url: https://apis.viggle.ai
    description: 生产服务器
security:
  - bearerAuth: []
tags:
  - name: Renders
    description: 准备输入、创建渲染、观察进度并获取结果。
  - name: Credits
    description: 查询当前调用者可用的积分余额。
  - name: Characters
    description: 创建、列出、查询和删除可复用角色。type 决定是否同时提取 3D vsplat，就绪后通过导出接口获取下载链接。
  - name: Motions
    description: 创建、列出、查询和删除可复用动作，也可从官方模板导入。type 决定是否提取或生成 3D 动画，就绪后通过导出接口获取下载链接。
  - name: Videos
    description: 生成 MiniMax H3 视频（vid_）或角色动画视频（anim_），并统一查询调用者的 H3、角色动画及角色动作渲染（render_）结果。
  - name: Images
    description: Viggle Image：用 qwen 模型从文字描述生成 1–6 张 PNG（img_），可选最多 8 张参考图，并按 ID 查询结果。
  - name: Scenes
    description: >-
      场景模型：从文字描述或 360° 全景图构建 3D 高斯泼溅场景（`.spz`），生成新的带位姿视图，并据此重建场景。所有操作都是异步任务（以
      `scn_` 开头），按 ID 查询。从文字描述创建场景每个任务 6 积分，其他场景任务每个 1 积分；任务未以 `ready` 结束时全额退回。
paths:
  /v1/scenes/reconstruct:
    post:
      tags:
        - Scenes
      summary: 重建场景
      description: |
        用 `referenceBatchIds` 中的批次重建会话的 `.spz`。就绪结果包含 `spz`，
        `outputBatch` 为 null。1 积分。
      operationId: reconstructScene
      parameters:
        - $ref: '#/components/parameters/RequestId'
        - $ref: '#/components/parameters/SourceChannel'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SceneReconstructRequest'
      responses:
        '200':
          description: 场景任务已启动。
          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: 可选的调用者自定义关联 ID，最长 128 字符。服务会在响应头返回实际使用的值，便于追踪和支持排查。
      schema:
        type: string
        minLength: 1
        maxLength: 128
    SourceChannel:
      name: X-Viggle-Source
      in: header
      required: false
      description: 可选来源标签，最长 128 字符，用于识别 SDK、集成、产品入口或内部工作流。
      schema:
        type: string
        minLength: 1
        maxLength: 128
  schemas:
    SceneReconstructRequest:
      type: object
      additionalProperties: false
      description: '`POST /v1/scenes/reconstruct` 的请求体。`spzOutputUrl` 与 `outputUris` 不能同时使用。'
      required:
        - sessionId
        - referenceBatchIds
      properties:
        sessionId:
          $ref: '#/components/schemas/SceneSessionId'
        referenceBatchIds:
          $ref: '#/components/schemas/SceneBatchIds'
        spzOutputUrl:
          type: string
          format: uri
          description: 等同于 `outputUris.spz`。
        outputUris:
          $ref: '#/components/schemas/SceneOutputUris'
    SceneTask:
      type: object
      additionalProperties: false
      description: >-
        场景任务（以 `scn_` 开头），所有 `/v1/scenes` 提交接口和 `GET /v1/scenes/{task_id}`
        都返回它。任务以 `queued` 开始（有空闲 GPU 时直接为
        `processing`），`ready`、`failed`、`cancelled` 为终态。只有 `ready` 的任务保留扣费。任务结束后约
        72 小时内可查询。
      required:
        - id
        - sessionId
        - operation
        - status
        - credits
        - createdAt
        - completedAt
        - result
        - error
      properties:
        id:
          type: string
          description: 任务 ID，格式为 `scn_{runId}.{sessionId}`。
        sessionId:
          type: string
        operation:
          type: string
          enum:
            - pano
            - generate
            - reconstruct
          description: custom-pano 任务也返回 `pano`。
        status:
          type: string
          enum:
            - queued
            - processing
            - ready
            - failed
            - cancelled
        queuePosition:
          type: integer
          minimum: 0
          description: 仅在 `queued` 时返回：排在本任务前面的任务数，轮到它时为 0。
        credits:
          type: number
          minimum: 0
          description: 本任务收取的积分：提交时预扣（从文字描述创建场景为 6，其他任务为 1）；未以 `ready` 结束的任务退款后为 0。
        createdAt:
          type: integer
          format: int64
          nullable: true
          description: 开始时间，Unix 毫秒。
        completedAt:
          type: integer
          format: int64
          nullable: true
          description: 结束时间，Unix 毫秒；`queued` 或 `processing` 时为 null。
        result:
          description: 只在 `ready` 时有值。
          nullable: true
          allOf:
            - $ref: '#/components/schemas/SceneResult'
        error:
          description: >-
            只在 `failed` 时有值。`code` 为
            `INVALID_REQUEST`（不可重试，模型拒绝了输入，例如引用了其他会话的批次）或
            `PROCESSING_FAILED`（可重试）。
          nullable: true
          allOf:
            - $ref: '#/components/schemas/ErrorBody'
    SceneSessionId:
      type: string
      minLength: 1
      maxLength: 128
      pattern: ^[A-Za-z0-9_-]+$
      description: >-
        调用方自定的会话 ID，按账户隔离。一个会话对应一个场景及其全部图像批次，同一时间只运行一个任务；已有任务 `processing`
        时再提交会返回 `409`，`error.details.running_task_id` 为正在运行的任务。
      example: living-room-01
    SceneBatchIds:
      type: array
      description: >-
        同一会话内的 1–35 个不重复批次 ID，即 `result.outputBatch.batchId`。格式正确但属于其他会话的 ID
        会让任务以 `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}$
    SceneOutputUris:
      type: object
      additionalProperties: false
      description: >-
        调用方自己的上传地址，Viggle 完成后用 `PUT` 把对应文件上传过去；值为 null 的项会被忽略。上传到这里的 `.spz`
        Viggle 不再保留，结果中的 `spz.url` 即该地址；预览图和全景图上传后 Viggle 仍保留一份，结果中链接指向 Viggle
        的副本。每个地址必须是 `http(s)`、不含账号密码、且主机只解析到公网地址。
      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: SPZ 格式的高斯泼溅场景，`pano` 与 `reconstruct` 产出。
          nullable: true
          allOf:
            - $ref: '#/components/schemas/SceneFile'
        preview:
          description: 预览图，操作产出时才有。
          nullable: true
          allOf:
            - $ref: '#/components/schemas/SceneFile'
        panorama:
          description: 构建场景所用的全景图，`pano` 产出。
          nullable: true
          allOf:
            - $ref: '#/components/schemas/SceneFile'
        outputBatch:
          description: 本任务新增的批次；`reconstruct` 为 null。
          nullable: true
          allOf:
            - $ref: '#/components/schemas/SceneOutputBatch'
        referenceViewCount:
          type: integer
          description: 从 `referenceBatchIds` 读取的视图数。
        newViewCount:
          type: integer
          description: 新产出的视图数。
        seconds:
          type: object
          description: 各阶段耗时（秒），仅供参考，键名随操作而变。
          additionalProperties:
            type: number
    ErrorBody:
      type: object
      additionalProperties: false
      required:
        - code
        - message
        - retryable
        - request_id
        - details
        - remediation
      properties:
        code:
          description: 恢复方法
          allOf:
            - $ref: '#/components/schemas/ErrorCode'
        message:
          type: string
          description: 供人阅读的描述，不要解析其文本做逻辑判断。
        retryable:
          type: boolean
          description: 重试相同请求是否可能成功。
        request_id:
          type: string
          description: 用于关联 Viggle 日志与支持排查。仅当异步工作进程无法恢复原请求 ID 时为 `null`。
        details:
          type: object
          description: 补充结构化信息，可能为空。
          additionalProperties: true
        remediation:
          description: >-
            `{action, retry_after_ms}`，表示下一步操作。除非建议定时重试，否则 `retry_after_ms` 为
            `null`。
          allOf:
            - $ref: '#/components/schemas/ErrorRemediation'
    ErrorResponse:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          description: 草稿流程的顶层错误，包含稳定错误码、说明、重试建议、关联 ID 和错误详情。
          allOf:
            - $ref: '#/components/schemas/ErrorBody'
    SceneFile:
      type: object
      additionalProperties: false
      required:
        - url
      properties:
        url:
          type: string
          format: uri
          description: 下载链接。Viggle 签名链接 3 小时内有效，重新查询任务即可获得新链接；`.spz` 上传到调用方地址时即为该地址。
    SceneOutputBatch:
      type: object
      additionalProperties: false
      required:
        - batchId
        - createdAt
        - manifest
      description: '`pano` 或 `generate` 任务在会话中新增的图像批次。这两个字段上线前完成的任务没有 `kind` 和 `views`。'
      properties:
        batchId:
          type: string
          description: 批次 ID，小写 UUID，可传入 `referenceBatchIds`。
        createdAt:
          type: number
          description: 批次创建时间，Unix 毫秒。
        manifest:
          $ref: '#/components/schemas/SceneFile'
        kind:
          type: string
          enum:
            - initial
            - generated
        views:
          type: array
          items:
            $ref: '#/components/schemas/SceneView'
    ErrorCode:
      description: 草稿渲染流程的错误码集合。资源操作将相应错误映射为 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: 建议的下一步操作，供程序或人工读取，例如稍后重试、重新上传或修正输入。
        retry_after_ms:
          type: integer
          description: 建议重试等待的毫秒数；无需定时重试时为 null。
          nullable: true
          format: int64
          minimum: 0
    SceneView:
      type: object
      additionalProperties: false
      required:
        - index
        - url
        - c2w
        - intrinsic
      properties:
        index:
          type: integer
          minimum: 0
          description: 在批次中的序号，从 0 开始。
        url:
          type: string
          format: uri
          description: 图像的签名下载链接，3 小时内有效。
        c2w:
          $ref: '#/components/schemas/SceneMatrix'
        intrinsic:
          type: array
          description: 相机内参，与批次清单中记录的一致。
          items:
            type: number
    SceneMatrix:
      type: array
      description: >-
        4 × 4 相机到世界（camera-to-world）矩阵，按行写成 4 行、每行 4 个有限数值；最后一行必须为 `[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
  headers:
    RequestId:
      description: 用于支持排查和追踪的稳定请求 ID。
      schema:
        type: string
  responses:
    BadRequest:
      description: 请求失败，详情见错误响应。
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    V1Unauthorized:
      description: 请求失败，详情见错误响应。
      headers:
        WWW-Authenticate:
          schema:
            type: string
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    PaymentRequired:
      description: 请求失败，详情见错误响应。
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    SceneSessionBusy:
      description: >-
        该会话已有任务在排队或运行，`error.details.running_task_id` 为该任务。错误码
        `INVALID_REQUEST`。
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: 请求失败，详情见错误响应。
      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: 请求失败，详情见错误响应。
      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: 服务端 SDK 使用项目 API 密钥，Remote MCP 使用 OAuth 访问令牌。不要在浏览器代码中暴露项目密钥。

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.