Blog

OpenAI Decisions API 사용법

OpenAI Decisions API 사용 방법: curl, Python, JavaScript를 통한 첫 호출, 술어, 선택 및 점수 답변, 이미지 입력, 그리고 Apidog 테스트.

Ashley Innocent

Ashley Innocent

10 October 2026

OpenAI Decisions API 사용법

Apidog 엔터프라이즈

온프레미스 배포

SSO & RBAC

SOC 2 준수

Apidog Enterprise 살펴보기

OpenAI Decisions API를 사용하려면, https://api.openai.com/v1/decisions로 POST 요청을 보내십시오. 이때 "model": "gpt-6-luna", input (텍스트, 이미지 또는 둘 다), 그리고 각 질문이 predicate, choice, score 중 하나인 questions 배열을 포함해야 합니다. 파싱할 텍스트 대신 확률을 포함한 유형화된 답변을 받게 되며, 출력, 캐시 읽기 또는 캐시 쓰기 요금 없이 1백만 입력 토큰당 0.10달러를 지불합니다. 이 엔드포인트는 2026년 10월 6일부로 공개 베타 상태입니다.

이 가이드에서는 키 발급, curl, Python 및 JavaScript를 사용한 첫 호출, 각 답변 유형 읽기, 하나의 지원 티켓에 대한 세 가지 질문, 이미지 입력, 임계값, 그리고 Apidog에서의 테스트 설정에 대해 다룹니다. 이 엔드포인트를 언제 선택해야 하는지에 대한 내용은 OpenAI Decisions API란 무엇인가에서 시작하세요.

button

Decisions API 요청 한눈에 보기

필드 설명
model gpt-6-luna (베타 버전에서 사용 가능한 유일한 모델)
input 문자열, 또는 content가 문자열이거나 input_text 및 input_image 유형의 부분으로 구성된 user 메시지 배열
questions[].type predicate, choice, 또는 score
questions[].instructions 필수; 일반 언어로 된 질문
questions[].name 선택 사항; 답변에서 에코백됨 (생략 시 null)
questions[].choices choice 전용; 2개에서 255개의 고유한 {value, description} 객체, value는 문자열 또는 부울
questions[].levels score 전용; 정렬된 {label, description} 객체, 가장 낮은 값부터 시작하며 인덱스는 0부터
safety_identifier 선택 사항인 불투명한 최종 사용자 ID, 최대 128자

출처: Decisions API 참조. 이 엔드포인트에는 temperature, stream, tools 또는 text.format이 없습니다.

키 발급 및 첫 호출

OpenAI 대시보드에서 키를 생성하고 (OpenAI API 키 가이드 참조), OPENAI_API_KEY로 내보내고, 절대로 코드에 붙여넣지 마십시오. 그런 다음 예/아니오 질문을 하나 던지십시오:

curl https://api.openai.com/v1/decisions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6-luna",
    "input": "The box arrived crushed and the screen is cracked.",
    "questions": [
      {"type": "predicate", "name": "damaged",
       "instructions": "Does the customer report a damaged item?"}
    ]
  }'

응답은 세 가지 최상위 필드인 model, answers, usage를 포함합니다. 이는 OpenAI 참조의 형식이며, 엔드포인트가 출력을 청구하지 않으므로 output_tokens는 0입니다:

{
  "model": "gpt-6-luna",
  "answers": [
    {"type": "predicate", "name": "damaged", "probability": 0.95}
  ],
  "usage": {
    "input_tokens": 42,
    "input_tokens_details": {"cached_tokens": 0, "cache_write_tokens": 0},
    "output_tokens": 0,
    "output_tokens_details": {"reasoning_tokens": 0},
    "total_tokens": 42
  }
}

Python에서의 동일한 호출 (SDK 3.26.0 이상):

from openai import OpenAI

client = OpenAI()  # reads OPENAI_API_KEY from the environment

decision = client.decisions.create(
    model="gpt-6-luna",
    input="The box arrived crushed and the screen is cracked.",
    questions=[
        {"type": "predicate", "name": "damaged",
         "instructions": "Does the customer report a damaged item?"}
    ],
)
print(decision.answers[0].probability)

그리고 JavaScript에서 (SDK 7.30.0 이상):

import OpenAI from "openai";

const client = new OpenAI();

const decision = await client.decisions.create({
  model: "gpt-6-luna",
  input: "The box arrived crushed and the screen is cracked.",
  questions: [
    { type: "predicate", name: "damaged",
      instructions: "Does the customer report a damaged item?" },
  ],
});
console.log(decision.answers[0].probability);

