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

# OpenAI Tasks API 접속 및 사용

> OpenAI generation API guide - Ace Data Cloud

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` 중 하나는 반드시 전달해야 합니다. 일반적으로 제출 응답에서 `id`를 직접 사용하면 되며, `trace_id`는 사용자 정의 비즈니스 식별자로 연관짓고 싶을 때만 전달합니다.

### 코드 예시

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

### 반환 예시

작업이 존재할 때:

```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
  }
}
```

일치하는 작업이 없을 때 빈 객체 반환:

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

### 필드 설명

* `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 | 페이지당 항목 수, 기본값 `12` |
| `created_at_min` | float | 시작 타임스탬프 (Unix 초) |
| `created_at_max` | float | 종료 타임스탬프 (Unix 초) |

`ids` / `trace_ids` / `application_id` / `user_id` 또는 `created_at_*` 시간 창 중 하나를 전달하면 됩니다.

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

### 반환 예시

```json theme={null}
{
  "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`를 직접 생성할 필요가 없습니다.

```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. 이미지 생성 작업 제출(콜백 모드: 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("제출됨:", 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("완료됨:", task["response"])
        break
    time.sleep(3)
```

## 주의 사항

* Tasks 인터페이스 자체는 **요금이 부과되지 않으므로** 안심하고 폴링할 수 있습니다. 원본 이미지 생성/편집 요청만 요금이 부과됩니다.
* 원본 요청에 `callback_url`이 포함된 경우에만 작업 기록이 작성됩니다; 동기 호출은 조회 가능한 작업을 생성하지 않습니다.
* 플랫폼 보존 기간을 초과한 작업 기록은 삭제될 수 있습니다.


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