OpenAI Tasks API 的集成与使用

在现代应用中，图像生成和编辑任务的处理变得尤为重要。OpenAI Tasks API 允许开发者在回调模式 下查询先前提交的图像任务。当你无法等待同步 HTTP 响应，或希望稍后通过 id 或自定义的 trace_id 查找任务时，Tasks API 是一个理想的选择。

任务仅在原始图像请求中包含 callback_url 时被持久化到服务器。非回调的同步调用不会被存储。

应用流程

OpenAI Tasks API 已与现有的 OpenAI 服务捆绑在一起。如果你已经访问了 OpenAI Images Generations，那么可以使用相同的授权令牌调用此端点，无需额外的申请。

首次使用的用户可以享受免费配额，允许你免费使用此 API。

端点

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

请求体支持的操作：

操作	目的
retrieve	通过 id 或 trace_id 查询单个任务
retrieve_batch	通过 ids、trace_ids、application_id 或 user_id 列出多个任务

请求头

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

单任务查询 (retrieve)

请求体

字段	类型	必填	描述
action	string	是	必须为 retrieve
id	string	任选其一	原始图像请求返回的任务 ID
trace_id	string	任选其一	你在原始请求中提供的自定义 trace ID

至少需要提供 id 或 trace_id 中的一个。若同时提供，则以 trace_id 为主。

代码示例

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",
    "trace_id": "my-custom-trace-001",
}
response = requests.post(url, json=payload, headers=headers)
print(response.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",
  "credential_id": "68253cc8-505d-47f4-97ad-0050a62e4975",
  "created_at": 1763142607.967,
  "finished_at": 1763142637.404,
  "duration": 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
  }
}

如果没有匹配的任务，API 将返回一个空对象：

{}

批量查询 (retrieve_batch)

请求体

字段	类型	描述
action	string	必须为 retrieve_batch
ids	string\[\]	通过任务 ID 列出任务
trace_ids	string\[\]	通过自定义 trace ID 列出任务
application_id	string	列出应用的所有任务
user_id	string	列出最终用户的所有任务
type	string	按上游类型过滤 (images_generations, images_edits, ...)
offset	int	分页偏移（默认 0）
limit	int	页面大小（默认 12）
created_at_min	float	最早创建时间戳（Unix秒）
created_at_max	float	最新创建时间戳（Unix秒）

你需要提供 一个 : ids、trace_ids、application_id、user_id，或一个 created_at_* 时间窗口。

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

响应示例

{
  "items": [
    {
      "_id": "67a1b2c3d4e5f6a7b8c9d0e1",
      "id": "7489df4c-ef03-4de0-b598-e9a590793434",
      "trace_id": "my-trace-001",
      "type": "images_generations",
      "request": { "model": "gpt-image-1", "prompt": "A cat" },
      "response": { "data": [{ "url": "https://...png" }] },
      "created_at": 1763142607.967,
      "finished_at": 1763142637.404
    }
  ],
  "count": 1
}

完整示例：提交并轮询

Tasks API 在回调模式下最为实用。以下是完整的流程示例：

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
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. 轮询 Tasks API 直到任务完成
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
• API 文档
• 认证接口

技术标签：#OpenAI #API #