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

# Get Grok video task status

> Poll a Grok video task for progress and the final video URL

## Task status

| Status        | Meaning                                        |
| ------------- | ---------------------------------------------- |
| `queued`      | Queued, waiting to be processed                |
| `in_progress` | Generating; `progress` reflects the percentage |
| `completed`   | Done; the video URL is in `metadata.url`       |
| `failed`      | Generation failed; see the `error` field       |

## Polling advice

Grok video tasks usually finish within tens of seconds to a few
minutes, depending on resolution and duration (720p is slower than
480p). Poll every 5–10 seconds and set a reasonable timeout.

## Getting the video

Once complete, there are two ways to retrieve the video:

* Use the link in `metadata.url` directly (it expires — see
  `expires_at` — so download promptly)
* Call `GET /v1/videos/{task_id}/content` to download through the API proxy


## OpenAPI

````yaml /openapi/grok-video.en.yaml get /v1/videos/{task_id}
openapi: 3.1.0
info:
  title: InfinityBlue API — Grok Imagine Video
  version: 1.0.0
  summary: Grok Imagine video generation API (/v1/videos async)
  description: >
    Grok Imagine video generation API, using the `/v1/videos`

    **asynchronous task model**: submit task → poll status → fetch result.


    ## Usage notes


    - **Resolution is selected by the model name**: use a `-480p` / `-720p`
      suffixed model to choose the resolution; **do not pass a `resolution`
      parameter**. For 720p, use `grok-imagine-video-720p`.
    - **`size` only sets the aspect ratio** (e.g. `1280x720` → 16:9); it does
      NOT set the resolution. Do not use `1792x1024` / `1024x1792`.
    - Parameters such as `generate_audio`, `camera_fixed`, and `watermark` are
      not supported. `grok-imagine-video-1.5-preview` is **image-to-video
      only** (an input image is required) and includes synchronized audio.

    ## Typical flow


    1. `POST /v1/videos` — submit a task and receive a task object (with `id`)

    2. `GET /v1/videos/{task_id}` — poll until `status` is `completed` or
    `failed`

    3. Read the video URL from `metadata.url`, or stream the file via
       `GET /v1/videos/{task_id}/content`

    ## Authentication


    Every request must include the API Key in the header:

    ```

    Authorization: Bearer YOUR_API_KEY

    ```
  contact:
    name: InfinityBlue
    url: https://getinfinityblue.com
servers:
  - url: https://api.getinfinityblue.com
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Grok Imagine Video
    description: >
      Grok Imagine video generation API, reusing the `/v1/videos` async task

      model. Resolution is selected by the model-name suffix (`-480p` /
      `-720p`);

      `size` only controls the aspect ratio.
paths:
  /v1/videos/{task_id}:
    get:
      tags:
        - Grok Imagine Video
      summary: Get Grok video task status
      description: |
        Get the status, progress, and result of a Grok video task.
        When the task completes, the video file URL is in `metadata.url`.
      operationId: getGrokVideo
      parameters:
        - name: task_id
          in: path
          description: The video task ID returned by the create endpoint's `id` field.
          required: true
          schema:
            type: string
          example: video_abc123
      responses:
        '200':
          description: Task status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GrokVideoTask'
              examples:
                in_progress:
                  summary: Generating
                  value:
                    id: video_abc123
                    object: video
                    model: grok-imagine-video-720p
                    status: in_progress
                    progress: 40
                    created_at: 1764347090922
                    seconds: '10'
                completed:
                  summary: Completed
                  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: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Invalid or missing API Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Task not found (an unfinished task returns 200 with `in_progress`)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    GrokVideoTask:
      type: object
      description: >-
        Grok video task object, compatible with the OpenAI / Sora video task
        format.
      required:
        - id
        - object
        - model
        - status
        - progress
        - created_at
        - seconds
      properties:
        id:
          type: string
          description: Video task ID.
          examples:
            - video_abc123
        object:
          type: string
          description: Object type, always `video`.
          enum:
            - video
          examples:
            - video
        model:
          type: string
          description: The model used to run the task.
          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: Task status.
          enum:
            - queued
            - in_progress
            - completed
            - failed
          examples:
            - queued
        progress:
          type: integer
          description: Task progress percentage (0–100).
          minimum: 0
          maximum: 100
          examples:
            - 0
        created_at:
          type: integer
          format: int64
          description: Task creation timestamp (milliseconds).
          examples:
            - 1764347090922
        seconds:
          type: string
          description: Video duration in seconds.
          examples:
            - '10'
        completed_at:
          type: integer
          format: int64
          description: Task completion timestamp (milliseconds), filled once complete.
          examples:
            - 1764347170000
        expires_at:
          type: integer
          format: int64
          description: Expiration timestamp (milliseconds) of the task and the video file.
          examples:
            - 1764433570000
        size:
          type: string
          description: >
            Actual output size, e.g. `1280x720`. The actual resolution comes

            from the model-name suffix; the aspect ratio comes from the request
            `size`.
          examples:
            - 1280x720
        error:
          $ref: '#/components/schemas/GrokVideoError'
        metadata:
          type: object
          description: Extra metadata; usually contains a `url` field once complete.
          additionalProperties: true
          properties:
            url:
              type: string
              format: uri
              description: Video file URL.
              examples:
                - https://example.com/generated-video.mp4
    ErrorResponse:
      type: object
      description: Standard error response.
      properties:
        error:
          type: object
          properties:
            message:
              type: string
              description: Error message.
              examples:
                - Invalid duration. The supported range is 1 to 15 seconds.
            type:
              type: string
              description: Error type.
              examples:
                - invalid_request_error
            param:
              type:
                - string
                - 'null'
              description: The related parameter.
              examples:
                - seconds
            code:
              type:
                - string
                - 'null'
              description: Error code.
              examples:
                - invalid_duration
    GrokVideoError:
      type: object
      description: Grok video task error info.
      properties:
        message:
          type: string
          description: Error message.
          examples:
            - generation failed
        code:
          type: string
          description: Error code.
          examples:
            - generation_failed
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >
        Bearer Token authentication, format: `Authorization: Bearer sk-xxxxxx`.

        Get an API Key in the
        [console](https://api.getinfinityblue.com/console).

````