> ## 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 /v1/scenes/{task_id}` 返回由[创建场景](/zh/v1/api-reference/scenes/pano)、[从自定义全景图创建场景](/zh/v1/api-reference/scenes/custom-pano)、[生成场景视图](/zh/v1/api-reference/scenes/generate)或[重建场景](/zh/v1/api-reference/scenes/reconstruct)发起的任务的当前状态，结构与提交时返回的场景任务对象相同。`status` 为 `queued` 或 `processing` 时每 5 秒轮询一次，直到变为 `ready`、`failed` 或 `cancelled`，然后下载 `result` 下的文件。

任务归属于你的账号——即你的组织；密钥不属于任何组织时则为你的用户——因此同一账号的任何 API 密钥都能读取。ID 不存在或属于其他账号时返回 `404 INVALID_REQUEST`。

## 请求参数

| 参数 | 类型 | 必填 | 说明 |
| - | - | :-: | - |
| `task_id` | string | 是 | 提交接口返回的完整任务 ID，以 `scn_` 开头。格式为 `scn_{runId}.{sessionId}`，请原样使用。 |

## 响应参数

返回 `200 OK` 和场景任务对象。字段名使用 camelCase。

| 字段 | 类型 | 说明 |
| - | - | - |
| `id` | string | 任务 ID，以 `scn_` 开头。 |
| `sessionId` | string | 提交任务时使用的 `sessionId`。 |
| `operation` | string | `pano`、`generate` 或 `reconstruct`。[custom-pano](/zh/v1/api-reference/scenes/custom-pano) 任务返回 `pano`。 |
| `status` | string | `queued`、`processing`、`ready`、`failed` 或 `cancelled`，见下方“状态与错误码”一节。 |
| `queuePosition` | integer | 仅在 `queued` 时返回：排在本任务前面的任务数，轮到它时为 `0`。 |
| `credits` | number | 本任务收取的积分，见[计费](/zh/v1/pricing#scene-model)。提交时预扣；任务未以 `ready` 结束并退款后为 `0`。 |
| `createdAt` | integer | 提交时间，Unix 毫秒。 |
| `completedAt` | integer 或 null | 结束时间，Unix 毫秒；`queued` 或 `processing` 时为 `null`。 |
| `result` | object 或 null | 只在 `status` 为 `ready` 时有值，见下方“结果”一节。 |
| `error` | object 或 null | 只在 `status` 为 `failed` 时有值。 |

### 结果

| 字段 | 类型 | 说明 |
| - | - | - |
| `operation` | string | 与任务的 `operation` 相同。 |
| `sessionId` | string | 与任务的 `sessionId` 相同。 |
| `spz` | object 或 null | 3D 高斯泼溅场景，形如 `{ "url": ... }`，[SPZ](https://github.com/nianticlabs/spz) 格式。由 `pano` 和 `reconstruct` 产生。如果传了 `spzOutputUrl`（或 `outputUris.spz`），文件只上传到你的地址，`url` 即该地址。 |
| `preview` | object 或 null | 预览图，形如 `{ "url": ... }`，仅在操作产生预览图时有值。 |
| `panorama` | object 或 null | 构建场景所用的 360° 全景图，形如 `{ "url": ... }`——根据描述文字生成的，或你提供的。由 `pano` 产生。 |
| `outputBatch` | object 或 null | 本任务向会话添加的图像批次，见下方“输出批次”一节。由 `pano`（初始视图）和 `generate`（新视图）产生；`reconstruct` 时为 `null`。 |
| `referenceViewCount` | integer | 任务从 `referenceBatchIds` 读取的参考视图数量。`pano` 为 `0`。 |
| `newViewCount` | integer | 任务产生的新视图数量。`reconstruct` 为 `0`。 |
| `seconds` | object | 各阶段处理耗时，单位为秒，例如 `{"model": 4.2}`。键因操作而异，仅供参考。 |

Viggle 签发的每个 `url` 有效期为 **3 小时**。再查询一次任务即可拿到新链接。

### 输出批次

批次是一个会话中一组带位姿的图像。它的 `batchId` 可传入 `referenceBatchIds`，用于[生成](/zh/v1/api-reference/scenes/generate)更多视图或[重建](/zh/v1/api-reference/scenes/reconstruct)场景。

| 字段 | 类型 | 说明 |
| - | - | - |
| `batchId` | string | 批次 ID，小写 UUID。 |
| `createdAt` | number | 批次创建时间，Unix 毫秒。 |
| `manifest` | object | 批次的 `batch.json` 清单，形如 `{ "url": ... }`。 |
| `kind` | string | `pano` 生成的批次为 `initial`，`generate` 生成的批次为 `generated`。 |
| `views` | array | 批次中的所有图像，按顺序排列。 |
| `views[].index` | integer | 在批次中的位置，从 0 开始。 |
| `views[].url` | string | 图像的签名下载链接。 |
| `views[].c2w` | number\[4]\[4] | 视图的相机到世界矩阵（c2w）。custom-pano 场景中它位于你自己的世界坐标系，见[从自定义全景图创建场景](/zh/v1/api-reference/scenes/custom-pano)中的“坐标系”一节。 |
| `views[].intrinsic` | number\[] | 视图的相机内参，与批次清单中的记录一致。 |

在引入 `kind` 和 `views` 之前就已结束的任务可能缺少这两个字段；`manifest` 始终存在。

### 就绪示例

一个 `pano` 任务。签名查询参数已缩写：

```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
}
```

### 失败示例

```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` | 含义 |
| - | - |
| `queued` | 已接收，等待 GPU 空位；`queuePosition` 表示前面还有几个任务。在它结束前，该会话不接受其他任务。 |
| `processing` | 运行中。在它结束前，该会话不接受其他任务。 |
| `ready` | 已完成，`result` 已填充。 |
| `failed` | 失败，原因见 `error`。 |
| `cancelled` | 在完成前被 Viggle 终止。请重新提交任务。 |

只有 `ready` 的任务保留扣费。`failed` 或 `cancelled` 的任务（包括一直没离开 `queued` 的）会全额退回，退款完成后 `credits` 为 `0`。重试即提交新任务，会重新预扣积分。

任务失败时 `error.code` 的取值：

| `code` | `retryable` | 什么时候出现 | 建议 |
| - | :-: | - | - |
| `INVALID_REQUEST` | `false` | 场景模型拒绝了输入，例如 `referenceBatchIds` 中有不属于本会话的批次。`message` 说明原因。 | 修正输入后重新提交。 |
| `PROCESSING_FAILED` | `true` | 其他任何失败：模型、存储或超时。 | 重新提交同样的请求。反复出现请带上任务 `id` 联系我们。 |

本接口的 HTTP 错误：

| HTTP | `code` | 含义 |
| - | - | - |
| `401` | `UNAUTHENTICATED` | 缺少或无效的 API 密钥。 |
| `404` | `INVALID_REQUEST` | 你的账号中没有该任务，或已超过下方“数据保留”一节所述的保留期限。 |
| `503` | `SERVICE_BUSY` | 场景模型暂时不可用，可重试。 |

这些错误与失败任务的 `error` 使用同样的结构，外面包一层 `{"error": {...}}`。详见[错误与恢复](/zh/v1/production/errors)。

## 数据保留

* 任务结束后约 **72 小时**内可以查询；之后本接口返回 `404`。请下载所需文件，或通过 [`outputUris`](/zh/v1/api-reference/scenes/pano) 让 Viggle 直接上传到你的存储（见“上传到自己的存储”一节）。
* 每个签名链接有效期为 **3 小时**；在任务仍可查询期间，再查询一次即可拿到新链接。

## 示例

<CodeGroup>
  ```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();
  ```
</CodeGroup>

<Card title="快速入门：场景模型" icon="rocket" href="/zh/v1/guides/quickstart-scene">
  端到端完成构建场景、生成新视图和重建。
</Card>


## OpenAPI

````yaml zh/openapi.yaml GET /v1/scenes/{task_id}
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/{task_id}:
    parameters:
      - $ref: '#/components/parameters/SceneTaskId'
      - $ref: '#/components/parameters/RequestId'
      - $ref: '#/components/parameters/SourceChannel'
    get:
      tags:
        - Scenes
      summary: 查询场景任务
      description: |
        返回当前账户的场景任务。`result` 中的签名链接 3 小时内有效，每次查询都会重新签名。
        任务结束后约 72 小时内可查询，之后返回 `404`。
      operationId: getSceneTask
      responses:
        '200':
          description: 请求成功。
          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: >-
        /v1/scenes 提交接口返回的场景任务 ID，以 scn_ 开头（格式
        scn_{runId}.{sessionId}），必须属于当前账户。
      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: 可选的调用者自定义关联 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
  headers:
    RequestId:
      description: 用于支持排查和追踪的稳定请求 ID。
      schema:
        type: string
  schemas:
    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'
    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
  responses:
    V1Unauthorized:
      description: 请求失败，详情见错误响应。
      headers:
        WWW-Authenticate:
          schema:
            type: string
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    SceneTaskNotFound:
      description: 当前账户下没有该场景任务，或已超过保留期。错误码 `INVALID_REQUEST`。
      headers:
        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.