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

# OpenAI Tasks API підключення та використання

> OpenAI generation API guide - Ace Data Cloud

OpenAI Tasks API використовується для запиту результатів завдань, які раніше були подані до OpenAI зображення через **режим зворотного виклику**. Коли ви не можете дочекатися синхронної HTTP-відповіді або хочете повторно запитати завдання пізніше, використовуйте цей інтерфейс.

У режимі зворотного виклику, **оригінальний інтерфейс зображень після обробки запиту відразу повертає `task_id`**. Ви безпосередньо володієте цим `task_id` і можете використовувати його для запиту в цьому інтерфейсі, не передаючи додатковий `trace_id` (лише якщо ви хочете пов'язати його з вашим власним бізнес-ідентифікатором).

> Завдання буде збережено лише тоді, коли в оригінальному запиті зображення є `callback_url`. Запити, виконані синхронно (не в режимі зворотного виклику), не зберігаються.

## Процес подачі заявки

OpenAI Tasks API спільно використовує авторизацію з існуючими сервісами OpenAI. Якщо ви вже подали заявку на OpenAI Images Generations, ви можете безпосередньо використовувати той же токен для виклику цього інтерфейсу, не подаючи додаткову заявку.

Нові користувачі отримують безкоштовний ліміт при першій подачі заявки.

## Адреса інтерфейсу

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

Підтримувані `action`:

| Операція | Опис |
| - | - |
| `retrieve` | Запит на одну задачу за `id` або `trace_id` |
| `retrieve_batch` | Пакетний запит за `ids` / `trace_ids` / `application_id` / `user_id` |

## Заголовки запиту

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

## Запит на одну задачу (`retrieve`)

### Тіло запиту

| Поле | Тип | Обов'язкове | Опис |
| - | - | - | - |
| `action` | string | Так | Фіксоване значення `retrieve` |
| `id` | string | Один з двох | ID завдання, повернуте в синхронній відповіді на запит зображення (рекомендується використовувати) |
| `trace_id` | string | Один з двох | Використовується лише тоді, коли ви явно передали власний `trace_id` в оригінальному запиті |

Необхідно передати хоча б одне з `id` або `trace_id`. У загальному випадку достатньо використовувати `id`, що повертається в відповіді на запит, `trace_id` передавайте лише тоді, коли хочете пов'язати його з власним бізнес-ідентифікатором.

### Приклад коду

#### CURL

```bash theme={null}
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

```python theme={null}
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())
```

### Приклад відповіді

Коли завдання існує:

```json theme={null}
{
  "_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
  }
}
```

Коли не знайдено жодного завдання, повертається порожній об'єкт:

```json theme={null}
{}
```

### Опис полів

* `id`: ID завдання, згенероване під час обробки оригінального запиту зображення.
* `trace_id`: Користувацький ідентифікатор відстеження, переданий в оригінальному запиті, для зручності зв'язування з бізнесом клієнта.
* `type`: Тип завдання. Завдання, записані в серії `gpt-image` (наприклад, `gpt-image-2`), мають тип `images`; `gpt-image-1`, nano-banana тощо використовують `images_generations` / `images_edits`, деякі інтерфейси чату мають тип `chat_completions_image`.
* `request`: Повне тіло оригінального запиту.
* `response`: Остаточне тіло відповіді, повернуте після завершення зворотного виклику.
* `created_at` / `started_at` / `finished_at`: Unix-мітки часу (секунди, з плаваючою комою).
* `elapsed`: Час виконання (секунди, з плаваючою комою).
* `application_id` / `user_id` / `credential_id`: ID належної програми, кінцевого користувача, ID облікових даних.

## Пакетний запит (`retrieve_batch`)

### Тіло запиту

| Поле | Тип | Опис |
| - | - | - |
| `action` | string | Фіксоване значення `retrieve_batch` |
| `ids` | string\[] | Запит за списком ID завдань |
| `trace_ids` | string\[] | Запит за списком `trace_id` |
| `application_id` | string | Запит усіх завдань за додатком |
| `user_id` | string | Запит усіх завдань за кінцевим користувачем |
| `type` | string | Фільтрація за типом завдання (можливі значення: `images`, `images_generations`, `images_edits`) |
| `offset` | int | Початкова точка для пагінації, за замовчуванням `0` |
| `limit` | int | Кількість записів на сторінці, за замовчуванням `12` |
| `created_at_min` | float | Початкова мітка часу (Unix секунди) |
| `created_at_max` | float | Кінцева мітка часу (Unix секунди) |

Достатньо передати одне з `ids` / `trace_ids` / `application_id` / `user_id` або `created_at_*` часовий інтервал.

### Приклад CURL

```bash theme={null}
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"]
  }'
```

### Приклад відповіді

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

## Приклад крок за кроком: подача та опитування

API завдань в основному служить для асинхронних процесів у режимі зворотного виклику. У режимі зворотного виклику, інтерфейс подачі **відразу синхронно повертає `task_id`** (тобто ID завдання), після чого вам просто потрібно безпосередньо використовувати цей `task_id` для опитування інтерфейсу завдань, без необхідності самостійно генерувати `trace_id`.

```python theme={null}
import os, time, requests

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

# 1. Подати завдання на генерацію зображення (режим зворотного виклику: додайте callback_url, щоб відразу отримати task_id)
submit = requests.post(
    f"{API}/openai/images/generations",
    headers=HEADERS,
    json={
        "model": "gpt-image-1",
        "prompt": "Кіт у стилі акварелі сидить на столі",
        "callback_url": "https://webhook.site/your-uuid",
    },
).json()
print("подано:", submit)

task_id = submit["task_id"]

# 2. Безпосередньо використовуйте task_id з відповіді подачі для опитування інтерфейсу завдань, поки завдання не буде завершено
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("завершено:", task["response"])
        break
    time.sleep(3)
```

## Зверніть увагу

* Інтерфейс завдань сам по собі **не підлягає оплаті**, можете безпечно опитувати. Лише оригінальні запити на генерацію/редагування зображень будуть оплачуватися.
* Лише коли оригінальний запит містить `callback_url`, буде записано запис завдання; синхронний виклик не створює запитуваного завдання.
* Записи завдань, що перевищують термін зберігання платформи, можуть бути очищені.


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