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

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

> OpenAI generation API guide - Ace Data Cloud

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

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

### Ejemplo de Respuesta

Cuando la tarea 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 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:

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

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

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

### Ejemplo de Respuesta

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

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


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