Integração e Uso da API de Tarefas OpenAI

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

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

Exemplo de Retorno

Quando a tarefa 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": "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:

{}

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

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

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

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.

Primeiros passos

Chat AI

Imagem AI

Vídeo AI

Áudio AI

Web e Dados

CAPTCHA

Identidade

Coding

Mais guias

Integração e Uso da API de Tarefas OpenAI

Processo de Solicitação

Endereço da Interface

Cabeçalhos da Solicitação

Consulta de Tarefa Única (`retrieve`)

Corpo da Solicitação

Exemplo de Código

CURL

Python

Exemplo de Retorno

Descrição dos Campos

Consulta em Lote (`retrieve_batch`)

Corpo da Solicitação

Exemplo CURL

Exemplo de Retorno

Exemplo de ponta a ponta: Submissão e Polling

Observações

​Processo de Solicitação

​Endereço da Interface

​Cabeçalhos da Solicitação

​Consulta de Tarefa Única (retrieve)

​Corpo da Solicitação

​Exemplo de Código

​CURL

​Python

​Exemplo de Retorno

​Descrição dos Campos

​Consulta em Lote (retrieve_batch)

​Corpo da Solicitação

​Exemplo CURL

​Exemplo de Retorno

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

​Observações

Processo de Solicitação

Endereço da Interface

Cabeçalhos da Solicitação

Consulta de Tarefa Única (`retrieve`)

Corpo da Solicitação

Exemplo de Código

CURL

Python

Exemplo de Retorno

Descrição dos Campos

Consulta em Lote (`retrieve_batch`)

Corpo da Solicitação

Exemplo CURL

Exemplo de Retorno

Exemplo de ponta a ponta: Submissão e Polling

Observações