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

# 获取视频

> 通过统一接口获取渲染、H3 视频生成或角色动画生成的完整状态。

`GET /v1/videos/{video_id}` 接受三类 ID，并返回当前持久化状态：角色与动作[渲染任务](/zh/v1/api-reference/renders/create)的 `render_` ID；H3 的 `vid_` ID，来源包括[文本](/zh/v1/api-reference/videos/create-from-text)、[首帧](/zh/v1/api-reference/videos/create-from-first-frame)、[首尾帧](/zh/v1/api-reference/videos/create-from-first-last-frame)或[参考素材](/zh/v1/api-reference/videos/create-from-reference-video)生成；以及[使用 Viggle-Animate](/zh/v1/api-reference/videos/create-from-character-animation)生成的 `anim_` ID。每 3–5 秒轮询一次，直到进入终态。Render 来源的 ID 也支持[监听渲染](/zh/v1/api-reference/renders/events)推送。

本接口替代已停用的 `GET /v1/renders/{render_id}`。

<Note>
  旧接口现返回 `405 Method Not Allowed`，而不是 `404`，因为该路径仍注册有其他方法。只有路径完全没有注册方法时才返回 `404`。如旧集成通过 `404` 判断接口已停用，请同时处理 `405`，或直接迁移到本接口。
</Note>

## 请求参数

| 参数         | 类型     |  必填 | 说明                                                                                   |
| ---------- | ------ | :-: | ------------------------------------------------------------------------------------ |
| `video_id` | string |  是  | 渲染、生成或视频列表接口返回的完整公开 ID：`render_...`、`vid_...` 或 `anim_...`。使用同一 ID 每 3–5 秒轮询，直到进入终态。 |

## 响应参数

返回 `200 OK` 和 Video 对象。

| 字段             | 类型             | 始终返回 | 说明                                                                                    |
| -------------- | -------------- | :--: | ------------------------------------------------------------------------------------- |
| `id`           | string         |   是  | 所请求的视频 ID。                                                                            |
| `status`       | string         |   是  | `queued`、`processing`、`ready`、`failed` 或 `cancelled`。                                 |
| `stage`        | string 或 null  |   是  | 仅 Render 来源且 `status=processing` 时有值，其他情况为 `null`；H3 始终为 `null`。不存在 `stage: "ready"`。 |
| `progress`     | integer 或 null |   是  | 0–100 的进度，或 `null`。                                                                   |
| `video_url`    | string 或 null  |   是  | 就绪后的输出下载地址；此前为 `null`。                                                                |
| `alpha_url`    | string 或 null  |   是  | 仅透明背景（`background_mode=transparent`）的 Render 在就绪后有值。H3 始终为 `null`。                    |
| `created_at`   | string 或 null  |   是  | Render 来源时间戳精确到纳秒；H3 来源精确到秒。                                                          |
| `completed_at` | string 或 null  |   是  | 见下方完成时间说明。                                                                            |
| `error`        | object 或 null  |   是  | `status=failed` 时的结构化错误详情。                                                            |
| `seed`         | integer        | 仅 H3 | 实际使用的随机种子：传入时原样返回，未传入时返回生成的值。仅 `vid_` 视频包含该字段；Render 来源会省略此字段，而非返回 `null`。            |

本响应没有 `links`，因此不包含[创建渲染](/zh/v1/api-reference/renders/create)响应中的 `self`、`events`、`download` 快捷链接。继续查询时使用同一 `video_id`；Render 来源的 ID 还可使用[下载渲染结果](/zh/v1/api-reference/renders/download)。

## 完成时间

Render 来源的视频在 `status` 变为 `ready` 后，`completed_at` 可能延迟约 30 秒回填，并非永久缺失。判断视频是否完成，应检查 `status == "ready"` 或 `video_url` 是否有值，不应依赖 `completed_at` 非空。

### Render 来源示例

```json theme={null}
{
  "id": "render_a1b2c3",
  "status": "ready",
  "stage": null,
  "progress": 100,
  "video_url": "https://assets.viggle.ai/render_a1b2c3.mp4",
  "alpha_url": null,
  "created_at": "2026-08-25T09:12:03.123456789Z",
  "completed_at": "2026-08-25T09:13:47Z",
  "error": null
}
```

### H3 来源示例

```json theme={null}
{
  "id": "vid_3f2a9c",
  "status": "ready",
  "stage": null,
  "progress": 100,
  "video_url": "https://storage.googleapis.com/...signed...",
  "alpha_url": null,
  "created_at": "2026-08-24T09:12:03Z",
  "completed_at": "2026-08-24T09:13:47Z",
  "error": null,
  "seed": 4271960385017522688
}
```

### 角色动画来源示例

```json theme={null}
{
  "id": "anim_7c1e4b",
  "status": "ready",
  "stage": null,
  "progress": 100,
  "video_url": "https://storage.googleapis.com/...signed...",
  "alpha_url": null,
  "created_at": "2026-09-09T09:12:03Z",
  "completed_at": "2026-09-09T09:13:47Z",
  "error": null
}
```

没有 `seed` 字段；该字段仅适用于 H3。

### 失败示例

