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

# Image Task Status API

> Check asynchronous t2i/i2i generation tasks and retrieve the generated image URLs.

## Overview

When you submit an image generation task (text-to-image or image-to-image) you receive a `task_id`. Use this endpoint to poll the execution lifecycle until the task either completes successfully or fails.

<Tip>
  Query every 3–5 seconds to maintain responsiveness without exceeding rate limits.
</Tip>

## Endpoint

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

**Headers**

* `Authorization: Bearer <SIRAY_API_TOKEN>`

**Path parameters**

| Name      | Description                                   |
| --------- | --------------------------------------------- |
| `task_id` | ID returned in the async submission response. |

## Response structure

```json theme={null}
{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "image_a8813a4b4c9",
    "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 request outcome.
* `data.task_id`: Echoes the submitted task identifier.
* `data.status`: Current lifecycle state — see the table below.
* `data.progress`: Human-readable percentage for UI display.
* `data.outputs`: Array of public URLs that host the generated image assets (present when `status` is `SUCCESS`).
* `data.fail_reason`: Populated if generation fails.
* `data.submit_time`, `data.start_time`, `data.finish_time`: Unix timestamps for auditing 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 them via the URLs in `outputs`.       |
| `FAILURE`     | Irrecoverable error; inspect `fail_reason` for remediation steps. |

## Usage example

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

> Once `status` becomes `SUCCESS`, fetch the image(s) via the URLs in `outputs`. If the task fails, retry only after resolving the reported `fail_reason`.


## OpenAPI

````yaml openapi-spec/task-status.json GET /v1/images/generations/async/{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/images/generations/async/{task_id}:
    get:
      tags:
        - Task Status
      summary: Query image generation task
      description: >-
        Retrieve the status and outputs of an asynchronous image generation
        task. The task ID is returned from the async POST request.
      operationId: get_image_task_status
      parameters:
        - name: task_id
          in: path
          description: Identifier returned from the image 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

````