> ## 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. # 生成场景视图 > 从你选定的相机位姿生成场景的新图像，作为新的图像批次。 从你放置的相机生成会话场景的新视图。模型读取 `referenceBatchIds` 中列出的图像批次，渲染出从你给定的相机——`targetC2w` 矩阵，或带偏航角和俯仰角的 `targetPosition`——看到的新图像，这些图像成为会话中一个新的 `generated` 批次。可以用它们补全现有视图没有覆盖到的场景部分，再把新的 `batchId` 连同之前的批次一起传给[重建场景](/zh/v1/api-reference/scenes/reconstruct)，得到更新后的 `.spz`。 接口是异步的：返回 `queued` 状态的[场景任务](/zh/v1/api-reference/scenes/get)，轮询直到任务结束。 **计费**（1 积分 = \$0.01）：每个任务 **1 积分（\$0.01）**，提交时预扣，任务未以 `ready` 结束则全额退回。见[计费](/zh/v1/pricing#scene-model)。 ## 请求参数 使用 `application/json`，最大 1 MiB。不接受未知字段。 | 参数 | 类型 | 必填 | 默认值 | 说明 | | - | - | :-: | - | - | | `sessionId` | string | 是 | — | 要扩展其场景的会话，见[创建场景](/zh/v1/api-reference/scenes/pano)中的“会话”一节。 | | `referenceBatchIds` | string\[] | 是 | — | 1–35 个本会话的批次 ID，即 `result.outputBatch.batchId` 中返回的值。小写 UUID，不能重复。 | | `targetC2w` | number\[4]\[4] | `targetC2w` / `targetPosition` 二选一 | — | 渲染所用的相机到世界矩阵（c2w），与视图的 `c2w` 处于同一坐标系。最后一行必须为 `[0, 0, 0, 1]`。 | | `targetPosition` | object | `targetC2w` / `targetPosition` 二选一 | — | 用位置和两个角度代替矩阵描述相机：`{"position": [x, y, z], "yaw": 度, "pitch": 度}`，见下方“目标位置”一节。 | | `projection` | string | 否 | `perspective` | `perspective` 生成普通相机图像，`pano` 生成位于目标相机处的 360° 全景图。 | | `fov` | number | 否 | 模型默认值 | 视场角，单位为度，20–140。 | | `seed` | integer | 否 | `1` | 0–4294967295。相同输入和 seed 会得到相同图像。 | | `spzOutputUrl` | string | 否 | — | 与所有场景操作一样接受此字段，见[创建场景](/zh/v1/api-reference/scenes/pano)中的“上传到自己的存储”一节。 | | `outputUris` | object | 否 | — | 按文件指定你自己的上传地址：`spz`、`preview`、`panorama`。不能与 `spzOutputUrl` 同时使用。 | 获得有效 `targetC2w` 最简单的方法，是从已有批次中某个视图的 `c2w` 出发，对其平移或旋转。相机离现有视图越近，生成的图像越一致。 ## 目标位置 `targetPosition` 无需写矩阵即可放置相机。`targetC2w` 和 `targetPosition` 必须且只能发送其中一个；两者都发送或都不发送都会被拒绝。 | 字段 | 类型 | 必填 | 默认值 | 说明 | | - | - | :-: | - | - | | `position` | number\[3] | 是 | — | 相机位置 `[x, y, z]`，与视图的 `c2w` 处于同一坐标系。 | | `yaw` | number | 否 | `0` | 绕世界 +Y 轴的偏航角，单位为度。正值向左转。 | | `pitch` | number | 否 | `0` | 俯仰角，单位为度，范围 `-90` 到 `90`。正值向上看。 | 不接受其他字段，值为 `null` 的角度按 `0` 处理。角度采用与 `c2w` 相同的 OpenGL 约定：世界 +Y 轴朝上，相机沿自身 −Z 轴方向看，+X 轴指向右侧。`yaw` 和 `pitch` 都为 `0` 时相机朝世界 −Z 方向看；`yaw: 90` 朝 −X 方向看，`pitch: 90` 垂直向上看。 请求会被转换为对应的 `targetC2w`：旋转为 `R = Ry(yaw) · Rx(pitch)`，平移为 `position`： ```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 | ``` 无法表示横滚：相机的地平线始终保持水平。需要横滚的相机请使用 `targetC2w`。 ## 响应参数 返回 `200 OK` 和 `queued`（或已经是 `processing`）状态的场景任务： ```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 } ``` 任务 `ready` 后，`result.outputBatch` 即新的 `generated` 批次，`views` 中包含每张新图像及其相机，`result.newViewCount` 为新图像数量。`result.spz` 为 `null`——请运行[重建场景](/zh/v1/api-reference/scenes/reconstruct)把新视图并入场景。 ## 常见错误 | 错误 | 原因 | | - | - | | `400 INVALID_REQUEST` | 字段缺失、不合法或未知，例如 `referenceBatchIds` 为空、超过 35 个 ID 或有重复，`targetC2w` 不是最后一行为 `[0, 0, 0, 1]` 的 4 × 4 矩阵，`targetC2w` 和 `targetPosition` 都发送或都未发送，或 `targetPosition` 缺少 `position`、包含未知字段或 `pitch` 超出 `-90`–`90`。 | | `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` 失败。 ## 示例 ```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(); ``` ### 使用位置和角度 同一会话中，相机位于 `[0.5, 1.2, 0]`，向左转 30°、向下倾斜 10°： ```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 } }' ``` 在完整的构建、生成和重建流程中查看生成视图。 ## OpenAPI ````yaml zh/openapi.yaml POST /v1/scenes/generate 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/generate: post: tags: - Scenes summary: 生成场景视图 description: > 基于 `referenceBatchIds` 中的批次，从 `targetC2w` 或 `targetPosition` 生成场景的新视图。就绪结果的 `outputBatch` 为新的 `generated` 批次，`spz` 为 null。1 积分。 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: 场景任务已启动。 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: SceneGenerateRequest: type: object additionalProperties: false description: >- `POST /v1/scenes/generate` 的请求体。`targetC2w` 与 `targetPosition` 必须且只能发送其一；`spzOutputUrl` 与 `outputUris` 不能同时使用。 required: - sessionId - referenceBatchIds properties: sessionId: $ref: '#/components/schemas/SceneSessionId' referenceBatchIds: $ref: '#/components/schemas/SceneBatchIds' targetC2w: allOf: - $ref: '#/components/schemas/SceneMatrix' description: 渲染所用的相机，与视图的 `c2w` 处于同一坐标系。与 `targetPosition` 必须且只能发送其一。 targetPosition: allOf: - $ref: '#/components/schemas/SceneTargetPosition' description: 用位置、偏航角和俯仰角表示的相机。与 `targetC2w` 必须且只能发送其一。 projection: type: string enum: - perspective - pano default: perspective description: '`perspective` 生成普通相机视角图像，`pano` 在目标相机处生成 360° 全景图。' fov: type: number nullable: true minimum: 20 maximum: 140 description: 视场角（度）。不传或为 null 时使用模型默认值。 seed: type: integer format: int64 minimum: 0 maximum: 4294967295 default: 1 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}$ 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 SceneTargetPosition: type: object additionalProperties: false description: >- `generate` 的相机，用位置和两个角度代替 `targetC2w`，坐标系和 OpenGL 约定与之相同：世界 +Y 轴朝上，相机沿自身 −Z 轴方向看，+X 轴指向右侧。旋转为 `R = Ry(yaw) · Rx(pitch)`：偏航角为正时绕世界 +Y 轴向左转，俯仰角为正时向上看，两者都为 `0` 时朝 −Z 方向看。 required: - position properties: position: type: array minItems: 3 maxItems: 3 items: type: number description: 相机位置 `[x, y, z]`。 yaw: type: number nullable: true default: 0 description: 绕世界 +Y 轴的角度（度），正值向左转。null 按 `0` 处理。 pitch: type: number nullable: true minimum: -90 maximum: 90 default: 0 description: 俯仰角（度），`-90` 到 `90`，正值向上看。null 按 `0` 处理。 example: position: - 0.5 - 1.2 - 0 yaw: 30 pitch: -10 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 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.