Integración y uso de la API de Tareas de OpenAI

La API de Tareas de OpenAI se utiliza para consultar los resultados de tareas enviadas anteriormente al interfaz de imágenes de OpenAI en modo de callback. Cuando no puede esperar una respuesta HTTP sincrónica, o desea consultar la tarea nuevamente más tarde, utilice esta interfaz. En modo de callback, la interfaz de imágenes original devolverá inmediatamente un task_id después de aceptar la solicitud. Usted posee directamente este task_id y puede usarlo para consultar esta interfaz cuando lo necesite, sin necesidad de pasar un trace_id personalizado (solo es necesario si desea asociarlo con un identificador de negocio propio).

La tarea solo se persistirá si la solicitud de imagen original incluye un callback_url. Las solicitudes realizadas de manera sincrónica (no en modo de callback) no se almacenarán.

Proceso de Solicitud

La API de Tareas de OpenAI comparte la autorización con los servicios existentes de OpenAI. Si ya ha solicitado Generaciones de Imágenes de OpenAI, puede utilizar el mismo token para llamar a esta interfaz, sin necesidad de solicitar uno adicional. Los nuevos usuarios tienen un límite gratuito en su primera solicitud.

Dirección de la Interfaz

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

Acciones soportadas:

Operación	Descripción
`retrieve`	Consultar una tarea individual mediante `id` o `trace_id`
`retrieve_batch`	Consultar múltiples tareas mediante `ids` / `trace_ids` / `application_id` / `user_id`

Encabezados de Solicitud

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

Consulta de Tarea Única (`retrieve`)

Cuerpo de Solicitud

Campo	Tipo	Requerido	Descripción
`action`	string	Sí	Fijo como `retrieve`
`id`	string	Opcional	ID de tarea devuelto en la respuesta sincrónica de la solicitud de imagen (se recomienda usar)
`trace_id`	string	Opcional	Solo se necesita si ha pasado explícitamente un `trace_id` personalizado en la solicitud original

Se debe proporcionar al menos uno de id o trace_id. En general, se puede usar directamente el id de la respuesta de la solicitud, y trace_id solo se debe pasar si desea asociarlo con un identificador de negocio personalizado.

Ejemplo de Código

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

Ejemplo de Respuesta

Cuando la tarea 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 gato sentado en una mesa",
    "size": "1024x1024",
    "callback_url": "https://your.server/callback"
  },
  "response": {
    "created": 1763142637,
    "data": [
      {
        "url": "https://platform.cdn.acedata.cloud/openai/...png"
      }
    ],
    "success": true
  }
}

Cuando no se encuentra ninguna tarea, se devuelve un objeto vacío:

{}

Descripción de Campos

id: ID de tarea generado al aceptar la solicitud de imagen original.
trace_id: Identificador de seguimiento personalizado pasado en la solicitud original, útil para asociar con el negocio del cliente.
type: Tipo de tarea. Las tareas escritas en la serie gpt-image (como gpt-image-2) son images; gpt-image-1, nano-banana, etc., utilizan images_generations / images_edits, y algunas interfaces de chat son chat_completions_image.
request: Cuerpo completo de la solicitud original.
response: Cuerpo de respuesta final devuelto al completar el callback.
created_at / started_at / finished_at: Marca de tiempo Unix (segundos, flotante).
elapsed: Tiempo de ejecución (segundos, flotante).
application_id / user_id / credential_id: ID de la aplicación, usuario final y credencial.

Consulta por Lotes (`retrieve_batch`)

Cuerpo de Solicitud

