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

# Get Task Status

> Query image task execution status and retrieve generated image files

# Get Task Status

Query the execution status of image generation and editing tasks and retrieve generated images when complete.

## Endpoint

```http theme={"dark"}
GET https://api.poyo.ai/api/generate/status/{task_id}
```

## Authentication

All requests require Bearer token authentication:

```bash theme={"dark"}
Authorization: Bearer YOUR_API_KEY
```

## Parameters

### Path Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `task_id` | string | Yes | Unique task identifier returned from the submit endpoint |

## Response

### Success Response (200)

```json theme={"dark"}
{
  "code": 200,
  "data": {
    "task_id": "task-unified-1757165031-uyujaw3d",
    "status": "finished",
    "credits_amount": 2,
    "files": [
      {
        "file_url": "https://storage.poyo.ai/generated/image-abc123.jpg",
        "file_type": "image"
      }
    ],
    "created_time": "2025-11-12T10:30:00",
    "progress": 100,
    "error_message": null
  }
}
```

### Response Fields

| Field | Type | Description |
| - | - | - |
| `code` | integer | HTTP status code (200 for success) |
| `data.task_id` | string | Unique task identifier |
| `data.status` | string | Task status: `not_started`, `running`, `finished`, `failed` |
| `data.credits_amount` | number | Credits charged for the task |
| `data.files` | array | Generated images when status is `finished` |
| `data.files[].file_url` | string | Direct URL to generated file |
| `data.files[].file_type` | string | Type of generated file, usually `image` |
| `data.created_time` | string | ISO 8601 timestamp of task creation |
| `data.progress` | integer | Completion percentage (0-100) |
| `data.error_message` | string | Error description when status is `failed` |

### Status Values

| Status | Description |
| - | - |
| `not_started` | Task is queued, waiting to be processed |
| `running` | Task is currently being generated |
| `finished` | Task completed successfully, results available in `files` |
| `failed` | Task failed, error details in `error_message` |

### Failed Task

```json theme={"dark"}
{
  "code": 200,
  "data": {
    "task_id": "task-unified-1757165031-uyujaw3d",
    "status": "failed",
    "credits_amount": 0,
    "files": [],
    "created_time": "2025-11-12T10:30:00",
    "progress": 0,
    "error_message": "The prompt violates our content policy"
  }
}
```

## Code Example

```bash theme={"dark"}
curl -X GET https://api.poyo.ai/api/generate/status/task-unified-1757165031-uyujaw3d \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Important Notes

> [!TIP]
>
> **Poll Interval**: Check status every 2-5 seconds. Typical image generation takes 15-60 seconds.

> [!WARNING]
>
> **Content Validity**: Generated images are accessible for **3 days** after creation. Download and save your content promptly.

> [!TIP]
>
> **Webhooks**: Instead of polling, you can provide a `callback_url` when submitting tasks to receive automatic notifications. See [Image Webhook Callbacks](https://docs.poyo.ai/api-manual/task-management/image-webhooks.md).

For code samples in more languages, polling with backoff, and HTTP error codes, see the [unified task status](https://docs.poyo.ai/api-manual/task-management/status.md) page.


## OpenAPI

````yaml api-manual/task-management/image-status.json GET /api/generate/status/{task_id}
openapi: 3.1.0
info:
  title: PoYo AI - Image Task Status API
  description: Query image task execution status and retrieve generated image files
  version: 1.0.0
servers:
  - url: https://api.poyo.ai
security:
  - BearerAuth: []
paths:
  /api/generate/status/{task_id}:
    get:
      tags:
        - Image Task Management
      summary: Query Image Task Status
      operationId: queryImageTaskStatus
      parameters:
        - name: task_id
          in: path
          required: true
          schema:
            type: string
          description: Unique task identifier returned from the submit endpoint
      responses:
        '200':
          description: Task status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
              examples:
                finished:
                  summary: Finished image task
                  value:
                    code: 200
                    data:
                      task_id: task-unified-1757165031-uyujaw3d
                      status: finished
                      credits_amount: 2
                      files:
                        - file_url: https://storage.poyo.ai/generated/image-abc123.jpg
                          file_type: image
                      created_time: '2025-11-12T10:30:00'
                      progress: 100
components:
  schemas:
    StatusResponse:
      type: object
      required:
        - code
        - data
      properties:
        code:
          type: integer
          example: 200
        data:
          $ref: '#/components/schemas/TaskStatus'
      example:
        code: 200
        data:
          task_id: task-unified-1757165031-uyujaw3d
          status: finished
          credits_amount: 2
          files:
            - file_url: https://storage.poyo.ai/generated/image-abc123.jpg
              file_type: image
          created_time: '2025-11-12T10:30:00'
          progress: 100
    TaskStatus:
      type: object
      properties:
        task_id:
          type: string
        status:
          type: string
          enum:
            - not_started
            - running
            - finished
            - failed
          example: finished
        credits_amount:
          type: number
          description: Credits charged for the task
          example: 2
        files:
          type: array
          items:
            $ref: '#/components/schemas/FileItem'
        created_time:
          type: string
          format: date-time
        progress:
          type: number
          example: 100
        error_message:
          type:
            - string
            - 'null'
      example:
        task_id: task-unified-1757165031-uyujaw3d
        status: finished
        credits_amount: 2
        files:
          - file_url: https://storage.poyo.ai/generated/image-abc123.jpg
            file_type: image
        created_time: '2025-11-12T10:30:00'
        progress: 100
    FileItem:
      type: object
      required:
        - file_url
        - file_type
      properties:
        label:
          type: string
          description: Optional file label when provided by the model
        file_url:
          type: string
          format: uri
          example: https://storage.poyo.ai/generated/image-abc123.jpg
        file_type:
          type: string
          enum:
            - image
            - video
            - audio
            - 3d
            - other
          example: image
        format:
          type: string
          description: Optional file format when provided by the model
        content_type:
          type: string
          description: Optional MIME type when provided by the model
        file_name:
          type: string
          description: Optional file name when provided by the model
        file_size:
          type: integer
          description: Optional file size in bytes when provided by the model
      example:
        file_url: https://storage.poyo.ai/generated/image-abc123.jpg
        file_type: image
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.