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

# 异步任务与结果可用性

> 可靠地轮询或监听 V1 任务，并处理其生命周期。

角色和动作是可复用的异步素材；渲染任务是生成输出文件的异步操作。

## 状态生命周期

```mermaid theme={null}
stateDiagram-v2
  [*] --> queued
  queued --> processing
  processing --> ready
  processing --> failed
  processing --> cancelled
```

`cancelled` 用于渲染状态，客户端无法主动触发，因为没有公开取消操作；任务仍可能自行进入该状态，应视为终态。资源为 `queued` 或 `processing` 时每 3–5 秒轮询，进入 `ready`、`failed` 或 `cancelled` 后停止。

## 轮询示例

```python theme={null}
import time
import requests

def wait_for_resource(url, api_key, interval_seconds=3):
    headers = {"Authorization": f"Bearer {api_key}"}
    while True:
        response = requests.get(url, headers=headers)
        response.raise_for_status()
        resource = response.json()

        if resource["status"] == "ready":
            return resource
        if resource["status"] in {"failed", "cancelled"}:
            error = resource.get("error") or {}
            raise RuntimeError(
                f"{resource['status']}: {error.get('code')} {error.get('message')}"
            )
        time.sleep(interval_seconds)

render = wait_for_resource(
    "https://apis.viggle.ai/v1/videos/render_123abc",
    "YOUR_API_KEY",
)
print(render["video_url"])
```

渲染与角色、动作的轮询模式一致，只需更换资源 URL。`GET /v1/renders/{render_id}` 已停用并返回 `405`，请改用 `GET /v1/videos/{video_id}`，也支持 H3 的 `vid_` ID。见[获取视频](/zh/v1/api-reference/videos/get)与[列出视频](/zh/v1/api-reference/videos/list)。

## 使用监听替代轮询

`GET /v1/renders/{render_id}/events` 通过 SSE 提供同一生命周期：连接时发送快照，状态变化时发送事件，每 10–15 秒发送心跳，进入终态后关闭连接。它可减少轮询延迟与请求量；断开后使用 `Last-Event-ID` 重连。见[监听渲染](/zh/v1/api-reference/renders/events)。角色和动作没有对应事件流，需要轮询。

## 渲染进度

渲染响应可能包含：

* `progress`：可用时为 0–100 的整数。
* `stage`：大致阶段。直接 multipart 流程使用 `analyzing`、`rendering`、`finishing`；草稿流程使用 `queued`、`preparing`、`generating`、`finalizing`。未知值应按“处理中”处理，不要直接报错。通过 `GET /v1/videos/{video_id}` 查询时，仅 Render 来源且 `status=processing` 才有值；H3（`vid_`）始终为 `null`。
* `video_url`：仅渲染就绪后可用。
* `alpha_url`：透明输出时可用。
* `links`：`POST /v1/renders` 响应中的 `{self, events, download}`。旧版迁移代理处理的任务不包含；`GET /v1/videos/{video_id}` 响应也完全不包含。

## 及时下载

`video_url`、`alpha_url`、`vsplat_url`、`thumbnail_url` 和 `glb_url` 都是短期签名链接，每次读取对应接口都会重新签名。后续仍需使用的输出请保存到自己的存储；链接过期时重新请求导出或下载接口，不要长期缓存 URL。

## 安全恢复

* 遇到 `failed`，检查 `error.code`、`error.retryable` 和 `error.remediation`，按照建议恢复，见[错误与恢复](/zh/v1/production/errors)。
* `POST /v1/renders` 的 JSON 草稿模式要求 `Idempotency-Key`，网络超时后可用相同键和请求体安全重试。multipart 渲染及角色、动作创建不使用该请求头。已收到创建响应时应查询资源 ID；未收到时，先根据请求日志和 `X-Request-Id` 确定结果，再决定是否重提。支持 `task_id` 的 3D 创建模式请遵循各自接口的幂等约定。
* 联系支持团队时附上 `X-Request-Id`。