Skip to main content
OpenAI Tasks API는 이전에 콜백 모드로 OpenAI 이미지 인터페이스에 제출된 작업 결과를 조회하는 데 사용됩니다. 동기 HTTP 응답을 기다릴 수 없거나, 나중에 작업을 다시 조회하고 싶을 때 이 인터페이스를 사용하세요. 콜백 모드에서는 원본 이미지 인터페이스가 요청을 수락한 후 즉시 task_id를 반환합니다. 이 task_id를 직접 보유하고 필요할 때 이 인터페이스를 통해 조회하면 되며, 추가로 사용자 정의 trace_id를 전달할 필요는 없습니다(자신의 비즈니스 식별자로 연관짓고 싶을 때만 필요합니다).
원본 이미지 요청에 callback_url이 포함된 경우에만 작업이 지속화됩니다. 동기(비콜백) 방식으로 호출된 요청은 저장되지 않습니다.

신청 프로세스

OpenAI Tasks API는 기존 OpenAI 서비스와 권한을 공유합니다. 이미 OpenAI Images Generations를 신청한 경우, 동일한 토큰을 사용하여 이 인터페이스를 호출할 수 있으며, 추가로 신청할 필요가 없습니다. 신규 사용자는 첫 신청 시 무료 한도가 있습니다.

인터페이스 주소

지원하는 action:

요청 헤더

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

단일 작업 조회 (retrieve)

요청 본문

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

코드 예시

CURL

Python

반환 예시

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

필드 설명

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

요청 본문

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

CURL 예시

반환 예시

엔드 투 엔드 예제: 제출 및 폴링

Tasks API는 주로 콜백 모드에서 비동기 프로세스를 지원합니다. 콜백 모드에서는 제출 인터페이스가 즉시 task_id(즉, 작업 ID)를 동기적으로 반환하며, 이후에는 이 task_id를 사용하여 Tasks 인터페이스를 폴링하면 됩니다. trace_id를 직접 생성할 필요가 없습니다.

주의 사항

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