> ## 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 a Seedream image task

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

Use this endpoint after you create a Seedream 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.

This workflow supports `doubao-seedream-4-0-250828`, `doubao-seedream-4-5-251128`, `doubao-seedream-5-0-260128`, and `seedream-5-0-pro-260628`. Check the [Models page](/overview/models) or `/v1/models` for account availability.

## Poll a Seedream 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 `data.data[0].url`. Other result fields, including `b64_json` and `revised_prompt`, can be empty in the URL workflow.
  </Step>
</Steps>

<Warning>
  Download or transfer the returned image promptly. The result URL is temporary; do not rely on a fixed lifetime.
</Warning>

## 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/seededit-seedream/get-bytedance-image-generation-task.openapi.json GET /v1/images/generations/{task_id}
openapi: 3.1.0
info:
  title: Seedream image generation task API
  version: 1.0.0
  description: >-
    Retrieve an async Seedream image generation task created by `POST
    /v1/images/generations` with `async: true`. This workflow is documented for
    `doubao-seedream-4-0-250828`, `doubao-seedream-4-5-251128`,
    `doubao-seedream-5-0-260128`, and `seedream-5-0-pro-260628`.
servers:
  - url: https://api.cometapi.com
security:
  - bearerAuth: []
paths:
  /v1/images/generations/{task_id}:
    get:
      summary: Retrieve a Seedream image generation task
      description: >-
        Poll an async Seedream image generation task by task ID. Use the
        `task_id` returned in `data.task_id` by an async create request.
      operationId: retrieve_seedream_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 Seedream image generation task state.
          content:
            application/json:
              schema:
                type: object
                required:
                  - code
                  - message
                  - data
                properties:
                  code:
                    type: string
                    description: >-
                      Request status code. Successful task lookups return
                      `success`.
                    example: success
                  message:
                    type: string
                    description: >-
                      Status message. Successful lookups can return an empty
                      string.
                  data:
                    type: object
                    required:
                      - task_id
                      - status
                      - data
                    properties:
                      task_id:
                        type: string
                        description: Task ID for this Seedream image generation job.
                      status:
                        type: string
                        description: >-
                          Task state. Keep polling 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 for the URL response
                                workflow. Download or transfer it promptly.
                            b64_json:
                              type: string
                              description: >-
                                Inline image field when returned. It can be an
                                empty string in the URL workflow.
                            revised_prompt:
                              type: string
                              description: >-
                                Provider-rewritten prompt when returned. It can
                                be an empty string.
                      fail_reason:
                        type: string
                        description: Failure reason when the task status is `failure`.
                example:
                  code: success
                  message: ''
                  data:
                    task_id: <task_id>
                    status: success
                    data:
                      - url: https://cdn.example.com/generated/seedream-image.jpg
                        b64_json: ''
                        revised_prompt: ''
              examples:
                pending:
                  summary: Pending task
                  value:
                    code: success
                    message: ''
                    data:
                      task_id: <task_id>
                      status: pending
                      data: []
                success:
                  summary: Finished task
                  value:
                    code: success
                    message: ''
                    data:
                      task_id: <task_id>
                      status: success
                      data:
                        - url: https://cdn.example.com/generated/seedream-image.jpg
                          b64_json: ''
                          revised_prompt: ''
                failure:
                  summary: Failed task
                  value:
                    code: success
                    message: ''
                    data:
                      task_id: <task_id>
                      status: failure
                      data: []
                      fail_reason: <failure-reason>
      x-codeSamples:
        - lang: Shell
          label: Poll until done
          source: |
            curl "https://api.cometapi.com/v1/images/generations/<task_id>" \
              -H "Authorization: Bearer $COMETAPI_KEY"
        - lang: Python
          label: Poll until done
          source: |
            import os
            import time
            import requests

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

            for _ in range(60):
                response = requests.get(
                    f"https://api.cometapi.com/v1/images/generations/{task_id}",
                    headers=headers,
                    timeout=30,
                )
                response.raise_for_status()
                task = response.json()
                status = task["data"]["status"]
                print(status)

                if status == "success":
                    print(task["data"]["data"][0]["url"])
                    break
                if status == "failure":
                    raise RuntimeError(task["data"].get("fail_reason", "Seedream task failed"))

                time.sleep(5)
            else:
                raise TimeoutError("Seedream task did not finish in time")
        - lang: JavaScript
          label: Poll until done
          source: >
            const taskId = "<task_id>";

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


            for (let attempt = 0; attempt < 60; attempt += 1) {
              const response = await fetch(
                `https://api.cometapi.com/v1/images/generations/${taskId}`,
                { headers, signal: AbortSignal.timeout(30_000) },
              );
              if (!response.ok) throw new Error(await response.text());

              const task = await response.json();
              const status = task.data.status;
              console.log(status);

              if (status === "success") {
                console.log(task.data.data[0].url);
                break;
              }
              if (status === "failure") {
                throw new Error(task.data.fail_reason ?? "Seedream task failed");
              }
              if (attempt === 59) throw new Error("Seedream task did not finish in time");

              await new Promise((resolve) => setTimeout(resolve, 5000));
            }
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication. Use your CometAPI key.

````