Campo	Tipo	Descripción
`action`	string	Fijo como `retrieve_batch`
`ids`	string[]	Consultar por lista de IDs de tarea
`trace_ids`	string[]	Consultar por lista de `trace_id`
`application_id`	string	Consultar todas las tareas por aplicación
`user_id`	string	Consultar todas las tareas por usuario final
`type`	string	Filtrar por tipo de tarea (valores: `images`, `images_generations`, `images_edits`)
`offset`	int	Punto de inicio de paginación, por defecto `0`
`limit`	int	Número de elementos por página, por defecto `12`
`created_at_min`	float	Marca de tiempo de inicio (segundos Unix)
`created_at_max`	float	Marca de tiempo de finalización (segundos Unix)

Se debe proporcionar al menos uno de ids / trace_ids / application_id / user_id o el rango de tiempo created_at_*.

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

Ejemplo de Respuesta

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

Ejemplo de extremo a extremo: enviar y sondear

La API de Tasks sirve principalmente para procesos asíncronos en modo de callback. En modo de callback, la interfaz de envío devuelve inmediatamente un task_id (es decir, ID de tarea), después solo necesita usar este task_id para sondear la interfaz de Tasks, sin necesidad de generar un trace_id por su cuenta.

import os, time, requests

API = "https://api.acedata.cloud"
HEADERS = {
    "authorization": f"Bearer {os.environ['ACEDATA_API_KEY']}",
    "content-type": "application/json",
}

# 1. Enviar tarea de generación de imagen (modo callback: solo necesita incluir callback_url para devolver inmediatamente task_id)
submit = requests.post(
    f"{API}/openai/images/generations",
    headers=HEADERS,
    json={
        "model": "gpt-image-1",
        "prompt": "Un gato en estilo acuarela sentado en una mesa",
        "callback_url": "https://webhook.site/your-uuid",
    },
).json()
print("enviado:", submit)

task_id = submit["task_id"]

# 2. Usar directamente el task_id de la respuesta de envío para sondear la interfaz de Tasks, hasta que la tarea esté completa
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("terminado:", task["response"])
        break
    time.sleep(3)

Consideraciones

La interfaz de Tasks no genera costos, puede sondear sin preocupaciones. Solo las solicitudes originales de generación/edición de imágenes incurrirán en costos.
Solo cuando la solicitud original incluya callback_url, se registrará la tarea; las llamadas sincrónicas no generarán tareas consultables.
Los registros de tareas que superen el período de retención de la plataforma pueden ser eliminados.

Primeros pasos

Chat de IA

Imagen de IA

Video de IA

Audio de IA

Web y datos

CAPTCHA

Identidad

Coding

Más guías

Integración y uso de la API de Tareas de OpenAI

Proceso de Solicitud

Dirección de la Interfaz

Encabezados de Solicitud

Consulta de Tarea Única (`retrieve`)

Cuerpo de Solicitud

Ejemplo de Código

CURL

Python

Ejemplo de Respuesta

Descripción de Campos

Consulta por Lotes (`retrieve_batch`)

Cuerpo de Solicitud

Ejemplo de CURL

Ejemplo de Respuesta

Ejemplo de extremo a extremo: enviar y sondear

Consideraciones

​Proceso de Solicitud

​Dirección de la Interfaz

​Encabezados de Solicitud

​Consulta de Tarea Única (retrieve)

​Cuerpo de Solicitud

​Ejemplo de Código

​CURL

​Python

​Ejemplo de Respuesta

​Descripción de Campos

​Consulta por Lotes (retrieve_batch)

​Cuerpo de Solicitud

​Ejemplo de CURL

​Ejemplo de Respuesta

​Ejemplo de extremo a extremo: enviar y sondear

​Consideraciones

Proceso de Solicitud

Dirección de la Interfaz

Encabezados de Solicitud

Consulta de Tarea Única (`retrieve`)

Cuerpo de Solicitud

Ejemplo de Código

CURL

Python

Ejemplo de Respuesta

Descripción de Campos

Consulta por Lotes (`retrieve_batch`)

Cuerpo de Solicitud

Ejemplo de CURL

Ejemplo de Respuesta

Ejemplo de extremo a extremo: enviar y sondear

Consideraciones