> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inb.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# 获取 Grok 视频任务状态

> 轮询 Grok 视频任务，获取进度和最终视频 URL

## 任务状态说明

| 状态            | 含义                           |
| ------------- | ---------------------------- |
| `queued`      | 排队等待处理                       |
| `in_progress` | 生成中，`progress` 字段反映百分比进度     |
| `completed`   | 已完成，视频 URL 位于 `metadata.url` |
| `failed`      | 生成失败，查看 `error` 字段了解原因       |

## 轮询建议

Grok 视频任务通常在数十秒到数分钟内完成，具体取决于分辨率与时长
（720p 比 480p 更慢）。建议每 5–10 秒轮询一次，并设置合理超时时间。

## 获取视频

完成后有两种方式获取视频：

* 直接使用 `metadata.url` 中的链接（有效期见 `expires_at`，请尽快下载）
* 调用 `GET /v1/videos/{task_id}/content` 通过接口代理下载


## OpenAPI

````yaml /openapi/grok-video.zh.yaml get /v1/videos/{task_id}
openapi: 3.1.0
info:
  title: InfinityBlue API — Grok Imagine 视频
  version: 1.0.0
  summary: Grok Imagine 视频生成接口（/v1/videos 异步）
  description: |
    Grok Imagine 系列视频生成接口，采用 `/v1/videos` **异步任务模型**：
    提交任务 → 轮询状态 → 获取结果。

    ## 使用要点

    - **分辨率由模型名决定**：用 `-480p` / `-720p` 后缀的模型来选择分辨率，
      **不要传入 `resolution` 参数**。例如 720p 用 `grok-imagine-video-720p`。
    - **`size` 仅决定画幅比例**（如 `1280x720` → 16:9），不决定分辨率；
      请勿使用 `1792x1024` / `1024x1792`。
    - 不支持 `generate_audio`、`camera_fixed`、`watermark` 等参数；
      `grok-imagine-video-1.5-preview` **仅支持图生视频**（必须带输入图），且自带同步音频。

    ## 典型调用流程

    1. `POST /v1/videos` — 提交任务，获取任务对象（含 `id`）
    2. `GET /v1/videos/{task_id}` — 轮询状态，直到 `status` 为 `completed` 或 `failed`
    3. 从 `metadata.url` 读取视频 URL，或 `GET /v1/videos/{task_id}/content` 直接下载视频流

    ## 认证

    所有请求需在请求头中携带 API Key：
    ```
    Authorization: Bearer YOUR_API_KEY
    ```
  contact:
    name: InfinityBlue
    url: https://getinfinityblue.com
servers:
  - url: https://api.getinfinityblue.com
    description: 生产环境
security:
  - bearerAuth: []
tags:
  - name: Grok Imagine 视频
    description: |
      Grok Imagine 系列视频生成接口，复用 `/v1/videos` 异步任务模型。
      分辨率由模型名后缀（`-480p` / `-720p`）决定，`size` 仅控制画幅比例。
paths:
  /v1/videos/{task_id}:
    get:
      tags:
        - Grok Imagine 视频
      summary: 获取 Grok 视频任务状态
      description: |
        获取 Grok 视频任务的状态、进度和结果。
        任务完成后，视频文件 URL 位于 `metadata.url` 字段。
      operationId: getGrokVideo
      parameters:
        - name: task_id
          in: path
          description: 视频任务 ID，由创建接口返回的 `id` 字段。
          required: true
          schema:
            type: string
          example: video_abc123
      responses:
        '200':
          description: 成功获取视频任务状态
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GrokVideoTask'
              examples:
                in_progress:
                  summary: 生成中
                  value:
                    id: video_abc123
                    object: video
                    model: grok-imagine-video-720p
                    status: in_progress
                    progress: 40
                    created_at: 1764347090922
                    seconds: '10'
                completed:
                  summary: 已完成
                  value:
                    id: video_abc123
                    object: video
                    model: grok-imagine-video-720p
                    status: completed
                    progress: 100
                    created_at: 1764347090922
                    completed_at: 1764347170000
                    seconds: '10'
                    size: 1280x720
                    metadata:
                      url: https://example.com/generated-video.mp4
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: API Key 无效或缺失
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 任务不存在（未完成的任务返回 200 + `in_progress`）
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: 请求频率超限
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    GrokVideoTask:
      type: object
      description: Grok 视频任务对象，兼容 OpenAI / Sora 视频任务格式。
      required:
        - id
        - object
        - model
        - status
        - progress
        - created_at
        - seconds
      properties:
        id:
          type: string
          description: 视频任务 ID。
          examples:
            - video_abc123
        object:
          type: string
          description: 对象类型，固定为 `video`。
          enum:
            - video
          examples:
            - video
        model:
          type: string
          description: 执行任务所用的模型。
          enum:
            - grok-imagine-video-480p
            - grok-imagine-video-720p
            - grok-imagine-video-1.5-preview-480p
            - grok-imagine-video-1.5-preview-720p
          examples:
            - grok-imagine-video-720p
        status:
          type: string
          description: 任务状态。
          enum:
            - queued
            - in_progress
            - completed
            - failed
          examples:
            - queued
        progress:
          type: integer
          description: 任务进度百分比（0–100）。
          minimum: 0
          maximum: 100
          examples:
            - 0
        created_at:
          type: integer
          format: int64
          description: 任务创建时间戳（毫秒）。
          examples:
            - 1764347090922
        seconds:
          type: string
          description: 视频时长，单位秒。
          examples:
            - '10'
        completed_at:
          type: integer
          format: int64
          description: 任务完成时间戳（毫秒），完成后填充。
          examples:
            - 1764347170000
        expires_at:
          type: integer
          format: int64
          description: 任务及视频文件的过期时间戳（毫秒）。
          examples:
            - 1764433570000
        size:
          type: string
          description: |
            实际输出尺寸，格式如 `1280x720`。
            实际分辨率由模型名后缀决定，画幅比例由请求的 `size` 决定。
          examples:
            - 1280x720
        error:
          $ref: '#/components/schemas/GrokVideoError'
        metadata:
          type: object
          description: 额外元数据，任务完成后通常包含 `url` 字段。
          additionalProperties: true
          properties:
            url:
              type: string
              format: uri
              description: 视频文件 URL。
              examples:
                - https://example.com/generated-video.mp4
    ErrorResponse:
      type: object
      description: 标准错误响应。
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: 错误信息。
              examples:
                - 无效的时长。支持的范围为 1 到 15 秒。
            type:
              type: string
              description: 错误类型。
              examples:
                - invalid_request_error
            param:
              type:
                - string
                - 'null'
              description: 相关参数。
              examples:
                - seconds
            code:
              type:
                - string
                - 'null'
              description: 错误代码。
              examples:
                - invalid_duration
    GrokVideoError:
      type: object
      description: Grok 视频任务错误信息。
      properties:
        message:
          type: string
          description: 错误信息。
          examples:
            - generation failed
        code:
          type: string
          description: 错误码。
          examples:
            - generation_failed
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: |
        使用 Bearer Token 认证，格式：`Authorization: Bearer sk-xxxxxx`。
        在 [控制台](https://api.getinfinityblue.com/console) 获取 API Key。

````