OpenAI Tasks API 接続と使用

OpenAI Tasks API は、以前に コールバックモード で OpenAI 画像インターフェースに送信されたタスクの結果を照会するために使用されます。同期 HTTP 応答を待つことができない場合や、後でタスクを再度照会したい場合は、このインターフェースを使用してください。コールバックモードでは、元の画像インターフェースはリクエストを受理した後、すぐに task_id を返します。この task_id を直接保持し、必要に応じてこのインターフェースで照会することができます。カスタム trace_id を追加で渡す必要はありません（自社のビジネス識別子で関連付けたい場合のみ必要です）。

元の画像リクエストに callback_url が含まれている場合にのみ、タスクは永続化されます。同期（非コールバック）方式で呼び出されたリクエストは保存されません。

申請プロセス

OpenAI Tasks API は、既存の OpenAI サービスと共通の認証を使用します。すでに OpenAI Images Generations を申請している場合は、追加の申請なしで同じトークンを使用してこのインターフェースを呼び出すことができます。新しいユーザーは初回申請時に無料枠があります。

インターフェースアドレス

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

サポートされている action：

操作	説明
`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 のいずれかを少なくとも1つ渡す必要があります。一般的には、提出応答内の 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",
    "id": "7489df4c-ef03-4de0-b598-e9a590793434",
}
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",
  "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
  }
}

一致するタスクが見つからない場合は空のオブジェクトを返します：

{}

フィールド説明

id：元の画像リクエスト受理時に生成されたタスク ID。
trace_id：元のリクエストで渡されたカスタム追跡識別子、クライアントビジネスの関連付けに便利。
type：タスクの種類。gpt-image シリーズ（例：gpt-image-2）で書き込まれたタスクは images；gpt-image-1、nano-banana などは images_generations / images_edits、一部のチャットインターフェースは chat_completions_image。
request：元のリクエストの完全なリクエストボディ。
response：コールバック完了時に返される最終応答ボディ。
created_at / started_at / finished_at：Unix タイムスタンプ（秒、浮動小数点）。
elapsed：実行時間（秒、浮動小数点）。
application_id / user_id / credential_id：所属アプリ、エンドユーザー、資格情報 ID。

バッチ照会（`retrieve_batch`）

リクエストボディ

フィールド	タイプ	説明
`action`	string	固定で `retrieve_batch`
`ids`	string[]	タスク ID リストで照会
`trace_ids`	string[]	`trace_id` リストで照会
`application_id`	string	アプリケーションで全タスクを照会
`user_id`	string	エンドユーザーで全タスクを照会
`type`	string	タスクタイプでフィルタリング（値：`images`、`images_generations`、`images_edits`）
`offset`	int	ページ開始点、デフォルト `0`
`limit`	int	1ページあたりの件数、デフォルト `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",
      "request": {
        "model": "gpt-image-2",
        "prompt": "猫"
      },
      "response": {
        "data": [
          {
            "url": "https://...png"
          }
        ]
      },
      "created_at": 1763142607.967,
      "started_at": 1763142608.027,
      "finished_at": 1763142637.404,
      "elapsed": 29.377
    }
  ],
  "count": 1
}

エンドツーエンドの例：提出とポーリング

Tasks API は主にコールバックモードでの非同期プロセスにサービスを提供します。コールバックモードでは、提出インターフェースが即座に task_id（すなわちタスクID）を返します。その後は、この task_id を使って Tasks インターフェースをポーリングするだけで、trace_id を自分で生成する必要はありません。

import os, time, requests

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

# 1. 画像生成タスクを提出する（コールバックモード：callback_url を付けると即座に task_id が返される）
submit = requests.post(
    f"{API}/openai/images/generations",
    headers=HEADERS,
    json={
        "model": "gpt-image-1",
        "prompt": "水彩風の猫がテーブルの上に座っている",
        "callback_url": "https://webhook.site/your-uuid",
    },
).json()
print("submitted:", submit)

task_id = submit["task_id"]

# 2. 提出応答の task_id を使って Tasks インターフェースをポーリングし、タスクが完了するまで待つ
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("finished:", task["response"])
        break
    time.sleep(3)

注意事項

Tasks インターフェース自体は課金されませんので、安心してポーリングできます。元の画像生成/編集リクエストのみが課金されます。
元のリクエストに callback_url が含まれている場合のみ、タスク記録が書き込まれます；同期呼び出しはクエリ可能なタスクを生成しません。
プラットフォームの保持期間を超えたタスク記録は削除される可能性があります。

はじめに

AIチャット

AI画像

AI動画

AIオーディオ

ウェブ＆データ

CAPTCHA

アイデンティティ

Coding

その他のガイド

OpenAI Tasks API 接続と使用

申請プロセス

インターフェースアドレス

リクエストヘッダー

単一タスク照会（`retrieve`）

リクエストボディ

コード例

CURL

Python

返却例

フィールド説明

バッチ照会（`retrieve_batch`）

リクエストボディ

CURL 例

返却例

エンドツーエンドの例：提出とポーリング

注意事項

​申請プロセス

​インターフェースアドレス

​リクエストヘッダー

​単一タスク照会（retrieve）

​リクエストボディ

​コード例

​CURL

​Python

​返却例

​フィールド説明

​バッチ照会（retrieve_batch）

​リクエストボディ

​CURL 例

​返却例

​エンドツーエンドの例：提出とポーリング

​注意事項

申請プロセス

インターフェースアドレス

リクエストヘッダー

単一タスク照会（`retrieve`）

リクエストボディ

コード例

CURL

Python

返却例

フィールド説明

バッチ照会（`retrieve_batch`）

リクエストボディ

CURL 例

返却例

エンドツーエンドの例：提出とポーリング

注意事項