Integrazione e utilizzo dell'API OpenAI Tasks

L’API OpenAI Tasks è utilizzata per interrogare i risultati delle attività precedentemente inviate all’interfaccia immagini di OpenAI in modalità callback. Quando non è possibile attendere una risposta HTTP sincrona o si desidera interrogare nuovamente l’attività in un secondo momento, utilizzare questa interfaccia. In modalità callback, l’interfaccia immagini originale restituisce immediatamente un task_id dopo aver elaborato la richiesta. Si possiede direttamente questo task_id e, quando necessario, lo si utilizza per interrogare questa interfaccia, senza dover fornire un trace_id personalizzato (solo se si desidera associare con un identificatore di business proprio).

L’attività verrà persistere solo se la richiesta originale delle immagini include un callback_url. Le richieste effettuate in modo sincrono (non callback) non verranno memorizzate.

Processo di richiesta

L’API OpenAI Tasks condivide l’autorizzazione con i servizi OpenAI esistenti. Se hai già richiesto le Generazioni di Immagini OpenAI, puoi utilizzare direttamente lo stesso token per chiamare questa interfaccia, senza necessità di ulteriori richieste. I nuovi utenti hanno un credito gratuito alla prima richiesta.

Indirizzo dell’interfaccia

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

Azioni supportate:

Operazione	Descrizione
`retrieve`	Interroga un’attività singola tramite `id` o `trace_id`
`retrieve_batch`	Interroga in batch tramite `ids` / `trace_ids` / `application_id` / `user_id`

Intestazioni della richiesta

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

Interrogazione di un’attività singola (`retrieve`)

Corpo della richiesta

Campo	Tipo	Obbligatorio	Descrizione
`action`	string	Sì	Fisso come `retrieve`
`id`	string	Opzionale	ID dell’attività restituito nella risposta sincrona della richiesta di immagini (consigliato)
`trace_id`	string	Opzionale	Necessario solo se è stato esplicitamente fornito un `trace_id` personalizzato nella richiesta originale

È necessario fornire almeno id o trace_id. In generale, è sufficiente utilizzare direttamente l’id restituito nella risposta della richiesta, mentre trace_id deve essere fornito solo se si desidera associare con un identificatore di business personalizzato.

Esempio di codice

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

Esempio di risposta

Quando l’attività esiste:

{
  "_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 gatto seduto su un tavolo",
    "size": "1024x1024",
    "callback_url": "https://your.server/callback"
  },
  "response": {
    "created": 1763142637,
    "data": [
      {
        "url": "https://platform.cdn.acedata.cloud/openai/...png"
      }
    ],
    "success": true
  }
}

Quando non viene trovata alcuna attività, restituisce un oggetto vuoto:

{}

Descrizione dei campi

id: ID dell’attività generato al momento dell’elaborazione della richiesta originale delle immagini.
trace_id: Identificatore di tracciamento personalizzato fornito nella richiesta originale, utile per l’associazione con il business del client.
type: Tipo di attività. Le attività scritte nella serie gpt-image (come gpt-image-2) sono di tipo images; gpt-image-1, nano-banana, ecc. utilizzano images_generations / images_edits, alcune interfacce di chat sono di tipo chat_completions_image.
request: Corpo completo della richiesta originale.
response: Corpo della risposta finale restituito al termine del callback.
created_at / started_at / finished_at: Timestamp Unix (secondi, float).
elapsed: Tempo di esecuzione (secondi, float).
application_id / user_id / credential_id: ID dell’applicazione, dell’utente finale e delle credenziali.

Interrogazione in batch (`retrieve_batch`)

Corpo della richiesta

Campo	Tipo	Descrizione
`action`	string	Fisso come `retrieve_batch`
`ids`	string[]	Interroga in base all’elenco degli ID delle attività
`trace_ids`	string[]	Interroga in base all’elenco dei `trace_id`
`application_id`	string	Interroga tutte le attività in base all’applicazione
`user_id`	string	Interroga tutte le attività in base all’utente finale
`type`	string	Filtra in base al tipo di attività (valori: `images`, `images_generations`, `images_edits`)
`offset`	int	Punto di partenza per la paginazione, predefinito `0`
`limit`	int	Numero di elementi per pagina, predefinito `12`
`created_at_min`	float	Timestamp di inizio (Unix secondi)
`created_at_max`	float	Timestamp di fine (Unix secondi)