유형별 답변 읽기

답변은 요청한 순서대로 돌아오며, 각 답변에는 type이 있습니다. 모든 질문이 refusal로 돌아올 수 있으므로, 유형에 따라 처리하십시오.

for a in decision.answers:
    if a.type == "refusal":
        send_to_review(a.name)
    elif a.type == "predicate":
        flag = a.probability > 0.9
    elif a.type == "choice":
        route = a.choice if a.confidence > 0.8 else "review"
    elif a.type == "score":
        priority = round(a.score)

OpenAI 가이드에서는 다음과 같이 구분합니다: 부서와 같이 순서가 없는 카테고리에는 choice를, 심각도와 같이 순서가 있는 레벨에는 score를 사용합니다.

하나의 지원 티켓에 대한 세 가지 질문

독립적인 질문들은 하나의 요청과 하나의 input을 공유하며, 각 질문은 다른 유형을 사용할 수 있습니다. 다음은 단일 티켓에 대한 predicate, choice, score의 예시입니다:

{
  "model": "gpt-6-luna",
  "input": "I was charged twice for my order.",
  "questions": [
    {"type": "predicate", "name": "refund_requested",
     "instructions": "Is the customer asking for money back?"},
    {"type": "choice", "name": "department",
     "instructions": "Which team should handle this ticket?",
     "choices": [
       {"value": "billing", "description": "Charges, refunds, invoices"},
       {"value": "technical", "description": "Bugs and errors in the product"},
       {"value": "shipping", "description": "Delivery and tracking"},
       {"value": "other", "description": "Anything else"}
     ]},
    {"type": "score", "name": "urgency",
     "instructions": "How urgent is this ticket?",
     "levels": [
       {"label": "low", "description": "No time pressure"},
       {"label": "medium", "description": "Needs a reply this week"},
       {"label": "high", "description": "Customer is blocked or losing money"}
     ]}
  ]
}

answers 배열은 요청한 순서와 동일하게 돌아옵니다. 아래의 choice 값은 이 정확한 입력에 대한 OpenAI의 가이드 값이며, predicate 및 score 값은 예시입니다:

"answers": [
  {"type": "predicate", "name": "refund_requested", "probability": 0.88},
  {"type": "choice", "name": "department", "choice": "billing",
   "probabilities": [
     {"value": "billing", "probability": 0.95},
     {"value": "technical", "probability": 0.02},
     {"value": "shipping", "probability": 0.01},
     {"value": "other", "probability": 0.02}
   ],
   "confidence": 0.93},
  {"type": "score", "name": "urgency", "score": 1.6,
   "probabilities": [
     {"value": 0, "label": "low", "probability": 0.05},
     {"value": 1, "label": "medium", "probability": 0.30},
     {"value": 2, "label": "high", "probability": 0.65}
   ],
   "confidence": 0.65}
]

가이드의 두 가지 규칙: 카테고리가 모든 입력을 다루지 못할 경우 other와 같은 대체 항목을 포함하고, 인접한 점수 레벨이 서로 다른 의미를 가지도록 관찰 가능한 기준을 중심으로 질문을 작성하십시오. 두 번째 결정이 첫 번째 답변에 의존하는 경우, 별도의 요청을 보내야 합니다.

이미지 입력

user 메시지 내부의 콘텐츠 부분으로 이미지를 전달하십시오. 가이드에서는 인라인 base64 데이터 URL을 설명합니다:

{
  "model": "gpt-6-luna",
  "input": [{
    "role": "user",
    "content": [
      {"type": "input_text", "text": "Photo attached to a return request."},
      {"type": "input_image", "image_url": "data:image/jpeg;base64,/9j/4AAQ..."}
    ]
  }],
  "questions": [
    {"type": "predicate", "name": "visible_damage",
     "instructions": "Is the product visibly damaged?"}
  ]
}

API 참조는 또한 공개적으로 접근 가능한 HTTP(S) URL, 하나의 요청에서 모든 메시지에 걸쳐 최대 128개의 이미지, 그리고 선택적인 detail 필드 (low, high, auto, original)를 나열하므로, 호스팅된 URL을 사용하기 전에 자신의 계정으로 테스트하십시오. file_id 입력은 어느 페이지에서도 지원되지 않습니다.

레이블이 지정된 예시에서 임계값 선택

