> ## 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 Integration and Usage

> OpenAI generation API guide - Ace Data Cloud

Die OpenAI Tasks API wird verwendet, um die Ergebnisse von zuvor im **Callback-Modus** an die OpenAI-Bildschnittstelle übermittelten Aufgaben abzufragen. Wenn Sie nicht auf die synchrone HTTP-Antwort warten können oder die Aufgabe später erneut abfragen möchten, verwenden Sie diese Schnittstelle.

Im Callback-Modus gibt die **ursprüngliche Bildschnittstelle nach der Annahme der Anfrage sofort eine `task_id` zurück**. Sie halten diese `task_id` direkt und können sie bei Bedarf zur Abfrage an diese Schnittstelle verwenden, ohne eine benutzerdefinierte `trace_id` zusätzlich übermitteln zu müssen (nur wenn Sie eine eigene Geschäftskennzeichnung zur Verknüpfung verwenden möchten, ist dies erforderlich).

> Die Aufgabe wird nur dann persistent gespeichert, wenn die ursprüngliche Bildanfrage eine `callback_url` enthält. Anfragen, die synchron (nicht im Callback-Modus) aufgerufen werden, werden nicht gespeichert.

## Antragsprozess

Die OpenAI Tasks API verwendet die gleiche Autorisierung wie die bestehenden OpenAI-Dienste. Wenn Sie bereits OpenAI Images Generations beantragt haben, können Sie dieselbe Token verwenden, um diese Schnittstelle aufzurufen, ohne eine zusätzliche Anfrage zu stellen.

Neue Benutzer haben bei der ersten Anfrage ein kostenloses Kontingent.

## Schnittstellenadresse

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

Unterstützte `action`:

| Operation | Beschreibung |
| - | - |
| `retrieve` | Abfrage einer einzelnen Aufgabe über `id` oder `trace_id` |
| `retrieve_batch` | Batch-Abfrage über `ids` / `trace_ids` / `application_id` / `user_id` |

## Anfrageheader

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

## Einzelne Aufgabenabfrage (`retrieve`)

### Anfragekörper

| Feld | Typ | Pflicht | Beschreibung |
| - | - | - | - |
| `action` | string | Ja | Festgelegt auf `retrieve` |
| `id` | string | Wahlweise | Die beim Einreichen der Bildanfrage in der synchronen Antwort zurückgegebene Aufgaben-ID (empfohlen) |
| `trace_id` | string | Wahlweise | Nur erforderlich, wenn Sie in der ursprünglichen Anfrage eine benutzerdefinierte `trace_id` übermittelt haben |

`id` und `trace_id` müssen mindestens eines übergeben werden. In der Regel verwenden Sie einfach die `id` aus der Antwort der Einreichung, `trace_id` wird nur übermittelt, wenn Sie eine benutzerdefinierte Geschäftskennzeichnung zur Verknüpfung verwenden möchten.

### Codebeispiel

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

### Rückgabe-Beispiel

Wenn die Aufgabe vorhanden ist:

```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": "Eine Katze, die auf einem Tisch sitzt",
    "size": "1024x1024",
    "callback_url": "https://your.server/callback"
  },
  "response": {
    "created": 1763142637,
    "data": [
      {
        "url": "https://platform.cdn.acedata.cloud/openai/...png"
      }
    ],
    "success": true
  }
}
```

Wenn keine Aufgabe gefunden wird, wird ein leeres Objekt zurückgegeben:

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

### Feldbeschreibung

* `id`: Die beim Bearbeiten der ursprünglichen Bildanfrage generierte Aufgaben-ID.
* `trace_id`: Die benutzerdefinierte Verfolgungskennzeichnung, die in der ursprünglichen Anfrage übermittelt wurde, um die Verknüpfung mit der Geschäftslogik des Clients zu erleichtern.
* `type`: Aufgabentyp. Aufgaben, die in der `gpt-image`-Serie (z. B. `gpt-image-2`) geschrieben werden, sind `images`; `gpt-image-1`, nano-banana usw. verwenden `images_generations` / `images_edits`, einige Chat-Schnittstellen sind `chat_completions_image`.
* `request`: Der vollständige Anfragekörper der ursprünglichen Anfrage.
* `response`: Der endgültige Antwortkörper, der bei Abschluss des Callbacks zurückgegeben wird.
* `created_at` / `started_at` / `finished_at`: Unix-Zeitstempel (Sekunden, Fließkomma).
* `elapsed`: Ausführungszeit (Sekunden, Fließkomma).
* `application_id` / `user_id` / `credential_id`: Zugehörige Anwendung, Endbenutzer, Anmeldeinformationen-ID.

## Batch-Abfrage (`retrieve_batch`)

### Anfragekörper

| Feld | Typ | Beschreibung |
| - | - | - |
| `action` | string | Festgelegt auf `retrieve_batch` |
| `ids` | string\[] | Abfrage nach Aufgaben-ID-Liste |
| `trace_ids` | string\[] | Abfrage nach `trace_id`-Liste |
| `application_id` | string | Abfrage aller Aufgaben nach Anwendung |
| `user_id` | string | Abfrage aller Aufgaben nach Endbenutzer |
| `type` | string | Filterung nach Aufgabentyp (Werte: `images`, `images_generations`, `images_edits`) |
| `offset` | int | Startpunkt für die Paginierung, Standard `0` |
| `limit` | int | Anzahl der Einträge pro Seite, Standard `12` |
| `created_at_min` | float | Start-Zeitstempel (Unix Sekunden) |
| `created_at_max` | float | End-Zeitstempel (Unix Sekunden) |

Es muss mindestens eines von `ids` / `trace_ids` / `application_id` / `user_id` oder `created_at_*` Zeitfenster übergeben werden.

### CURL-Beispiel

```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"]
  }'
```

### Rückgabe-Beispiel

```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": "Eine Katze"
      },
      "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-Beispiel: Einreichen und Abfragen

Die Tasks-API dient hauptsächlich einem asynchronen Prozess im Callback-Modus. Im Callback-Modus gibt die Einreichschnittstelle **sofort eine `task_id`** (d.h. Aufgaben-ID) zurück, die Sie direkt verwenden können, um die Tasks-Schnittstelle abzufragen, ohne selbst eine `trace_id` zu generieren.

```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. Einreichen einer Bildgenerierungsaufgabe (Callback-Modus: Mit callback_url wird sofort task_id zurückgegeben)
submit = requests.post(
    f"{API}/openai/images/generations",
    headers=HEADERS,
    json={
        "model": "gpt-image-1",
        "prompt": "Eine Aquarellstil Katze sitzt auf dem Tisch",
        "callback_url": "https://webhook.site/your-uuid",
    },
).json()
print("eingereicht:", submit)

task_id = submit["task_id"]

# 2. Verwenden Sie die task_id aus der Einreichantwort, um die Tasks-Schnittstelle abzufragen, bis die Aufgabe abgeschlossen ist
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("abgeschlossen:", task["response"])
        break
    time.sleep(3)
```

## Hinweise

* Die Tasks-Schnittstelle selbst **verursacht keine Kosten**, Sie können also bedenkenlos abfragen. Nur die ursprünglichen Bildgenerierungs-/Bearbeitungsanfragen werden berechnet.
* Nur wenn die ursprüngliche Anfrage `callback_url` enthält, wird ein Aufgabenprotokoll geschrieben; synchrone Aufrufe erzeugen keine abfragbaren Aufgaben.
* Aufgabenprotokolle, die die Aufbewahrungsfrist der Plattform überschreiten, können gelöscht werden.


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