OpenAI Tasks API Integration and Usage

The OpenAI Tasks API is used to query the results of tasks previously submitted to the OpenAI image interface in callback mode. Use this interface when you cannot wait for a synchronous HTTP response or wish to query the task later. In callback mode, the original image interface will immediately return a task_id after accepting the request. You hold this task_id directly and can query this interface with it when needed, without needing to pass a custom trace_id (only required if you want to associate it with your own business identifier).

Tasks will only be persisted if the original image request includes a callback_url. Requests made in synchronous (non-callback) mode will not be stored.

Application Process

The OpenAI Tasks API shares authorization with existing OpenAI services. If you have already applied for OpenAI Images Generations, you can directly use the same token to call this interface without additional application. New users have a free quota for their first application.

Interface Address

POST https://api.acedata.cloud/openai/tasks

Supported action:

Operation	Description
`retrieve`	Query a single task by `id` or `trace_id`
`retrieve_batch`	Batch query by `ids` / `trace_ids` / `application_id` / `user_id`

Request Headers

accept: application/json
authorization: Bearer {token}
content-type: application/json

Single Task Query (`retrieve`)

Request Body

Field	Type	Required	Description
`action`	string	Yes	Fixed as `retrieve`
`id`	string	One of two	The task ID returned in the synchronous response when submitting the image request (recommended)
`trace_id`	string	One of two	Only needed if you explicitly passed a custom `trace_id` in the original request

At least one of id and trace_id must be provided. Generally, you can directly use the id from the submission response; trace_id should only be passed if you want to associate it with a custom business identifier.

Code Example

CURL

curl -X POST 'https://api.acedata.cloud/openai/tasks' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "action": "retrieve",
    "id": "7489df4c-ef03-4de0-b598-e9a590793434"
  }'

Python

import requests

url = "https://api.acedata.cloud/openai/tasks"
headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json",
}
payload = {
    "action": "retrieve",
    "id": "7489df4c-ef03-4de0-b598-e9a590793434",
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())

Response Example

When the task exists:

{
  "_id": "67a1b2c3d4e5f6a7b8c9d0e1",
  "id": "7489df4c-ef03-4de0-b598-e9a590793434",
  "trace_id": "my-custom-trace-001",
  "type": "images",
  "application_id": "9dec7b2a-1cad-41ff-8536-d4ddaf2525d4",
  "user_id": "5d8e7f6a-1234-4abc-9def-0123456789ab",
  "credential_id": "68253cc8-505d-47f4-97ad-0050a62e4975",
  "created_at": 1763142607.967,
  "started_at": 1763142607.97,
  "finished_at": 1763142637.404,
  "elapsed": 29.437,
  "request": {
    "model": "gpt-image-1",
    "prompt": "A cat sitting on a table",
    "size": "1024x1024",
    "callback_url": "https://your.server/callback"
  },
  "response": {
    "created": 1763142637,
    "data": [
      { "url": "https://platform.cdn.acedata.cloud/openai/...png" }
    ],
    "success": true
  }
}

Returns an empty object when no tasks are matched:

{}

Field Descriptions

id: The task ID generated when the original image request is accepted.
trace_id: The custom tracking identifier passed in the original request, facilitating association with client business.
type: Task type. Tasks written for the gpt-image series (e.g., gpt-image-2) are images; gpt-image-1, nano-banana, etc., use images_generations / images_edits, and some chat interfaces are chat_completions_image.
request: The complete request body of the original request.
response: The final response body returned upon callback completion.
created_at / started_at / finished_at: Unix timestamps (seconds, floating point).
elapsed: Execution time (seconds, floating point).
application_id / user_id / credential_id: The application, end user, and credential ID.

Batch Query (`retrieve_batch`)

Request Body