```json theme={null}
{
  "id": "render_a1b2c3",
  "status": "failed",
  "stage": null,
  "progress": null,
  "video_url": null,
  "alpha_url": null,
  "created_at": "2026-08-25T09:12:03.123456789Z",
  "completed_at": "2026-08-25T09:13:50Z",
  "error": {
    "code": "TASK_FAILED",
    "message": "The render could not be completed.",
    "retryable": false,
    "request_id": "req_123abc",
    "details": {},
    "remediation": { "action": "contact_support", "retry_after_ms": null }
  }
}
```

## 示例

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://apis.viggle.ai/v1/videos/render_a1b2c3" -H "Authorization: Bearer $VIGGLE_API_KEY"
  ```

  ```python Python theme={null}
  import os, requests
  response = requests.get("https://apis.viggle.ai/v1/videos/render_a1b2c3", headers={"Authorization": f"Bearer {os.environ['VIGGLE_API_KEY']}"})
  response.raise_for_status()
  video = response.json()
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://apis.viggle.ai/v1/videos/render_a1b2c3", { headers: { Authorization: `Bearer ${process.env.VIGGLE_API_KEY}` } });
  const video = await response.json();
  ```

  ```go Go theme={null}
  req, _ := http.NewRequest("GET", "https://apis.viggle.ai/v1/videos/render_a1b2c3", nil)
  req.Header.Set("Authorization", "Bearer "+os.Getenv("VIGGLE_API_KEY"))
  resp, err := http.DefaultClient.Do(req)
  if err != nil { panic(err) }
  defer resp.Body.Close()
  ```
</CodeGroup>


## OpenAPI

````yaml zh/openapi.yaml GET /v1/videos/{video_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_）结果。
paths:
  /v1/videos/{video_id}:
    parameters:
      - $ref: '#/components/parameters/VideoId'
      - $ref: '#/components/parameters/RequestId'
      - $ref: '#/components/parameters/SourceChannel'
    get:
      tags:
        - Videos
      summary: 获取视频
      description: 通过统一接口获取渲染、H3 视频生成或角色动画生成的完整状态。
      operationId: getVideo
      responses:
        '200':
          description: 请求成功。
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Video'
        '401':
          $ref: '#/components/responses/V1Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  parameters:
    VideoId:
      name: video_id
      in: path
      required: true
      description: 当前调用者拥有的视频公开 ID：渲染为 render_，H3 为 vid_，角色动画为 anim_。
      schema:
        type: string
        minLength: 1
      example: render_123
    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:
    Video:
      description: >-
        统一、只读的视频完整状态，支持 render_、vid_ 和 anim_。不包含 links 或 self/events/download
        快捷链接。stage 仅 Render 来源且 processing 时有值，其余为 null。alpha_url 仅透明背景 Render
        就绪时有值。seed 仅 H3 包含，Render 和角色动画完全省略该字段，而不是返回 null。
      type: object
      additionalProperties: false
      required:
        - id
        - status
        - stage
        - progress
        - video_url
        - alpha_url
        - created_at
        - completed_at
        - error
      properties:
        id:
          type: string
          description: 所请求的视频 ID。
          minLength: 1
        status:
          description: '`queued`、`processing`、`ready`、`failed` 或 `cancelled`。'
          allOf:
            - $ref: '#/components/schemas/ResourceStatus'
        stage:
          type: string
          description: >-
            仅 Render 来源且 `status=processing` 时有值，其他情况为 `null`；H3 始终为 `null`。不存在
            `stage: "ready"`。
          nullable: true
          allOf:
            - $ref: '#/components/schemas/RenderStage'
        progress:
          type: integer
          description: 0–100 的进度，或 `null`。
          nullable: true
          minimum: 0
          maximum: 100
        video_url:
          type: string
          description: 就绪后的输出下载地址；此前为 `null`。
          nullable: true
          format: uri
        alpha_url:
          type: string
          description: 仅透明背景（`background_mode=transparent`）的 Render 在就绪后有值。H3 始终为 `null`。
          nullable: true
          format: uri
        created_at:
          type: string
          description: Render 来源时间戳精确到纳秒；H3 来源精确到秒。
          nullable: true
          format: date-time
        completed_at:
          type: string
          description: 见下方完成时间说明。
          nullable: true
          format: date-time
        error:
          type: object
          description: '`status=failed` 时的结构化错误详情。'
          nullable: true
          allOf:
            - $ref: '#/components/schemas/ErrorBody'
        seed:
          type: integer
          format: int64
          description: >-
            实际使用的随机种子：传入时原样返回，未传入时返回生成的值。仅 `vid_` 视频包含该字段；Render 来源会省略此字段，而非返回
            `null`。
    ResourceStatus:
      description: 异步资源共用的公开生命周期，枚举值与 RenderStatus 相同。
      type: string
      enum:
        - queued
        - processing
        - ready
        - failed
        - cancelled
    RenderStage:
      description: >-
        大致处理阶段。multipart 渲染使用
        analyzing、rendering、finishing，其他值来自草稿流程。未知值应按处理中处理，不要直接失败。
      type: string
      enum:
        - queued
        - preparing
        - generating
        - finalizing
        - ready
        - failed
        - cancelled
        - analyzing
        - rendering
        - finishing
    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'
    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
    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
  responses:
    V1Unauthorized:
      description: 请求失败，详情见错误响应。
      headers:
        WWW-Authenticate:
          schema:
            type: string
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: 请求失败，详情见错误响应。
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: 请求失败，详情见错误响应。
      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'
    InternalServerError:
      description: 请求失败，详情见错误响应。
      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 访问令牌。不要在浏览器代码中暴露项目密钥。

````