Skip to main content
GET
查询场景任务
GET /v1/scenes/{task_id} 返回由创建场景、从自定义全景图创建场景、生成场景视图或重建场景发起的任务的当前状态,结构与提交时返回的场景任务对象相同。每 5 秒轮询一次,直到 status 为 ready、failed 或 cancelled,然后下载 result 下的文件。 任务归属于你的账号——即你的组织;密钥不属于任何组织时则为你的用户——因此同一账号的任何 API 密钥都能读取。ID 不存在或属于其他账号时返回 404 INVALID_REQUEST。

请求参数

响应参数

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

结果

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

输出批次

批次是一个会话中一组带位姿的图像。它的 batchId 可传入 referenceBatchIds,用于生成更多视图或重建场景。 在引入 kind 和 views 之前就已结束的任务可能缺少这两个字段;manifest 始终存在。

就绪示例

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

失败示例

状态与错误码

任务失败时 error.code 的取值: 本接口的 HTTP 错误: 这些错误与失败任务的 error 使用同样的结构,外面包一层 {"error": {...}}。详见错误与恢复。

数据保留

  • 任务结束后约 72 小时内可以查询;之后本接口返回 404。请下载所需文件,或通过 outputUris 让 Viggle 直接上传到你的存储(见“上传到自己的存储”一节)。
  • 每个签名链接有效期为 3 小时;在任务仍可查询期间,再查询一次即可拿到新链接。

示例

快速入门:场景模型

端到端完成构建场景、生成新视图和重建。

授权

Authorization
string
header
必填

服务端 SDK 使用项目 API 密钥,Remote MCP 使用 OAuth 访问令牌。不要在浏览器代码中暴露项目密钥。

请求头

X-Request-Id
string

可选的调用者自定义关联 ID,最长 128 字符。服务会在响应头返回实际使用的值,便于追踪和支持排查。

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

可选来源标签,最长 128 字符,用于识别 SDK、集成、产品入口或内部工作流。

Required string length: 1 - 128

路径参数

task_id
string
必填

/v1/scenes 提交接口返回的场景任务 ID,以 scn_ 开头(格式 scn_{runId}.{sessionId}),必须属于当前账户。

Minimum string length: 1

响应

请求成功。

场景任务(以 scn_ 开头),所有 /v1/scenes 提交接口和 GET /v1/scenes/{task_id} 都返回它。ready、failed、cancelled 为终态。任务结束后约 72 小时内可查询。

id
string
必填

任务 ID,格式为 scn_{runId}.{sessionId}。

sessionId
string
必填
operation
enum<string>
必填

custom-pano 任务也返回 pano。

可用选项:
pano,
generate,
reconstruct
status
enum<string>
必填
可用选项:
processing,
ready,
failed,
cancelled
createdAt
integer<int64> | null
必填

开始时间,Unix 毫秒。

completedAt
integer<int64> | null
必填

结束时间,Unix 毫秒;processing 时为 null。

result
object | null
必填

只在 ready 时有值。

error
object | null
必填

只在 failed 时有值。code 为 INVALID_REQUEST(不可重试,模型拒绝了输入,例如引用了其他会话的批次)或 PROCESSING_FAILED(可重试)。