Field	Type	Description
`action`	string	Fixed as `retrieve_batch`
`ids`	string[]	Query by a list of task IDs
`trace_ids`	string[]	Query by a list of `trace_id`
`application_id`	string	Query all tasks by application
`user_id`	string	Query all tasks by end user
`type`	string	Filter by task type (values: `images`, `images_generations`, `images_edits`)
`offset`	int	Pagination starting point, default `0`
`limit`	int	Number of items per page, default `12`
`created_at_min`	float	Start timestamp (Unix seconds)
`created_at_max`	float	End timestamp (Unix seconds)

You can pass one of ids / trace_ids / application_id / user_id or created_at_* time window.

CURL Example

curl -X POST 'https://api.acedata.cloud/openai/tasks' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "action": "retrieve_batch",
    "trace_ids": ["my-trace-001", "my-trace-002"]
  }'

Response Example

{
  "items": [
    {
      "_id": "67a1b2c3d4e5f6a7b8c9d0e1",
      "id": "7489df4c-ef03-4de0-b598-e9a590793434",
      "trace_id": "my-trace-001",
      "type": "images",
      "request": {
        "model": "gpt-image-2",
        "prompt": "A cat"
      },
      "response": {
        "data": [
          {
            "url": "https://...png"
          }
        ]
      },
      "created_at": 1763142607.967,
      "started_at": 1763142608.027,
      "finished_at": 1763142637.404,
      "elapsed": 29.377
    }
  ],
  "count": 1
}

End-to-end Example: Submit and Poll

The Tasks API mainly serves asynchronous processes in callback mode. In callback mode, the submission interface will immediately return a task_id (i.e., task ID), and then you only need to directly use this task_id to poll the Tasks interface, without needing to generate a trace_id yourself.

import os, time, requests

API = "https://api.acedata.cloud"
HEADERS = {
    "authorization": f"Bearer {os.environ['ACEDATA_API_KEY']}",
    "content-type": "application/json",
}

# 1. Submit image generation task (callback mode: just include callback_url to immediately return task_id)
submit = requests.post(
    f"{API}/openai/images/generations",
    headers=HEADERS,
    json={
        "model": "gpt-image-1",
        "prompt": "A watercolor style cat sitting on a table",
        "callback_url": "https://webhook.site/your-uuid",
    },
).json()
print("submitted:", submit)

task_id = submit["task_id"]

# 2. Directly use the task_id from the submission response to poll the Tasks interface until the task is complete
while True:
    task = requests.post(
        f"{API}/openai/tasks",
        headers=HEADERS,
        json={"action": "retrieve", "id": task_id},
    ).json()
    if task and task.get("response"):
        print("finished:", task["response"])
        break
    time.sleep(3)

Notes

The Tasks interface itself does not incur charges, so you can poll with peace of mind. Only the original image generation/editing requests will incur charges.
Task records will only be written if the original request includes a callback_url; synchronous calls will not generate queryable tasks.
Task records that exceed the platform’s retention period may be cleared.

Getting Started

Core Concepts

AI Chat

AI Image

AI Video

AI Audio

Web & Data

CAPTCHA

Identity

Proxy

Advanced

OpenAI Tasks API Integration and Usage

Application Process

Interface Address

Request Headers

Single Task Query (`retrieve`)

Request Body

Code Example

CURL

Python

Response Example

Field Descriptions

Batch Query (`retrieve_batch`)

Request Body

CURL Example

Response Example

End-to-end Example: Submit and Poll

Notes

​Application Process

​Interface Address

​Request Headers

​Single Task Query (retrieve)

​Request Body

​Code Example

​CURL

​Python

​Response Example

​Field Descriptions

​Batch Query (retrieve_batch)

​Request Body

​CURL Example

​Response Example

​End-to-end Example: Submit and Poll

​Notes

Application Process

Interface Address

Request Headers

Single Task Query (`retrieve`)

Request Body

Code Example

CURL

Python

Response Example

Field Descriptions

Batch Query (`retrieve_batch`)

Request Body

CURL Example

Response Example

End-to-end Example: Submit and Poll

Notes