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

# Retrieve an image generation task

> Use CometAPI GET /v1/images/generations/{task_id} to poll an async OpenAI-compatible image generation task and retrieve final image data.

Use this endpoint after you create an image with `POST /v1/images/generations` and `async: true`. The create request returns `data.task_id`, and this endpoint returns the task state plus final image data when the task succeeds.

## Poll an image task

<Steps>
  <Step title="Create the task">
    Send `POST /v1/images/generations` with `async: true`, then store `data.task_id`.
  </Step>

  <Step title="Poll the task">
    Call this endpoint with the stored task ID until `data.status` is `success` or `failure`.
  </Step>

  <Step title="Read the image data">
    When `data.status` is `success`, read the first item in `data.data`. Depending on the selected model, the item can include `b64_json`, `url`, or `revised_prompt`.
  </Step>
</Steps>

## Status values

* `pending`: The task is queued or generating.
* `success`: The task finished and `data.data` contains the generated image data.
* `failure`: The task failed. Check `data.fail_reason` when it is returned.


## OpenAPI

````yaml api/openapi/image/openai/get-image-generation-task.openapi.json GET /v1/images/generations/{task_id}
openapi: 3.1.0
info:
  title: Image generation task API
  version: 1.0.0
  description: >-
    Retrieve an async image generation task created by `POST
    /v1/images/generations` with `async: true`.
servers:
  - url: https://api.cometapi.com
security:
  - bearerAuth: []
paths:
  /v1/images/generations/{task_id}:
    get:
      summary: Retrieve an image generation task
      description: >-
        Poll an async image generation task by task ID. Use the `task_id`
        returned by an async `POST /v1/images/generations` request.
      operationId: retrieve_image_generation_task
      parameters:
        - name: task_id
          in: path
          required: true
          description: Task ID returned in `data.task_id` by the async create request.
          schema:
            type: string
          example: <task_id>
      responses:
        '200':
          description: Current image generation task state.
          content:
            application/json:
              schema:
                type: object
                required:
                  - code
                  - data
                properties:
                  code:
                    type: string
                    description: >-
                      Request status code. Successful task lookups return
                      `success`.
                    example: success
                  message:
                    type: string
                    description: Optional status message.
                  data:
                    type: object
                    required:
                      - task_id
                      - status
                      - data
                    properties:
                      task_id:
                        type: string
                        description: Task ID for this image generation job.
                      status:
                        type: string
                        description: >-
                          Task state. Poll while the value is `pending`; read
                          `data[]` when the value is `success`.
                        enum:
                          - pending
                          - success
                          - failure
                      data:
                        type: array
                        description: >-
                          Generated image data. The array is empty until the
                          task succeeds.
                        items:
                          type: object
                          properties:
                            url:
                              type: string
                              description: >-
                                Temporary image URL when the selected model
                                supports URL output.
                            b64_json:
                              type: string
                              description: >-
                                Base64-encoded image payload for models that
                                return inline content.
                            revised_prompt:
                              type: string
                              description: Provider-rewritten prompt, when available.
                      fail_reason:
                        type: string
                        description: Failure reason when the task status is `failure`.
                example:
                  code: success
                  data:
                    task_id: <task_id>
                    status: success
                    data:
                      - b64_json: <base64-image-data>
              examples:
                pending:
                  summary: Pending task
                  value:
                    code: success
                    data:
                      task_id: <task_id>
                      status: pending
                      data: []
                success:
                  summary: Finished task
                  value:
                    code: success
                    data:
                      task_id: <task_id>
                      status: success
                      data:
                        - b64_json: <base64-image-data>
      x-codeSamples:
        - lang: Shell
          label: Poll until done
          source: |
            TASK_ID="<task_id>"

            while true; do
              RESPONSE=$(curl -s "https://api.cometapi.com/v1/images/generations/$TASK_ID" \
                -H "Authorization: Bearer $COMETAPI_KEY")
              STATUS=$(printf "%s" "$RESPONSE" | python3 -c "import json,sys; print(json.load(sys.stdin)['data']['status'])")
              echo "status: $STATUS"
              case "$STATUS" in success | failure) break;; esac
              sleep 3
            done

            printf "%s\n" "$RESPONSE"
        - lang: Python
          label: Poll until done
          source: |
            import os
            import time
            import requests

            task_id = "<task_id>"
            headers = {"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]}

            while True:
                task = requests.get(
                    f"https://api.cometapi.com/v1/images/generations/{task_id}",
                    headers=headers,
                ).json()
                status = task["data"]["status"]
                print(status)
                if status in ("success", "failure"):
                    break
                time.sleep(3)

            if status == "success":
                print(task["data"]["data"][0].keys())
        - lang: JavaScript
          label: Poll until done
          source: >
            const taskId = "<task_id>";

            const headers = { Authorization: `Bearer
            ${process.env.COMETAPI_KEY}` };


            let task;

            while (true) {
              const response = await fetch(
                `https://api.cometapi.com/v1/images/generations/${taskId}`,
                { headers },
              );
              task = await response.json();
              const status = task.data.status;
              console.log(status);
              if (status === "success" || status === "failure") break;
              await new Promise((resolve) => setTimeout(resolve, 3000));
            }


            if (task.data.status === "success") {
              console.log(Object.keys(task.data.data[0]));
            }
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication. Use your CometAPI key.

````