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

# Query image task

> Poll the status and result of an image generation task created via `POST /v1/image-generation`.

Call this endpoint periodically with the `task_id` returned from task creation. When `status` is `Success`, `output_images` contains the generated image URLs.

**Note:** this endpoint's envelope uses `message`, not `msg` as the create task endpoint does. Plan both field names when parsing.

### Recommended polling schedule

Image generation averages ~1 minute (some as fast as 10s). Use this schedule to balance responsiveness and request cost:

| Phase        | Elapsed       | Interval         |
| ---          | ---           | ---              |
| Initial wait | 0 – 10s       | — (no requests)  |
| Dense        | 10s – 1 min   | every 3s         |
| Medium       | 1 – 3 min     | every 6s         |
| Slow         | 3 – 15 min    | every 10s        |
| Timeout      | > 15 min      | stop, report error |

Stop polling when `status` is `Success`, `Failed`, or `Cancelled`.




## OpenAPI

````yaml /openapi/image/_query.yaml get /query/image-generation
openapi: 3.0.3
info:
  title: Query image generation task
  version: 1.0.0
  description: Poll the status and result of an image generation task.
servers:
  - url: https://api.linkmodel.ai/api/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: image
paths:
  /query/image-generation:
    get:
      tags:
        - image
      summary: Query image task
      description: >
        Poll the status and result of an image generation task created via `POST
        /v1/image-generation`.


        Call this endpoint periodically with the `task_id` returned from task
        creation. When `status` is `Success`, `output_images` contains the
        generated image URLs.


        **Note:** this endpoint's envelope uses `message`, not `msg` as the
        create task endpoint does. Plan both field names when parsing.


        ### Recommended polling schedule


        Image generation averages ~1 minute (some as fast as 10s). Use this
        schedule to balance responsiveness and request cost:


        | Phase        | Elapsed       | Interval         |

        | ---          | ---           | ---              |

        | Initial wait | 0 – 10s       | — (no requests)  |

        | Dense        | 10s – 1 min   | every 3s         |

        | Medium       | 1 – 3 min     | every 6s         |

        | Slow         | 3 – 15 min    | every 10s        |

        | Timeout      | > 15 min      | stop, report error |


        Stop polling when `status` is `Success`, `Failed`, or `Cancelled`.
      operationId: query-image-generation
      parameters:
        - name: task_id
          in: query
          required: true
          description: Task id returned from `POST /v1/image-generation`.
          schema:
            type: string
            example: aurora_xyz789
      responses:
        '200':
          description: Query result with current task status.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 0
                  data:
                    type: object
                    properties:
                      task_id:
                        type: string
                        example: aurora_xyz789
                      prompt:
                        type: string
                        example: A red panda coding at a laptop
                      status:
                        type: string
                        description: >-
                          Current task state. Poll until terminal (`Success` or
                          `Failed`).
                        enum:
                          - Pending
                          - Processing
                          - Success
                          - Failed
                          - Cancelled
                        example: Success
                      images:
                        type: array
                        description: >-
                          Input reference images echoed from the request (e.g.
                          for image-to-image tasks).
                        items:
                          type: string
                      output_images:
                        type: array
                        description: >-
                          Generated image URLs. Populated once `status` is
                          `Success`.
                        items:
                          type: string
                          format: uri
                        example:
                          - https://cdn.xxx.com/img_1.png
                      model:
                        type: string
                        example: gemini-3-pro-image-preview
                      metadata:
                        type: string
                        description: Reserved field. Usually empty.
                      msg:
                        type: string
                        description: Task-level detail or error message.
                  message:
                    type: string
                    description: >-
                      Envelope-level status. This endpoint uses `message`
                      (create task uses `msg`).
                    example: success
                  request_id:
                    type: string
                    format: uuid
        '400':
          description: Bad request — `task_id` missing or malformed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 400
                  message:
                    type: string
                    example: task_id is required
                  request_id:
                    type: string
        '401':
          description: Unauthorized — missing or invalid API key.
        '404':
          description: Task not found.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````