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

# Intégration et utilisation de l'API OpenAI Tasks

> OpenAI generation API guide - Ace Data Cloud

L'API OpenAI Tasks est utilisée pour interroger les résultats des tâches soumises précédemment au biais de **mode de rappel** à l'interface d'image d'OpenAI. Lorsque vous ne pouvez pas attendre une réponse HTTP synchrone, ou si vous souhaitez interroger à nouveau la tâche ultérieurement, veuillez utiliser cette interface.

En mode de rappel, **l'interface d'image d'origine renverra immédiatement un `task_id` après avoir accepté la demande**. Vous détenez directement ce `task_id` et pouvez l'utiliser pour interroger cette interface lorsque nécessaire, sans avoir à transmettre un `trace_id` personnalisé (sauf si vous souhaitez établir une association avec votre propre identifiant commercial).

> Les tâches ne seront persistées que si la demande d'image d'origine contient un `callback_url`. Les demandes effectuées de manière synchrone (non en mode de rappel) ne seront pas stockées.

## Processus de demande

L'API OpenAI Tasks partage l'autorisation avec les services OpenAI existants. Si vous avez déjà demandé des générations d'images OpenAI, vous pouvez directement utiliser le même token pour appeler cette interface, sans demande supplémentaire.

Les nouveaux utilisateurs bénéficient d'un quota gratuit lors de leur première demande.

## Adresse de l'API

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

Actions supportées :

| Opération | Description |
| - | - |
| `retrieve` | Interroger une tâche unique par `id` ou `trace_id` |
| `retrieve_batch` | Interroger plusieurs tâches par `ids` / `trace_ids` / `application_id` / `user_id` |

## En-têtes de requête

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

## Interrogation d'une tâche unique (`retrieve`)

### Corps de la requête

| Champ | Type | Obligatoire | Description |
| - | - | - | - |
| `action` | string | Oui | Fixe à `retrieve` |
| `id` | string | Un des deux | ID de tâche retourné dans la réponse synchrone lors de la soumission de la demande d'image (recommandé) |
| `trace_id` | string | Un des deux | Nécessaire uniquement si vous avez explicitement transmis un `trace_id` personnalisé dans la demande d'origine |

Il faut transmettre au moins `id` ou `trace_id`. En général, il suffit d'utiliser directement l'`id` de la réponse de soumission, `trace_id` n'est à transmettre que si vous souhaitez établir une association avec un identifiant commercial personnalisé.

### Exemple de code

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

### Exemple de réponse

Lorsque la tâche existe :

```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": "Un chat assis sur une table",
    "size": "1024x1024",
    "callback_url": "https://your.server/callback"
  },
  "response": {
    "created": 1763142637,
    "data": [
      {
        "url": "https://platform.cdn.acedata.cloud/openai/...png"
      }
    ],
    "success": true
  }
}
```

Lorsque aucune tâche n'est trouvée, renvoie un objet vide :

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

### Description des champs

* `id` : ID de tâche généré lors de l'acceptation de la demande d'image d'origine.
* `trace_id` : Identifiant de suivi personnalisé transmis dans la demande d'origine, facilitant l'association avec les activités commerciales du client.
* `type` : Type de tâche. Les tâches écrites pour la série `gpt-image` (comme `gpt-image-2`) sont de type `images` ; `gpt-image-1`, nano-banana, etc. utilisent `images_generations` / `images_edits`, certaines interfaces de chat sont de type `chat_completions_image`.
* `request` : Corps complet de la demande d'origine.
* `response` : Corps de réponse final retourné lors de l'achèvement du rappel.
* `created_at` / `started_at` / `finished_at` : Horodatages Unix (secondes, flottant).
* `elapsed` : Temps d'exécution (secondes, flottant).
* `application_id` / `user_id` / `credential_id` : ID de l'application, de l'utilisateur final, et des identifiants de crédentiel.

## Interrogation par lot (`retrieve_batch`)

### Corps de la requête

| Champ | Type | Description |
| - | - | - |
| `action` | string | Fixe à `retrieve_batch` |
| `ids` | string\[] | Interroger par liste d'ID de tâche |
| `trace_ids` | string\[] | Interroger par liste de `trace_id` |
| `application_id` | string | Interroger toutes les tâches par application |
| `user_id` | string | Interroger toutes les tâches par utilisateur final |
| `type` | string | Filtrer par type de tâche (valeurs : `images`, `images_generations`, `images_edits`) |
| `offset` | int | Point de départ de la pagination, par défaut `0` |
| `limit` | int | Nombre d'éléments par page, par défaut `12` |
| `created_at_min` | float | Horodatage de début (secondes Unix) |
| `created_at_max` | float | Horodatage de fin (secondes Unix) |

Il suffit de transmettre l'un des `ids` / `trace_ids` / `application_id` / `user_id` ou des fenêtres temporelles `created_at_*`.

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

### Exemple de réponse

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

## Exemple de bout en bout : soumettre et interroger

L'API Tasks sert principalement à un processus asynchrone en mode de rappel. En mode de rappel, l'interface de soumission renverra **immédiatement un `task_id`** (c'est-à-dire l'ID de la tâche), après quoi vous n'avez qu'à utiliser ce `task_id` pour interroger l'interface Tasks, sans avoir à générer vous-même un `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. Soumettre une tâche de génération d'images (mode de rappel : en incluant callback_url, task_id sera immédiatement renvoyé)
submit = requests.post(
    f"{API}/openai/images/generations",
    headers=HEADERS,
    json={
        "model": "gpt-image-1",
        "prompt": "Un chat dans un style aquarelle assis sur une table",
        "callback_url": "https://webhook.site/your-uuid",
    },
).json()
print("soumis :", submit)

task_id = submit["task_id"]

# 2. Interroger directement l'interface Tasks avec le task_id de la réponse de soumission, jusqu'à ce que la tâche soit terminée
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("terminé :", task["response"])
        break
    time.sleep(3)
```

## Remarques

* L'interface Tasks elle-même **n'entraîne pas de frais**, vous pouvez interroger sans souci. Seules les demandes de génération/édition d'images originales seront facturées.
* Les enregistrements de tâches ne seront écrits que si la demande originale contient `callback_url` ; les appels synchrones ne produiront pas de tâches consultables.
* Les enregistrements de tâches dépassant la période de conservation de la plateforme peuvent être nettoyés.


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