Intégration et utilisation de l'API OpenAI Tasks

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

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

Exemple de réponse

Lorsque la tâche existe :

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

{}

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

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

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

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.

Démarrage

Chat IA

Image IA

Vidéo IA

Audio IA

Web & Données

CAPTCHA

Identité

Coding

Autres guides

Intégration et utilisation de l'API OpenAI Tasks

Processus de demande

Adresse de l’API

En-têtes de requête

Interrogation d’une tâche unique (`retrieve`)

Corps de la requête

Exemple de code

CURL

Python

Exemple de réponse

Description des champs

Interrogation par lot (`retrieve_batch`)

Corps de la requête

Exemple CURL

Exemple de réponse

Exemple de bout en bout : soumettre et interroger

Remarques

​Processus de demande

​Adresse de l’API

​En-têtes de requête

​Interrogation d’une tâche unique (retrieve)

​Corps de la requête

​Exemple de code

​CURL

​Python

​Exemple de réponse

​Description des champs

​Interrogation par lot (retrieve_batch)

​Corps de la requête

​Exemple CURL

​Exemple de réponse

​Exemple de bout en bout : soumettre et interroger

​Remarques

Processus de demande

Adresse de l’API

En-têtes de requête

Interrogation d’une tâche unique (`retrieve`)

Corps de la requête

Exemple de code

CURL

Python

Exemple de réponse

Description des champs

Interrogation par lot (`retrieve_batch`)

Corps de la requête

Exemple CURL

Exemple de réponse

Exemple de bout en bout : soumettre et interroger

Remarques