OpenAI Decisions API'si Nasıl Kullanılır?

OpenAI Decisions API'yi kullanmak için, https://api.openai.com/v1/decisions adresine "model": "gpt-6-luna", bir input (metin, görseller veya her ikisi) ve her sorunun bir predicate, choice veya score olduğu bir questions dizisi ile bir POST isteği gönderin. Ayrıştırılacak metin yerine olasılıklı, tip verilmiş yanıtlar alırsınız ve çıktı, önbellek okuma veya önbellek yazma ücreti olmadan 1 milyon giriş belirteci başına 0,10 ABD doları ödersiniz. Uç nokta, 6 Ekim 2026 itibarıyla genel beta sürümündedir.

Bu kılavuz, bir anahtar almayı, curl, Python ve JavaScript'te ilk çağrıyı, her yanıt türünü okumayı, bir destek biletiyle ilgili üç soruyu, görsel girişini, eşikleri ve Apidog'daki bir test kurulumunu kapsar. Uç noktayı ne zaman seçeceğinizi öğrenmek için, OpenAI Decisions API nedir konusuyla başlayın.

düğme

Decisions API isteğine bir bakış

Alan	Neyi alır
`model`	`gpt-6-luna` (beta sürümünde mevcut tek model)
`input`	Bir dize veya `content`'i bir dize ya da `input_text` ve `input_image` türünde parçalar olan `user` mesajlarından oluşan bir dizi
`questions[].type`	`predicate`, `choice` veya `score`
`questions[].instructions`	Zorunlu; soru açık kelimelerle
`questions[].name`	İsteğe bağlı; yanıtta geri yansıtılır (atlanırsa `null`)
`questions[].choices`	Yalnızca `choice`; 2 ila 255 benzersiz `{value, description}` nesnesi, `value` bir dize veya boole değeri
`questions[].levels`	Yalnızca `score`; sıralı `{label, description}` nesneleri, en düşük önce, indeksler 0'dan başlar
`safety_identifier`	İsteğe bağlı opak son kullanıcı kimliği, 128 karaktere kadar

Kaynak: Decisions API referansı. Bu uç noktada temperature, stream, tools veya text.format yoktur.

Bir anahtar alın ve ilk çağrıyı yapın

OpenAI kontrol panelinde bir anahtar oluşturun (OpenAI API anahtarı kılavuzu bunu kapsar), OPENAI_API_KEY olarak dışa aktarın ve asla koda yapıştırmayın. Ardından bir evet/hayır sorusu sorun:

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

Yanıtın üç üst düzey alanı vardır: model, answers ve usage. Bu, OpenAI'nin referansından alınan şekildir; uç nokta çıktı faturalandırmadığı için output_tokens 0'dır:

{
  "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'da aynı çağrı (SDK 3.26.0 veya sonrası):

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)

Ve JavaScript'te (SDK 7.30.0 veya sonrası):

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

Yanıtı türe göre okuyun

Yanıtlar, sorduğunuz sırayla, her biri bir type ile geri döner. Türü kontrol edin, çünkü herhangi bir soru bir refusal olarak geri dönebilir.

predicate, koşulun doğru olduğuna dair 0 ile 1 arasında bir tahmin olan probability değerini döndürür.
choice, choice (kazanan value), {value, probability} nesnelerinden oluşan bir dizi olarak probabilities ve confidence değerlerini döndürür.
score, score, {value, label, probability} nesnelerinden oluşan bir dizi olarak probabilities (burada value 0 tabanlı seviye indeksidir) ve confidence değerlerini döndürür. Skor, seviye indekslerinin olasılık ağırlıklı ortalamasıdır, bu nedenle seviyeler arasında yer alabilir: 1.1, "seviye 1 ile seviye 2 arasında, 1'e yakın" anlamına gelir.
refusal yalnızca type ve name değerlerini döndürür. Model bu soruyu reddetti; aynı istekteki diğer sorular yine de yanıt alabilir.

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'nin kılavuzu sınırı şu şekilde çizer: bölümler gibi sıralanmamış kategoriler için choice; önem derecesi gibi sıralı seviyeler için score.

Tek bir destek biletinde üç soru