OpenAI는 이 엔드포인트에 대한 정확도나 보정 수치를 공개하지 않습니다. 가이드라인은 오탐지(false positive) 비용 대비 미탐지(false negative) 비용을 기반으로 라우팅, 필터링 또는 검토를 위한 임계값을 설정하기 위해 자체 애플리케이션의 레이블이 지정된 예시를 사용하도록 권장합니다. 실제로는 사람이 선택한 부서와 함께 실제 티켓의 작은 CSV를 동일한 요청을 통해 실행하여, confidence가 깔끔한 경로와 사람의 개입이 필요한 경로를 어떻게 구분하는지 확인할 수 있습니다. 다음 섹션에서 이 루프를 구축합니다.

Apidog에서 Decisions API 테스트

저장된 요청을 통해 임계값 조정 및 회귀 검사를 반복할 수 있습니다. Apidog에서의 설정은 다음과 같습니다:

  1. 키를 환경 변수로 저장합니다. 환경을 생성하고, OPENAI_API_KEY를 비밀 변수로 추가한 다음 (Apidog 환경 및 비밀 변수에서 설정 방법을 보여줍니다), Authorization 헤더를 Bearer {{OPENAI_API_KEY}}로 설정합니다. 키는 공유 요청 본문에 절대 포함되지 않습니다.
  2. 질문 유형별로 요청을 하나씩 저장합니다. https://api.openai.com/v1/decisions로 Content-Type: application/json을 사용하여 POST 요청을 생성하고, 위 티켓 예시의 choice 질문을 별도로 붙여넣어 저장합니다. predicate 및 score 버전으로 복제하십시오.
  3. JSONPath 어설션을 추가합니다. choice 요청에서: 상태는 200, $.answers[0].type은 choice와 같고, $.answers[0].choice는 billing과 같고, $.answers[0].confidence는 0.8보다 크고, $.usage.output_tokens는 0과 같다고 어설션합니다. 손상 predicate의 경우, $.answers[?(@.name=='damaged')].probability가 0.9보다 크다고 어설션합니다. 지침의 문구 변경 또는 모델 동작 변경은 이제 티켓을 잘못 라우팅하는 대신 테스트를 실패하게 만듭니다.
  4. 레이블이 지정된 티켓에 대해 실행합니다. 저장된 요청에서 테스트 시나리오를 구축하고, ticket_text 및 expected_department 두 열을 포함하는 작은 CSV 파일을 첨부합니다. {{ticket_text}}를 input으로 매핑하고 $.answers[0].choice가 {{expected_department}}와 같다고 어설션합니다. 실행 보고서는 각 행에 대한 confidence를 보여주며, 이는 OpenAI가 임계값을 설정하도록 알려주는 데이터입니다. 모든 잘못된 경로가 위치하는 지점 아래가 코드에서 "자동 라우팅" 임계값이 됩니다.
  5. 프론트엔드를 위해 answers 배열을 모의합니다. 라우터 또는 UI를 동일한 엔드포인트의 모의(mock)로 지정하여, 임계값 위아래의 confidence를 가진 choice 답변과 refusal을 반환하도록 합니다. 이렇게 하면 입력 토큰을 소비하기 전에 검토 대기열 경로가 구축됩니다. Apidog의 조건부 모의 응답은 요청 내용에 따라 모의를 전환하는 방법을 다룹니다.
  6. CI에서 시나리오를 실행합니다. 액세스 토큰을 내보내고, 파이프라인에 단계를 추가합니다:
apidog run --access-token "$APIDOG_ACCESS_TOKEN" \
  -t "$SCENARIO_ID" -e "$ENV_ID" -r cli,junit

어설션 실패는 빌드 실패로 이어지므로, confidence의 조용한 하락은 지원 대기열에서 발견되기보다 배포 전에 감지됩니다. 더 광범위한 패턴에 대해서는 LLM 애플리케이션 테스트를 참조하십시오.

오류 및 예외 처리

자주 묻는 질문

다음 단계

이 가이드의 세 가지 질문 티켓 요청을 보낸 다음, 자체 레이블이 지정된 20개의 티켓에 대해 실행하여 confidence가 올바른 경로와 잘못된 경로를 어떻게 구분하는지 확인하십시오. 그런 다음 요청, CSV 시나리오 및 어설션을 함께 유지할 수 있도록 Apidog를 다운로드하여 오늘 선택한 임계값이 배포할 때마다 다시 확인되도록 하십시오.

Apidog에서 API 설계-첫 번째 연습

API를 더 쉽게 구축하고 사용하는 방법을 발견하세요

무료 회원가입다운로드