오픈AI Decisions API 사용법: 분류와 라우팅을 빠르게 처리하는 판단 전용 API

오픈AI 코덱스 팀의 티보 소티오(Tibo Sottiaux)가 10월 6일 X에 "Decisions API가 공개됐다, 실시간 범용 분류기가 좋은 가능성을 연다"고 썼습니다. 같은 날 오픈AI 개발자 계정은 "앱이 적합한 모델, 도구, 행동을 거의 실시간으로 고르게 하라"며 이 API를 모든 개발자에게 퍼블릭 베타로 열었다고 알렸습니다.

Decisions API는 9월 29일 데브데이 2026에서 제한 프리뷰로 처음 소개됐습니다. 일주일 만에 누구나 호출할 수 있게 된 것입니다. 이 글은 10월 7일 기준 공식 문서와 API 레퍼런스를 바탕으로 이 API가 무엇을 돌려주는지, 어떻게 호출하는지, 언제 기존 방식 대신 쓰면 되는지 설명합니다.

글을 쓰지 않고 판단만 돌려주는 API

일반적인 언어 모델 API는 질문을 받으면 답을 문장으로 생성합니다. 고객 문의를 "결제, 기술 지원, 배송" 중 하나로 분류하고 싶을 때도 모델이 "결제"라는 답을 토큰 단위로 생성하는 과정을 거칩니다. 토큰은 모델이 글을 나눠 처리하는 단위입니다. 출력 형식을 JSON으로 고정하는 Structured Outputs를 써도 생성 단계 자체는 남습니다.

Decisions API는 이 생성 단계를 없앴습니다. 텍스트나 이미지를 넣고 미리 정의한 질문을 보내면 조건이 참일 확률, 정해 둔 선택지 중 하나, 단계별 점수 가운데 하나를 숫자와 값으로 돌려줍니다. 오픈AI 문서는 Responses API보다 약 10배 빠르다고 설명합니다. 데브데이 발표 영상에서는 고객 요청 1만 건을 세 부서로 나누는 작업을 Decisions는 150ms, Responses API는 1.6초로 표시한 비교 장면이 나왔다고 보도됐습니다. 이 수치는 발표용 데모 조건이며 지연 시간 분포나 보장 수준은 공개되지 않았습니다.

티보가 "실시간 범용 분류기"라고 부른 것도 이 속도 때문으로 보입니다. 분류 모델을 따로 학습시키지 않고 질문과 선택지를 자연어로 적기만 해도, 화면 응답이나 에이전트 동작 중간에 끼워 넣을 수 있는 속도로 판단을 받는다는 뜻입니다.

질문 세 종류: predicate, choice, score

요청은 세 부분으로 구성됩니다. model에는 현재 유일하게 지원하는 gpt-6-luna를 적고, input에는 판단할 텍스트나 이미지를, questions에는 판단할 내용을 넣습니다. 질문은 아래 세 종류 중에서 고릅니다.

score는 계산 방식을 알아 두어야 값을 해석할 수 있습니다. 공식 문서의 예에서 "외관 문제(0), 우회 방법 있음(1), 완전히 막힘(2)" 세 단계의 확률이 0.1, 0.7, 0.2로 나오면 score는 0×0.1 + 1×0.7 + 2×0.2 = 1.1입니다. 단계 하나를 골라 주는 것이 아니라 분포를 숫자 하나로 요약한 값이므로 단계 사이 값이 나옵니다. 범주 하나만 정해야 한다면 choice를 씁니다.

서로 관계없는 질문 여러 개는 한 요청에 함께 넣을 수 있습니다. 상품 사진 한 장으로 파손 여부(predicate)와 상품 종류(choice)를 동시에 묻는 식입니다. 앞 질문의 답에 따라 다음 질문이 달라진다면 요청을 나눠 보내야 합니다. 모델이 답하기 어려운 질문은 그 질문만 refusal로 돌아오고 나머지 질문은 정상적으로 답합니다.

첫 요청: 고객 문의를 부서로 나누기

오픈AI의 Python SDK는 10월 6일 배포된 3.26.0 버전부터 client.decisions.create 메서드를 지원합니다. 아래는 한국어 문의를 결제, 기술 지원, 배송, 기타로 나누는 예시입니다. 공식 문서의 영어 예제를 한국어 문의로 바꿔 작성했고, 이 글을 쓰면서 직접 호출해 보지는 않았습니다.

응답의 answers 배열에는 질문마다 하나씩 답이 들어 있습니다. 질문에 붙인 name이 그대로 돌아오므로 여러 질문을 넣어도 어느 답인지 구분할 수 있습니다. 같은 구조의 영어 문의로 공식 문서가 보여 준 응답 예시는 다음과 같습니다.

질문이 거부되어 refusal이 돌아오는 경우를 빼면 choice에는 내가 정한 값 중 하나만 들어오므로, 응답을 처리하는 코드가 단순해집니다. 실무에서 쓸 때는 두 가지를 같이 정합니다.

1. 기타 선택지를 넣습니다. 문서는 범주가 모든 입력을 덮지 못할 때 other 같은 선택지를 두고, 그 결과를 사람이 보는 대기열로 보내라고 안내합니다.
2. 확신 기준을 내 자료로 정합니다. 예를 들어 confidence가 일정 값보다 낮으면 사람이 검토하게 하는 식입니다. 그 기준값은 공식 권장치가 없고, 실제 문의에 정답을 붙인 자료로 시험해 잘못 보냈을 때와 놓쳤을 때의 비용을 따져 정하라는 것이 문서의 안내입니다.