È sufficiente fornire uno tra ids / trace_ids / application_id / user_id o il periodo di tempo created_at_*.

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

Esempio di risposta

{
  "items": [
    {
      "_id": "67a1b2c3d4e5f6a7b8c9d0e1",
      "id": "7489df4c-ef03-4de0-b598-e9a590793434",
      "trace_id": "my-trace-001",
      "type": "images",
      "request": {
        "model": "gpt-image-2",
        "prompt": "Un gatto"
      },
      "response": {
        "data": [
          {
            "url": "https://...png"
          }
        ]
      },
      "created_at": 1763142607.967,
      "started_at": 1763142608.027,
      "finished_at": 1763142637.404,
      "elapsed": 29.377
    }
  ],
  "count": 1
}

Esempio end-to-end: invio e polling

L’API Tasks serve principalmente per flussi asincroni in modalità callback. In modalità callback, l’interfaccia di invio restituirà immediatamente un task_id (cioè l’ID del compito), dopodiché è sufficiente utilizzare direttamente questo task_id per il polling dell’interfaccia Tasks, senza dover generare 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. Inviare un compito di generazione di immagini (modalità callback: basta includere callback_url per restituire immediatamente task_id)
submit = requests.post(
    f"{API}/openai/images/generations",
    headers=HEADERS,
    json={
        "model": "gpt-image-1",
        "prompt": "Un gatto in stile acquerello seduto su un tavolo",
        "callback_url": "https://webhook.site/your-uuid",
    },
).json()
print("inviato:", submit)

task_id = submit["task_id"]

# 2. Utilizzare direttamente il task_id nella risposta di invio per il polling dell'interfaccia Tasks, fino al completamento del compito
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("completato:", task["response"])
        break
    time.sleep(3)

Note

L’interfaccia Tasks non comporta costi, puoi fare polling senza preoccupazioni. Solo le richieste di generazione/modifica delle immagini originali comporteranno costi.
Solo quando la richiesta originale include callback_url, verrà registrato il compito; le chiamate sincrone non genereranno compiti consultabili.
I registri dei compiti che superano il periodo di conservazione della piattaforma potrebbero essere eliminati.

Inizia

Chat AI

Immagine AI

Video AI

Audio AI

Web e Dati

CAPTCHA

Identità

Coding

Altre guide

Integrazione e utilizzo dell'API OpenAI Tasks

Processo di richiesta

Indirizzo dell’interfaccia

Intestazioni della richiesta

Interrogazione di un’attività singola (`retrieve`)

Corpo della richiesta

Esempio di codice

CURL

Python

Esempio di risposta

Descrizione dei campi

Interrogazione in batch (`retrieve_batch`)

Corpo della richiesta

Esempio CURL

Esempio di risposta

Esempio end-to-end: invio e polling

Note

​Processo di richiesta

​Indirizzo dell’interfaccia

​Intestazioni della richiesta

​Interrogazione di un’attività singola (retrieve)

​Corpo della richiesta

​Esempio di codice

​CURL

​Python

​Esempio di risposta

​Descrizione dei campi

​Interrogazione in batch (retrieve_batch)

​Corpo della richiesta

​Esempio CURL

​Esempio di risposta

​Esempio end-to-end: invio e polling

​Note

Processo di richiesta

Indirizzo dell’interfaccia

Intestazioni della richiesta

Interrogazione di un’attività singola (`retrieve`)

Corpo della richiesta

Esempio di codice

CURL

Python

Esempio di risposta

Descrizione dei campi

Interrogazione in batch (`retrieve_batch`)

Corpo della richiesta

Esempio CURL

Esempio di risposta

Esempio end-to-end: invio e polling

Note