> ## 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 integracja i użycie

> OpenAI generation API guide - Ace Data Cloud

OpenAI Tasks API służy do zapytania o wyniki zadań, które wcześniej zostały przesłane do interfejsu obrazów OpenAI w **trybie callback**. Gdy nie możesz czekać na synchronizowaną odpowiedź HTTP lub chcesz ponownie zapytać o zadanie później, użyj tego interfejsu.

W trybie callback, **oryginalny interfejs obrazów po przyjęciu żądania natychmiast zwraca `task_id`**. Posiadasz ten `task_id` i możesz go użyć do zapytania w tym interfejsie, gdy zajdzie taka potrzeba, bez konieczności dodatkowego przekazywania niestandardowego `trace_id` (tylko gdy chcesz powiązać to z własnym identyfikatorem biznesowym).

> Zadanie będzie trwałe tylko wtedy, gdy oryginalne żądanie obrazów zawiera `callback_url`. Żądania wywoływane w trybie synchronizowanym (nie callback) nie będą przechowywane.

## Proces aplikacji

OpenAI Tasks API korzysta z tej samej autoryzacji co istniejące usługi OpenAI. Jeśli już aplikowałeś o OpenAI Images Generations, możesz bezpośrednio użyć tego samego tokena do wywołania tego interfejsu, nie musisz składać dodatkowej aplikacji.

Nowi użytkownicy mają darmowy limit przy pierwszej aplikacji.

## Adres interfejsu

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

Obsługiwane `action`:

| Operacja | Opis |
| - | - |
| `retrieve` | Zapytanie o pojedyncze zadanie za pomocą `id` lub `trace_id` |
| `retrieve_batch` | Zapytanie o wiele zadań za pomocą `ids` / `trace_ids` / `application_id` / `user_id` |

## Nagłówki żądania

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

## Zapytanie o pojedyncze zadanie (`retrieve`)

### Treść żądania

| Pole | Typ | Wymagane | Opis |
| - | - | - | - |
| `action` | string | Tak | Ustalona wartość `retrieve` |
| `id` | string | Opcjonalnie | ID zadania zwrócone w odpowiedzi synchronizowanej przy przesyłaniu żądania obrazów (zalecane) |
| `trace_id` | string | Opcjonalnie | Należy użyć tylko wtedy, gdy w oryginalnym żądaniu wyraźnie przekazano niestandardowy `trace_id` |

Należy przekazać przynajmniej jedno z `id` lub `trace_id`. W normalnych okolicznościach wystarczy użyć `id` zwróconego w odpowiedzi, `trace_id` należy przekazać tylko wtedy, gdy chcesz powiązać to z niestandardowym identyfikatorem biznesowym.

### Przykład kodu

#### 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())
```

### Przykład odpowiedzi

Gdy zadanie istnieje:

```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": "Kot siedzący na stole",
    "size": "1024x1024",
    "callback_url": "https://your.server/callback"
  },
  "response": {
    "created": 1763142637,
    "data": [
      {
        "url": "https://platform.cdn.acedata.cloud/openai/...png"
      }
    ],
    "success": true
  }
}
```

Gdy nie znaleziono żadnego zadania, zwraca pusty obiekt:

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

### Opis pól

* `id`: ID zadania wygenerowane podczas przyjmowania oryginalnego żądania obrazów.
* `trace_id`: Niestandardowy identyfikator śledzenia przekazany w oryginalnym żądaniu, ułatwiający powiązanie z biznesem klienta.
* `type`: Typ zadania. Zadania zapisane w serii `gpt-image` (np. `gpt-image-2`) mają wartość `images`; `gpt-image-1`, nano-banana itp. używają `images_generations` / `images_edits`, a niektóre interfejsy czatu mają wartość `chat_completions_image`.
* `request`: Pełna treść oryginalnego żądania.
* `response`: Ostateczna treść odpowiedzi zwrócona po zakończeniu callbacku.
* `created_at` / `started_at` / `finished_at`: Znaczniki czasu Unix (sekundy, liczby zmiennoprzecinkowe).
* `elapsed`: Czas wykonania (sekundy, liczby zmiennoprzecinkowe).
* `application_id` / `user_id` / `credential_id`: ID aplikacji, użytkownika końcowego, ID poświadczenia.

## Zapytanie o wiele zadań (`retrieve_batch`)

### Treść żądania

| Pole | Typ | Opis |
| - | - | - |
| `action` | string | Ustalona wartość `retrieve_batch` |
| `ids` | string\[] | Zapytanie według listy ID zadań |
| `trace_ids` | string\[] | Zapytanie według listy `trace_id` |
| `application_id` | string | Zapytanie o wszystkie zadania według aplikacji |
| `user_id` | string | Zapytanie o wszystkie zadania według użytkownika końcowego |
| `type` | string | Filtrowanie według typu zadania (możliwe wartości: `images`, `images_generations`, `images_edits`) |
| `offset` | int | Punkt początkowy paginacji, domyślnie `0` |
| `limit` | int | Liczba elementów na stronie, domyślnie `12` |
| `created_at_min` | float | Początkowy znacznik czasu (Unix sekundy) |
| `created_at_max` | float | Końcowy znacznik czasu (Unix sekundy) |

Należy przekazać jedno z `ids` / `trace_ids` / `application_id` / `user_id` lub `created_at_*` w oknie czasowym.

### Przykład 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"]
  }'
```

### Przykład odpowiedzi

```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": "Kot" },
      "response": { "data": [{ "url": "https://...png" }] },
      "created_at": 1763142607.967,
      "finished_at": 1763142637.404
    }
  ],
  "count": 1
}
```

## Przykład end-to-end: przesyłanie i polling

API zadań głównie służy do asynchronicznych procesów w trybie callback. W trybie callback, interfejs przesyłania **natychmiast synchronizuje zwrot `task_id`** (czyli ID zadania), a następnie wystarczy bezpośrednio użyć tego `task_id` do pollingowania interfejsu zadań, bez potrzeby generowania `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. Przesyłanie zadania generowania obrazu (tryb callback: wystarczy podać callback_url, aby natychmiast zwrócić task_id)
submit = requests.post(
    f"{API}/openai/images/generations",
    headers=HEADERS,
    json={
        "model": "gpt-image-1",
        "prompt": "Kot w stylu akwareli siedzący na stole",
        "callback_url": "https://webhook.site/your-uuid",
    },
).json()
print("przesłano:", submit)

task_id = submit["task_id"]

# 2. Bezpośrednie użycie task_id z odpowiedzi przesyłania do pollingowania interfejsu zadań, aż zadanie zostanie zakończone
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("zakończono:", task["response"])
        break
    time.sleep(3)
```

## Uwagi

* Interfejs zadań **nie jest płatny**, można bez obaw pollingować. Tylko oryginalne żądania generowania/edycji obrazów będą obciążane opłatami.
* Tylko gdy oryginalne żądanie zawiera `callback_url`, zostanie zapisany rekord zadania; wywołania synchronizacyjne nie generują zadań do zapytania.
* Rekordy zadań, które przekroczyły okres przechowywania platformy, mogą zostać usunięte.


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