OpenAI Tasks API 集成与使用指南

在 Ace Data Cloud 平台上，OpenAI Tasks API 允许你查询之前通过 OpenAI 图片接口提交的 回调模式（callback mode） 任务。当你无法等待同步 HTTP 响应完成，或者希望根据 id 或自定义 trace_id 在之后查找任务时，这个 API 非常有用。

注意：任务仅在原始图片请求使用 callback_url 时才会被服务器保存。同步调用（非回调）不会产生可查询任务。

简介

Ace Data Cloud 是一个集成了 OpenAI 模型和多种 AI 服务的云平台，支持图像生成、文本生成和智能应用开发。通过 Tasks API，你可以在异步处理场景下方便地追踪和获取任务结果，尤其适合：

生成大尺寸图像，避免同步请求超时。
后续查询历史任务结果，用于数据分析或日志管理。
批量管理应用或用户的生成任务。

平台链接：Ace Data Cloud 平台 | API 文档

环境准备

在开始之前，请确保你已经具备以下条件：

拥有 Ace Data Cloud 账户，并获取 API Key。
已开通 OpenAI 图片生成服务。
Python 3.x 环境，已安装 requests 库：

bash 复制代码

pip install requests

1. Tasks API 接口概览

接口地址：

复制代码

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

支持操作：

操作	功能
`retrieve`	查询单个任务（通过 `id` 或 `trace_id`）
`retrieve_batch`	批量查询任务（通过 `ids`、`trace_ids`、`application_id` 或 `user_id`）

请求头：

http 复制代码

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

2. 查询单个任务（retrieve）

请求体

字段	类型	必填	描述
`action`	string	是	固定为 `retrieve`
`id`	string	二选一	原始请求返回的任务 ID
`trace_id`	string	二选一	自定义追踪 ID，优先级高于 `id`

至少提供 id 或 trace_id 中的一个。

Python 示例

python 复制代码

import requests

url = "https://api.acedata.cloud/openai/tasks"
headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json",
}
payload = {
    "action": "retrieve",
    "trace_id": "my-custom-trace-001",
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())

返回示例

任务找到时：

json 复制代码

{
  "_id": "67a1b2c3d4e5f6a7b8c9d0e1",
  "id": "7489df4c-ef03-4de0-b598-e9a590793434",
  "trace_id": "my-custom-trace-001",
  "type": "images_generations",
  "application_id": "9dec7b2a-1cad-41ff-8536-d4ddaf2525d4",
  "user_id": "5d8e7f6a-1234-4abc-9def-0123456789ab",
  "request": { "model": "gpt-image-1", "prompt": "A cat sitting on a table" },
  "response": { "data": [{ "url": "https://platform.cdn.acedata.cloud/openai/...png" }], "success": true },
  "created_at": 1763142607.967,
  "finished_at": 1763142637.404,
  "duration": 29.437
}

若未找到匹配任务，返回空对象 {}。

3. 批量查询任务（retrieve_batch）

请求体示例

字段	类型	描述
`action`	string	固定为 `retrieve_batch`
`ids`	string[]	按任务 ID 查询
`trace_ids`	string[]	按自定义追踪 ID 查询
`application_id`	string	查询应用下所有任务
`user_id`	string	查询用户下所有任务
`type`	string	筛选上游类型（如 `images_generations`）
`offset`	int	分页起始（默认 0）
`limit`	int	分页大小（默认 12）
`created_at_min` / `created_at_max`	float	按创建时间筛选

注意：只需提供 ids、trace_ids、application_id、user_id 或时间窗口中的一个。

CURL 示例

bash 复制代码

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

4. 提交任务并轮询结果示例

python 复制代码

import os, time, uuid, requests

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

# 1. 提交带 callback_url 的图片生成任务
trace_id = str(uuid.uuid4())
submit = requests.post(
    f"{API}/openai/images/generations",
    headers=HEADERS,
    json={
        "model": "gpt-image-1",
        "prompt": "a watercolor cat sitting on a desk",
        "callback_url": "https://webhook.site/your-uuid",
        "trace_id": trace_id,
    },
).json()
print("submitted:", submit)

# 2. 轮询任务状态直到完成
while True:
    task = requests.post(
        f"{API}/openai/tasks",
        headers=HEADERS,
        json={"action": "retrieve", "trace_id": trace_id},
    ).json()
    if task and task.get("response"):
        print("finished:", task["response"])
        break
    time.sleep(3)

常见问题

是否会额外收费？
查询 Tasks API 请求免费，只有原始图片生成/编辑请求会计费。
为什么找不到任务？
任务仅在提交请求时包含 callback_url 才会生成。同步请求不会产生任务。
任务记录会永久保存吗？
平台有任务保留期，超过时间的记录可能被清理。

总结

通过 OpenAI Tasks API，你可以方便地在异步场景下管理和获取图像生成或编辑任务结果，支持单任务查询和批量查询。结合 Ace Data Cloud 平台的回调模式，可以轻松实现自动化处理与任务追踪。

技术标签

#OpenAI #AceDataCloud #API #Python教程 #异步任务管理