> ## 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

OpenAI Tasks API används för att hämta resultatet av uppgifter som tidigare har skickats till OpenAI:s bildgränssnitt i **callback-läge**. När du inte kan vänta på en synkron HTTP-respons, eller vill fråga om uppgiften i efterhand, använd detta gränssnitt.

I callback-läge, **återger det ursprungliga bildgränssnittet omedelbart ett `task_id` efter att ha tagit emot begäran**. Du har direkt detta `task_id`, och när du behöver det kan du använda det för att fråga detta gränssnitt, utan att behöva skicka en anpassad `trace_id` (endast om du vill koppla det till din egen affärsidentifierare).

> Uppgiften kommer endast att sparas om den ursprungliga bildbegäran innehöll en `callback_url`. Begärningar som görs på ett synkront (icke-callback) sätt kommer inte att lagras.

## Ansökningsprocess

OpenAI Tasks API delar auktorisering med befintliga OpenAI-tjänster. Om du redan har ansökt om OpenAI Images Generations kan du direkt använda samma token för att anropa detta gränssnitt, utan att behöva ansöka om något ytterligare.

Nya användare har en gratis kvot vid första ansökan.

## Gränssnittsadress

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

Stödda `action`:

| Åtgärd | Beskrivning |
| - | - |
| `retrieve` | Hämta en enskild uppgift via `id` eller `trace_id` |
| `retrieve_batch` | Hämta flera uppgifter via `ids` / `trace_ids` / `application_id` / `user_id` |

## Begärningshuvud

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

## Enskild uppgiftshämtning (`retrieve`)

### Begärningskropp

| Fält | Typ | Obligatoriskt | Beskrivning |
| - | - | - | - |
| `action` | string | Ja | Fastställt till `retrieve` |
| `id` | string | Antingen/eller | Uppgiftens ID som returnerades i den synkrona responsen vid bildbegäran (rekommenderas) |
| `trace_id` | string | Antingen/eller | Endast om du uttryckligen angav en anpassad `trace_id` i den ursprungliga begäran |

Antingen `id` eller `trace_id` måste anges. I allmänhet kan du direkt använda `id` från svaret på begäran, `trace_id` bör endast anges om du vill koppla det till en anpassad affärsidentifierare.

### Kodexempel

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

### Exempel på svar

När uppgiften finns:

```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
  }
}
```

När ingen uppgift matchas returneras ett tomt objekt:

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

### Fältbeskrivning

* `id`: Uppgiftens ID som genererades när den ursprungliga bildbegäran behandlades.
* `trace_id`: Den anpassade spårningsidentifieraren som skickades i den ursprungliga begäran, för att underlätta kopplingen till klientens affär.
* `type`: Uppgiftstyp. Uppgifter skrivna med `gpt-image`-serien (som `gpt-image-2`) är `images`; `gpt-image-1`, nano-banana etc. använder `images_generations` / `images_edits`, vissa chattgränssnitt är `chat_completions_image`.
* `request`: Den fullständiga begärningskroppen för den ursprungliga begäran.
* `response`: Den slutliga responskroppen som returneras när callbacken är klar.
* `created_at` / `started_at` / `finished_at`: Unix-tidsstämpel (sekunder, flyttal).
* `elapsed`: Utförandetid (sekunder, flyttal).
* `application_id` / `user_id` / `credential_id`: Tillhörande applikation, slutanvändare, autentiserings-ID.

## Batchhämtning (`retrieve_batch`)

### Begärningskropp

| Fält | Typ | Beskrivning |
| - | - | - |
| `action` | string | Fastställt till `retrieve_batch` |
| `ids` | string\[] | Hämta via lista av uppgiftens ID |
| `trace_ids` | string\[] | Hämta via lista av `trace_id` |
| `application_id` | string | Hämta alla uppgifter via applikation |
| `user_id` | string | Hämta alla uppgifter via slutanvändare |
| `type` | string | Filtrera efter uppgiftstyp (värden: `images`, `images_generations`, `images_edits`) |
| `offset` | int | Startpunkt för paginering, standard `0` |
| `limit` | int | Antal poster per sida, standard `12` |
| `created_at_min` | float | Starttidsstämpel (Unix sekunder) |
| `created_at_max` | float | Sluttidsstämpel (Unix sekunder) |

Antingen `ids` / `trace_ids` / `application_id` / `user_id` eller `created_at_*` tidsfönster kan anges.

### CURL-exempel

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

### Exempel på svar

```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": "En katt"
      },
      "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 exempel: Skicka och pollera

Tasks API tjänar främst för asynkrona processer i callback-läge. I callback-läge kommer submit-gränssnittet att **omedelbart synkronisera och returnera en `task_id`** (dvs. uppgifts-ID), och därefter behöver du bara använda detta `task_id` för att pollera Tasks-gränssnittet, utan att själv generera `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. Skicka bildgenereringsuppgift (callback-läge: ange callback_url för att omedelbart få tillbaka task_id)
submit = requests.post(
    f"{API}/openai/images/generations",
    headers=HEADERS,
    json={
        "model": "gpt-image-1",
        "prompt": "En akvarellstil katt sitter på bordet",
        "callback_url": "https://webhook.site/your-uuid",
    },
).json()
print("inlämnad:", submit)

task_id = submit["task_id"]

# 2. Använd direkt task_id från svaret för att pollera Tasks-gränssnittet tills uppgiften är klar
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("avslutad:", task["response"])
        break
    time.sleep(3)
```

## Viktiga punkter

* Tasks-gränssnittet **debiterar inte**, så du kan tryggt pollera. Endast de ursprungliga bildgenererings-/redigeringsförfrågningarna kommer att debiteras.
* Endast när den ursprungliga förfrågan innehåller `callback_url` kommer uppgiftsregister att skrivas; synkrona anrop kommer inte att generera några sökbara uppgifter.
* Uppgiftsregister som överskrider plattformens lagringsperiod kan rensas.


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