API를 바로 호출하기 전에 Decisions 플레이그라운드에서 질문과 입력을 바꿔 가며 결과를 먼저 볼 수도 있습니다.

이미지를 넣을 때의 조건

입력에는 텍스트와 이미지를 함께 넣을 수 있습니다. 공식 문서의 예는 상품 사진을 넣고 "그림자와 포장 손상은 무시하고, 상품에 금이나 찢어짐, 찌그러짐이 보이는지"를 predicate로 묻습니다. 돌아온 확률이 기준보다 높은 사진만 검토 대상으로 표시하는 방식입니다.

이미지는 base64로 인코딩한 데이터 URL로만 넣을 수 있습니다. 웹에 올린 이미지 주소나 오픈AI에 업로드한 파일 ID는 받지 않습니다. 한 요청에 최대 128장까지 넣을 수 있고, 메시지 역할은 user만 지원합니다. 오디오와 파일 입력, 도구 호출도 지원하지 않습니다.

가격과 기존 방식과의 차이

요금은 입력 토큰에만 붙습니다. gpt-6-luna로 Decisions를 호출하면 입력 100만 토큰당 0.10달러이고, 출력 토큰과 캐시 읽기, 쓰기 요금은 없습니다. 같은 Luna를 Responses API로 부르면 입력 0.10달러에 출력 100만 토큰당 0.50달러가 더해집니다. 지역 처리 할증과 긴 입력 배수는 그대로 적용됩니다.

문의 한 건과 질문, 선택지 설명을 합쳐 300토큰이라고 가정하면 1만 건은 300만 토큰이고 요금은 약 0.30달러입니다. 질문 지시문과 선택지 설명도 요청에 함께 들어가므로 입력 토큰에 포함된다고 보고 계산했습니다. 실제 토큰 수는 응답의 usage로 확인합니다.

기존에도 작은 모델에 Structured Outputs로 선택지를 고정하면 같은 분류를 할 수 있었습니다. 오픈AI 문서는 두 방식을 이렇게 나눕니다.

Decisions가 더해 주는 것은 생성 단계가 없는 속도, 기본으로 붙는 선택지별 확률, 출력 요금이 없는 가격 구조입니다. 반대로 왜 그렇게 판단했는지 설명을 받거나 입력에서 값을 뽑아내야 한다면 Decisions로는 할 수 없습니다.

데이터 보관 측면에서는 자격을 갖춘 고객에게 데이터 미보관(ZDR)과 HIPAA 용도를 지원하고, 데이터 저장과 처리 지역으로 미국과 유럽을 선택할 수 있다고 문서에 적혀 있습니다.

퍼블릭 베타에서 확인할 한계

오픈AI는 몇 주 안에 정식 버전으로 전환할 계획이라고 밝혔습니다. 그 전까지 알고 써야 할 조건이 있습니다.

• 모델이 하나뿐입니다. 지금은 gpt-6-luna만 쓸 수 있습니다. 판단 전용으로 따로 학습한 모델인지는 공개되지 않았습니다.
• Decisions 전용 사용량 한도가 공개되지 않았습니다. Luna 모델 페이지의 등급별 한도가 같이 적용되는지는 문서에 없습니다. 같은 모델 페이지의 지원 엔드포인트 목록에도 아직 Decisions가 빠져 있어 문서끼리 맞지 않는 상태입니다.
• 정확도와 확신값의 신뢰도가 공개되지 않았습니다. confidence가 0.9일 때 실제로 90% 맞는지는 알 수 없으므로 앞에서 말한 대로 내 자료로 확인해야 합니다.

공개 직후 나온 외부 비교도 아직 소규모입니다. 오픈AI 개발자 커뮤니티의 한 사용자는 9월 15일 먼저 출시된 TypeSafe의 판단 전용 모델 Jev와 수백 문항 규모로 비교해, 판단이 미묘한 질문에서 Jev가 더 정확했고 Luna의 지연 중앙값은 1.6초였다고 적었습니다. 공식 문서의 10배 수치와는 측정 조건이 다르고 표본도 작아서 어느 쪽이 맞다고 결론 내릴 자료는 아닙니다. 응답 속도가 중요한 서비스라면 내 환경에서 직접 측정하는 편이 확실합니다.

Decisions API가 맞는 작업

정리하면 Decisions API는 다음 조건이 겹칠 때 먼저 검토할 만합니다.

• 답이 미리 정할 수 있는 선택지나 단계 안에 있습니다.
• 처리할 건수가 많아 출력 요금과 처리 시간이 부담됩니다.
• 사용자가 기다리는 화면이나 에이전트의 다음 행동 결정처럼 응답 속도가 중요합니다.

반대로 설명이 필요하거나, 입력에서 값을 뽑아야 하거나, 앞 판단에 따라 질문이 계속 바뀌는 작업은 기존 Responses API가 맞습니다.

처음 도입한다면 실제 문의나 사진 100건 정도에 정답을 붙이고, 플레이그라운드에서 질문 문구와 선택지 설명을 다듬은 뒤, 같은 자료로 정확도와 confidence 기준값을 정하는 순서로 시작합니다. 기존에 Structured Outputs로 분류하고 있었다면 같은 100건을 두 방식으로 돌려 정확도, 응답 시간, 비용을 나란히 비교한 결과로 전환 여부를 판단합니다.