OpenAI Tasks API Integration and Usage

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

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

Rückgabe-Beispiel

Wenn die Aufgabe vorhanden ist:

{
  "_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:

{}

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

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

{
  "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.

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.

Erste Schritte

KI Chat

KI Bild

KI Video

KI Audio

Web & Daten

CAPTCHA

Identität

Coding

Weitere Anleitungen

OpenAI Tasks API Integration and Usage

Antragsprozess

Schnittstellenadresse

Anfrageheader

Einzelne Aufgabenabfrage (`retrieve`)

Anfragekörper

Codebeispiel

CURL

Python

Rückgabe-Beispiel

Feldbeschreibung

Batch-Abfrage (`retrieve_batch`)

Anfragekörper

CURL-Beispiel

Rückgabe-Beispiel

End-to-End-Beispiel: Einreichen und Abfragen

Hinweise

​Antragsprozess

​Schnittstellenadresse

​Anfrageheader

​Einzelne Aufgabenabfrage (retrieve)

​Anfragekörper

​Codebeispiel

​CURL

​Python

​Rückgabe-Beispiel

​Feldbeschreibung

​Batch-Abfrage (retrieve_batch)

​Anfragekörper

​CURL-Beispiel

​Rückgabe-Beispiel

​End-to-End-Beispiel: Einreichen und Abfragen

​Hinweise

Antragsprozess

Schnittstellenadresse

Anfrageheader

Einzelne Aufgabenabfrage (`retrieve`)

Anfragekörper

Codebeispiel

CURL

Python

Rückgabe-Beispiel

Feldbeschreibung

Batch-Abfrage (`retrieve_batch`)

Anfragekörper

CURL-Beispiel

Rückgabe-Beispiel

End-to-End-Beispiel: Einreichen und Abfragen

Hinweise