> ## 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 приложения, конечного пользователя, учетных данных.

## Пакетный запрос (`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,
      "finished_at": 1763142637.404
    }
  ],
  "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.