Bağımsız sorular tek bir isteği ve tek bir input'u paylaşır ve her soru farklı bir tür kullanabilir. İşte tek bir bilet üzerindeki bir predicate, bir choice ve bir 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 dizisi aynı sırayla geri döner. Aşağıdaki choice değerleri, bu belirli girdi için OpenAI'nin kılavuz değerleridir; predicate ve score değerleri açıklayıcıdır:

"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}
]

Kılavuzdan iki kural: kategorileriniz her girdiyi kapsamadığında other gibi bir yedek dahil edin ve bitişik skor seviyelerinin farklı şeyler ifade etmesi için gözlemlenebilir kriterler etrafında sorular yazın. Eğer ikinci bir karar ilk yanıta bağlıysa, ayrı bir istek gönderin.

Görsel girişi

Bir görseli bir user mesajının içinde içerik parçası olarak iletin. Kılavuz, satır içi base64 veri URL'lerini belgeler:

{
  "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 referansı ayrıca herkese açık HTTP(S) URL'lerini, tek bir istekte tüm mesajlarda 128'e kadar görseli ve isteğe bağlı bir detail alanını (low, high, auto, original) listeler, bu nedenle barındırılan URL'lere güvenmeden önce kendi hesabınızda test edin. file_id girdileri her iki sayfada da desteklenmemektedir.

Etiketli örneklerden eşikleri belirleyin

OpenAI, uç nokta için doğruluk veya kalibrasyon rakamları yayınlamaz. Kılavuzu, yanlış pozitiflerin yanlış negatiflere karşı maliyetine dayalı olarak yönlendirme, filtreleme veya inceleme için eşikleri belirlemek üzere kendi uygulamanızdan etiketli örnekleri kullanmaktır. Pratikte bu, bir insanın seçtiği departmanla gerçek biletlerden oluşan küçük bir CSV'nin aynı istekten geçirilmesi anlamına gelir, böylece confidence'ın temiz rotaları bir kişiye ihtiyaç duyanlardan nerede ayırdığını görebilirsiniz. Bir sonraki bölüm bu döngüyü oluşturur.

Decisions API'yi Apidog'da test edin

Kaydedilmiş istekler, eşik ayarlamasını ve regresyon kontrollerini tekrarlanabilir kılar. İşte Apidog'daki kurulum:

Anahtarı bir ortam değişkeni olarak saklayın. Bir ortam oluşturun, OPENAI_API_KEY'i gizli bir değişken olarak ekleyin (Apidog ortamları ve gizli değişkenleri kurulumu gösterir) ve Authorization başlığını Bearer {{OPENAI_API_KEY}} olarak ayarlayın. Anahtar asla paylaşılan bir istek gövdesine düşmez.
Soru tipine göre bir istek kaydedin. https://api.openai.com/v1/decisions adresine Content-Type: application/json ile bir POST oluşturun, yukarıdaki bilet örneğinden choice sorusunu kendi başına yapıştırın ve kaydedin. Predicate ve score versiyonları için kopyalayın.
JSONPath onaylamaları ekleyin. Choice isteğinde: durum 200, $.answers[0].type choice'a eşit, $.answers[0].choice billing'e eşit, $.answers[0].confidence 0.8'den büyük ve $.usage.output_tokens 0'a eşit. Hasar predicate'i için, $.answers[?(@.name=='damaged')].probability'nin 0.9'dan büyük olduğunu onaylayın. Talimatlarınızdaki bir kelime değişikliği veya bir model davranış değişikliği, biletleri yanlış yönlendirmek yerine artık bir testi başarısız kılar.
Etiketli biletler üzerinde çalıştırın. Kaydedilmiş istekten bir test senaryosu oluşturun ve iki sütunlu (ticket_text ve expected_department) küçük bir CSV ekleyin. {{ticket_text}}'i input'a eşleyin ve $.answers[0].choice'un {{expected_department}}'a eşit olduğunu onaylayın. Çalışma raporu, OpenAI'nin eşikleri belirlemenizi söylediği veri olan her satır için confidence'ı gösterir. Her yanlış rotanın oturduğu noktanın altı, kodunuzdaki "otomatik yönlendir" eşiğiniz olur.
Ön uç için answers dizisini taklit edin. Yönlendiriciyi veya kullanıcı arayüzünü, eşiğinizin üzerinde ve altında bir confidence ile bir choice yanıtı ve ayrıca bir refusal döndüren aynı uç noktanın bir taklidine yönlendirin, böylece bir giriş belirteci harcamadan önce inceleme sırası yolu oluşturulur. Apidog'da koşullu taklit yanıtlar, istek içeriğine göre taklitleri değiştirmeyi kapsar.
Senaryoyu CI'da çalıştırın. Bir erişim belirteci dışa aktarın, ardından işlem hattınıza bir adım ekleyin:

apidog run --access-token "$APIDOG_ACCESS_TOKEN" \
  -t "$SCENARIO_ID" -e "$ENV_ID" -r cli,junit

Başarısız bir onaylama derlemeyi başarısız kılar, böylece confidence'taki sessiz bir düşüş, destek kuyruğunda değil, dağıtımdan önce yakalanır. Daha geniş kalıplar için LLM uygulamalarını test etme konusuna bakın.

Hataları ve uç durumları ele alın

429 hız sınırlı. Decisions API'ye özel bir sınır yayınlanmamıştır; kendi sayılarınız için Ayarlar > Kuruluş > Sınırlar bölümünü kontrol edin. Üstel olarak geri çekilin ve mevcut olduğunda bir Retry-After başlığını dikkate alın. Hız sınırı aşıldı kılavuzu bir yeniden deneme sarıcısına sahiptir.
Reddedilen yanıtlar. type: "refusal"'ı bir yönlendirme sonucu olarak ele alın, bir istisna olarak değil. Bu bileti bir insana gönderin ve aynı isteğin diğer yanıtlarını saklayın.
Bağımlı kararlar. Her soru, paylaşılan girdiye karşı bağımsız olarak değerlendirilir. Daha önceki bir yanıta bağlı olan her şey kendi isteğine ihtiyaç duyar.

SSS

Decisions API ne kadar tutar? gpt-6-luna üzerinde 1 milyon giriş belirteci başına 0,10 ABD doları, çıktı, önbellek okuma veya önbellek yazma ücreti yok. Üç sorulu 500 belirteçlik bir bilet 500 / 1.000.000 x 0,10 ABD doları = 0,00005 ABD doları tutar, bu nedenle bir milyon böyle bilet 50 ABD doları tutar. 272K belirtecin üzerindeki uzun bağlamlı giriş 2 katıdır ve bölgesel işleme %10 ekler.

Decisions API ücretsiz mi? Hayır. Ücretsiz bir Decisions katmanı yok. GPT-6 Luna'yı ücret ödemeden denemek isterseniz, GPT-6 Luna ücretsiz rotaları gönderisi mevcut olanları listeler.

Ne kadar hızlıdır? OpenAI, Responses API'den yaklaşık 10 kat daha hızlı olduğunu söylüyor ve mutlak bir gecikme süresi numarası yayınlamıyor. OpenAI forumundaki bir geliştirici, yaklaşık 0,8 saniyede görsel kararları rapor etti.

Decisions API hangi modellerle çalışır? Bugün yalnızca gpt-6-luna. Luna üzerinde bir uç noktadır, ayrı bir model değil. Modelin kendisi için GPT-6 Luna nedir bölümüne bakın.

Bunun yerine Yapılandırılmış Çıktıları ne zaman kullanmalıyım? Kendi JSON şemanızda (çıkarılan alanlar veya yazılı bir açıklama gibi) bir nesneye ihtiyacınız olduğunda veya modelin bağımsız değişkenlerle bir araç istemesi gerektiğinde işlev çağırmayı kullanın. Decisions API vs Responses API gönderisi, aynı biletin her iki şekilde nasıl yapıldığını gösterir.

Jev ile nasıl karşılaştırılır? Her ikisi de olasılıklı ve yalnızca giriş faturalandıran tipte yanıtlar döndürür; Jev, 1 milyon başına 0,042 ABD doları ile yalnızca metin tabanlıdır. Decisions API vs Jev karşılaştırması tam tabloyu içerir.

Sonraki adım

Bu kılavuzdaki üç sorulu bilet isteğini gönderin, ardından kendi etiketli biletlerinizden 20'si üzerinde çalıştırın ve confidence'ın doğru rotaları yanlış olanlardan nerede ayırdığını görün. Ardından, isteği, CSV senaryosunu ve onaylamaları bir arada tutmak için Apidog'u indirin, böylece bugün seçtiğiniz eşik her dağıtımda tekrar kontrol edilir.