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

# Video Task Status API

> Monitor asynchronous t2v/i2v generation tasks and download the produced video assets.

## Overview

All text-to-video or image-to-video submissions return a `task_id`. Use the video task status endpoint to poll the job until it finishes. The payload mirrors the async submission response and includes downloadable asset URLs when the task succeeds.

<Tip>
  Poll every 3–5 seconds to balance freshness with API usage efficiency.
</Tip>

## Endpoint

* `GET https://api.siray.ai/v1/video/generations/{task_id}`

**Headers**

* `Authorization: Bearer <SIRAY_API_TOKEN>`

**Path parameters**

| Name      | Description                                  |
| --------- | -------------------------------------------- |
| `task_id` | ID returned when the video task was created. |

## Response structure

```json theme={null}
{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "video_69196fafcc9c8190acccf32e9b560c3f0da8a6d1948cfaa5",
    "status": "SUCCESS",
    "progress": "100%",
    "outputs": [
      "https://api.siray.ai/redirect/example-output"
    ],
    "start_time": 1763274702,
    "finish_time": 1763274838,
    "submit_time": 1763274672,
    "fail_reason": ""
  }
}
```

### Fields

* `code` / `message`: Service-level indicators for the polling request.
* `data.task_id`: Echo of the video task identifier.
* `data.status`: Lifecycle state — values listed below.
* `data.progress`: Human-readable progress string.
* `data.outputs`: URLs pointing to the generated video assets (present when `status` is `SUCCESS`).
* `data.fail_reason`: Explains why processing stopped when `status` is `FAILURE`.
* `data.submit_time`, `data.start_time`, `data.finish_time`: Unix timestamps that help track total latency.

### Status values

| Status        | Meaning                                                           |
| ------------- | ----------------------------------------------------------------- |
| `NOT_START`   | Task accepted but preprocessing has not started yet.              |
| `SUBMITTED`   | Request stored and waiting to enter the queue.                    |
| `QUEUED`      | Task is scheduled and waiting for compute resources.              |
| `IN_PROGRESS` | Generation is currently running.                                  |
| `SUCCESS`     | Outputs are ready; download the video via the provided URLs.      |
| `FAILURE`     | Irrecoverable error; inspect `fail_reason` for remediation steps. |

## Usage example

```bash theme={null}
curl -X GET "https://api.siray.ai/v1/video/generations/${TASK_ID}" \
  -H "Authorization: Bearer ${SIRAY_API_TOKEN}"
```

> When `status` reaches `SUCCESS`, stream or download the video from the URLs in `outputs`. If the task fails, retry after resolving the underlying issue noted in `fail_reason`.


## OpenAPI

````yaml openapi-spec/task-status.json GET /v1/video/generations/{task_id}
openapi: 3.1.0
info:
  title: Task Status API
  summary: Track asynchronous Siray generation jobs
  description: >-
    Provides endpoints to poll the lifecycle of asynchronous image, video, or 3D
    model generation tasks created through Siray APIs.
  version: 1.0.0
servers:
  - url: https://api.siray.ai
    description: Siray API Server
security: []
tags:
  - name: Task Status
    description: >-
      Endpoints for polling Siray asynchronous image, video, and 3D model
      generation tasks.
paths:
  /v1/video/generations/{task_id}:
    get:
      tags:
        - Task Status
      summary: Query video generation task
      description: >-
        Retrieve the status and outputs of an asynchronous video generation
        task. The task ID is returned from the async POST request.
      operationId: get_video_task_status
      parameters:
        - name: task_id
          in: path
          description: Identifier returned from the video generation task submission
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Task status and (if available) generated outputs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaskStatusResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    TaskStatusResponse:
      type: object
      required:
        - code
        - message
        - data
      properties:
        code:
          type: string
          description: Status code returned by the service
          example: success
        message:
          type: string
          description: Additional information about the request result
          example: ''
        data:
          $ref: '#/components/schemas/TaskStatusData'
      description: Async task status query response
      example:
        code: success
        message: ''
        data:
          task_id: video_69196fafcc9c8190acccf32e9b560c3f0da8a6d1948cfaa5
          status: SUCCESS
          progress: 100%
          outputs:
            - https://api.siray.ai/redirect/example-output
          start_time: 1763274702
          finish_time: 1763274838
          submit_time: 1763274672
          fail_reason: ''
    TaskStatusData:
      type: object
      required:
        - task_id
        - status
      properties:
        task_id:
          type: string
          description: Identifier of the task
        status:
          type: string
          description: Current lifecycle status of the task
          enum:
            - NOT_START
            - SUBMITTED
            - QUEUED
            - IN_PROGRESS
            - FAILURE
            - SUCCESS
        progress:
          type: string
          description: Human-readable task progress indicator
          example: 100%
        outputs:
          type: array
          description: List of URLs pointing to generated assets
          items:
            type: string
            format: uri
        fail_reason:
          type: string
          description: Explanation of the failure if the task did not succeed
        submit_time:
          type: integer
          format: int64
          description: Unix timestamp when the task was submitted
        start_time:
          type: integer
          format: int64
          description: Unix timestamp when task processing began
        finish_time:
          type: integer
          format: int64
          description: Unix timestamp when task processing finished
      description: Task execution details
  securitySchemes:
    bearerAuth:
      type: http
      description: Bearer authentication using API key
      scheme: bearer
      bearerFormat: API Key

````