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

# Integração e Uso da API de Tarefas OpenAI

> OpenAI generation API guide - Ace Data Cloud

A API de Tarefas OpenAI é usada para consultar os resultados de tarefas submetidas anteriormente ao interface de imagem da OpenAI em **modo de callback**. Quando você não pode esperar por uma resposta HTTP síncrona ou deseja consultar a tarefa novamente mais tarde, use esta interface.

No modo de callback, **a interface de imagem original retornará imediatamente um `task_id` após aceitar o pedido**. Você possui diretamente esse `task_id` e pode usá-lo para consultar esta interface quando necessário, sem precisar passar um `trace_id` personalizado (apenas se você desejar associar com um identificador de negócio próprio).

> As tarefas só serão persistidas se o pedido de imagem original incluir um `callback_url`. Pedidos feitos de forma síncrona (não em callback) não serão armazenados.

## Processo de Solicitação

A API de Tarefas OpenAI compartilha a autorização com os serviços existentes da OpenAI. Se você já solicitou a Geração de Imagens da OpenAI, pode usar diretamente o mesmo token para chamar esta interface, sem necessidade de solicitação adicional.

Novos usuários têm uma cota gratuita na primeira solicitação.

## Endereço da Interface

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

Ações suportadas:

| Ação | Descrição |
| - | - |
| `retrieve` | Consulta uma única tarefa pelo `id` ou `trace_id` |
| `retrieve_batch` | Consulta várias tarefas por `ids` / `trace_ids` / `application_id` / `user_id` |

## Cabeçalhos da Solicitação

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

## Consulta de Tarefa Única (`retrieve`)

### Corpo da Solicitação

| Campo | Tipo | Obrigatório | Descrição |
| - | - | - | - |
| `action` | string | Sim | Fixo como `retrieve` |
| `id` | string | Um dos dois | ID da tarefa retornado na resposta síncrona ao submeter o pedido de imagem (recomendado) |
| `trace_id` | string | Um dos dois | Apenas necessário se você explicitamente passou um `trace_id` personalizado na solicitação original |

É necessário passar pelo menos um dos campos `id` ou `trace_id`. Normalmente, você pode usar diretamente o `id` da resposta de submissão; o `trace_id` deve ser passado apenas se você desejar associar com um identificador de negócio próprio.

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

### Exemplo de Retorno

Quando a tarefa 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": "A cat sitting on a table",
    "size": "1024x1024",
    "callback_url": "https://your.server/callback"
  },
  "response": {
    "created": 1763142637,
    "data": [
      {
        "url": "https://platform.cdn.acedata.cloud/openai/...png"
      }
    ],
    "success": true
  }
}
```

Quando nenhuma tarefa é encontrada, retorna um objeto vazio:

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

### Descrição dos Campos

* `id`: ID da tarefa gerado quando o pedido de imagem original foi aceito.
* `trace_id`: Identificador de rastreamento personalizado passado na solicitação original, facilitando a associação com o negócio do cliente.
* `type`: Tipo de tarefa. Tarefas escritas na série `gpt-image` (como `gpt-image-2`) são `images`; `gpt-image-1`, nano-banana, etc., usam `images_generations` / `images_edits`, e algumas interfaces de chat são `chat_completions_image`.
* `request`: Corpo completo da solicitação original.
* `response`: Corpo da resposta final retornada quando o callback é concluído.
* `created_at` / `started_at` / `finished_at`: Timestamp Unix (segundos, ponto flutuante).
* `elapsed`: Tempo de execução (segundos, ponto flutuante).
* `application_id` / `user_id` / `credential_id`: ID do aplicativo, usuário final e credencial.

## Consulta em Lote (`retrieve_batch`)

### Corpo da Solicitação

| Campo | Tipo | Descrição |
| - | - | - |
| `action` | string | Fixo como `retrieve_batch` |
| `ids` | string\[] | Consulta por lista de IDs de tarefas |
| `trace_ids` | string\[] | Consulta por lista de `trace_id` |
| `application_id` | string | Consulta todas as tarefas por aplicativo |
| `user_id` | string | Consulta todas as tarefas por usuário final |
| `type` | string | Filtra por tipo de tarefa (valores: `images`, `images_generations`, `images_edits`) |
| `offset` | int | Ponto de partida da paginação, padrão `0` |
| `limit` | int | Número de itens por página, padrão `12` |
| `created_at_min` | float | Timestamp inicial (Unix segundos) |
| `created_at_max` | float | Timestamp final (Unix segundos) |

Você pode passar um dos campos `ids` / `trace_ids` / `application_id` / `user_id` ou a janela de tempo `created_at_*`.

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

### Exemplo de Retorno

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

## Exemplo de ponta a ponta: Submissão e Polling

A API de Tarefas serve principalmente para processos assíncronos no modo de callback. No modo de callback, a interface de submissão **retorna imediatamente um `task_id`** (ou seja, ID da tarefa), depois você só precisa usar esse `task_id` para fazer polling na interface de Tarefas, sem precisar gerar um `trace_id` por conta própria.

```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. Submeter tarefa de geração de imagem (modo de callback: inclua callback_url para retornar imediatamente o task_id)
submit = requests.post(
    f"{API}/openai/images/generations",
    headers=HEADERS,
    json={
        "model": "gpt-image-1",
        "prompt": "Um gato em estilo aquarela sentado na mesa",
        "callback_url": "https://webhook.site/your-uuid",
    },
).json()
print("submetido:", submit)

task_id = submit["task_id"]

# 2. Use diretamente o task_id da resposta da submissão para fazer polling na interface de Tarefas, até que a tarefa seja concluída
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("concluído:", task["response"])
        break
    time.sleep(3)
```

## Observações

* A interface de Tarefas **não gera custos**, você pode fazer polling à vontade. Apenas as solicitações de geração/edição de imagem originais serão cobradas.
* Apenas quando a solicitação original contém `callback_url`, a gravação da tarefa será feita; chamadas síncronas não gerarão tarefas consultáveis.
* Registros de tarefas que excederem o período de retenção da plataforma podem ser limpos.


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