OpenAI Responses API Nasıl Kullanılır

Bu rehber, OpenAI Responses API'sini uçtan uca kullanma konusunda size yol gösterecek: bitirdiğinizde, POST /v1/responses adresine bir istek gönderebilecek, döndürdüğü iç içe çıktıyı okuyabilecek, yerleşik araçları etkinleştirebilecek, görüşme durumunu çağrılar arasında taşıyabilecek ve tüm sözleşmeyi Apidog içinde doğrulayabileceksiniz. Responses API, OpenAI'nin model çıktısı oluşturmak için daha yeni arayüzüdür ve resmi Responses rehberi, OpenAI'nin neden yeni projeleri bu API'ye yönlendirdiğini açıklar. Eğer eski uç noktayı zaten test ediyorsanız, ChatGPT API test rehberimizdeki iş akışına benzer şekilde, bu kurulumun çoğunu yeniden kullanabilirsiniz.

button

Öncelikle neye ihtiyacınız var?

Bir istek göndermeden önce, birkaç şeyin hazır olduğundan emin olun:

Güncel genel amaçlı bir modele erişimi olan bir OpenAI API anahtarı. Anahtarı bir komuta veya paylaşılan bir dosyaya yapıştırmak yerine bir ortam değişkeninde saklayın.
Hesabınızın gerçekten çağırabileceği bir model adı. Bir modeli sabit kodlamak yerine, OpenAI kontrol panelinizdeki model listesini kontrol edin ve uç noktaya karşı onaylayın.
Ham HTTP istekleri göndermenin ve gelen JSON'ı incelemenin bir yolu. `curl` içeren bir terminal ilk çağrı için işe yarar ve yanıtı daha sonra doğrulamak ve taklit etmek için Apidog'u kullanacaksınız.

Uç noktayı çağırmadan önce ne işe yaradığını bilmek de faydalıdır. Responses API, tek bir uç noktayı açığa çıkarır: POST /v1/responses. Bir model adı ve bir `input` gönderirsiniz ve düz metin, fonksiyon çağrıları ve web araması veya dosya araması gibi OpenAI tarafından barındırılan araçların sonuçlarını içerebilen bir yanıt nesnesi alırsınız. Tek bir çağrı, çok adımlı bir dönüşü çalıştırabilir: model web'de arama yapmaya karar verir, sonuçları okur, ardından bir cevap yazar ve yanıt, attığı her adımı kaydeder.

İki şey onu düz metin uç noktasından ayırır. Birincisi, yerleşik araçları sunucu tarafında çalıştırabilir, böylece kendi arama veya sanal ortamınızı kurmak zorunda kalmazsınız. İkincisi, varsayılan olarak durum bilgisi içerir. Her yanıt bir `id` alır ve bu `id`'yi bir sonraki isteğe ileterek OpenAI'nin konuşma geçmişini sizin için saklamasını sağlayabilirsiniz. OpenAI, Responses API'sini Chat Completions'ın evrimi olarak tanımlar ve Assistants API betasının derslerini de içererek yeni projeler için tavsiye eder. Böylece üç zihinsel model yerine bir tane elde edersiniz.

Chat Completions'dan farklarını bilin

POST /v1/chat/completions kullandıysanız, değişim çoğunlukla şekil ve durumdadır. Chat Completions, bir `messages` dizisi alır ve `choices` döndürür. Tüm transkripti kendiniz yönetir, her çağrıda önceki her dönüşü yeniden gönderirsiniz. Araçlar, sizin tarafınızda uyguladığınız bir şeydir.

Responses API, bir `input` (bir dize veya yazılı öğelerin listesi) alır ve bir `output` (yazılı öğelerin listesi) döndürür. Sizin için dönüşü saklayabilir ve ek tesisat olmadan barındırılan araçları çalıştırabilir.

İşte pratik karşılaştırma:

Yön	Chat Completions	Responses API
Uç Nokta	`POST /v1/chat/completions`	`POST /v1/responses`
İstek gövdesi	`messages` dizisi	`input` (dize veya öğeler) + `instructions`
Çıktı şekli	`choices[].message`	`output` yazılı öğe listesi
Konuşma durumu	Tüm geçmişi yeniden gönderirsiniz	`store` + `previous_response_id`
Yerleşik araçlar	Siz oluşturursunuz	`web_search`, `file_search`, `code_interpreter` ve daha fazlası
Durum	Destekleniyor, kullanımdan kaldırıldığı açıklanmadı	Yeni projeler için önerilir

Chat Completions ortadan kalkmıyor. OpenAI, desteklenmeye devam ettiğini ve her şeyi bir kerede yeniden yazmak yerine, her seferinde bir kullanıcı akışını taşıyabileceğinizi belirtiyor. Assistants API ise takvimdeki tek API: OpenAI, 26 Ağustos 2025'te kullanımdan kaldırdı ve 26 Ağustos 2026'da tamamen sona erdireceğini belirtti, bu nedenle yeni ajan çalışmaları Responses ile başlamalıdır.

İlk isteğinizi yapın

İşte minimal bir çağrı. Model adını hesabınızın erişebildiği herhangi bir modelle değiştirin ve anahtarınızı komutun dışında tutun.

curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "input": "Write one sentence describing what an API mock server does.",
    "instructions": "You are a concise technical writer. No marketing language.",
    "store": true
  }'

Burada önemli olan üç şeyi iletirsiniz: `model`, `input` (isteminiz) ve `instructions` (sistem seviyesi yönlendirme). `store`'u `true` olarak ayarlamak, OpenAI'ye yanıtı kaydetmesini söyler, böylece iş parçacığını daha sonra devam ettirebilirsiniz.

Yanıtı okuyun

Kısaltılmış bir yanıt şöyle görünür:

{
  "id": "resp_abc123",
  "object": "response",
  "status": "completed",
  "model": "gpt-5.5",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "A mock server returns predefined API responses so clients can be developed and tested before the real backend exists."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 28,
    "output_tokens": 24,
    "total_tokens": 52
  }
}

Yapıya dikkat edin, çünkü insanları şaşırtan kısım budur. İstediğiniz metin, en üst düzey bir alanda değil, `output[0].content[0].text` adresinde bulunur. Resmi SDK'lar, tüm metin öğelerini tek bir dizeye toplayan `output_text` kolaylık erişimcisini ekler, ancak bu özellik bir SDK yardımcısıdır, ham HTTP JSON'ının bir parçası değildir. Uç noktayı doğrudan çağırdığınızda, iç içe yolu okursunuz. En üst düzey `id`, durumu yeniden kullanacağınız şeydir ve `usage.total_tokens` size çağrının maliyetini söyler.

Yerleşik araçları ekleyin

Öne çıkan özellik, OpenAI'nin sizin için belirli araçları çalıştırmasıdır. Onları bir `tools` dizisinde listelersiniz ve model ne zaman çağıracağına karar verir. Doğrulanmış yerleşik türler şunları içerir:

Canlı internet aramaları için atıflı web_search (eski web_search_preview eski entegrasyonlar için hala çalışır ancak daha yeni kontrollere sahip değildir).
Yüklediğiniz dosyalar arasında arama yapmak için file_search.
Bir sanal ortamda kod çalıştırmak ve analiz etmek için code_interpreter.
Bir bilgisayar arayüzünü yönlendirmek için computer_use.
Satır içi görüntü oluşturmak için image_generation.

Bunlardan birini etkinleştirmek, gövdeye küçük bir eklemedir:

{
  "model": "gpt-5.5",
  "input": "What changed in the latest OpenAPI release? Cite sources.",
  "tools": [{ "type": "web_search" }]
}

Model bir araç kullandığında, `output` dizisi, son `message` ile birlikte `web_search_call` gibi adımı belgeleyen girişler kazanır. Bu daha sonra faydalıdır: bir aracın gerçekten çalıştığını, sadece metin döndürmediğini kontrol edebilirsiniz.

Çağrılar arasında konuşmayı sürdürün

Durum iki parametre aracılığıyla çalışır. `store` varsayılan olarak true'dur, bu da OpenAI'nin yanıt nesnesini kaydettiği (varsayılan olarak 30 gün boyunca saklanır) ve bir `id` döndürdüğü anlamına gelir. Bu `id`'yi bir sonraki çağrınızda `previous_response_id` olarak iletin ve model, transkripti yeniden göndermenize gerek kalmadan ileti dizisini devam ettirir:

{
  "model": "gpt-5.5",
  "input": "Now rewrite that for a non-technical audience.",
  "previous_response_id": "resp_abc123"
}

Eğer durumu olmayan bir yaklaşım tercih ediyorsanız veya sıfır veri tutma gereksiniminiz varsa, `store`'u false olarak ayarlayın ve bağlamı kendiniz yönetin. Gerçek zamanlı, düşük gecikmeli ses ve işitsel akışlar için OpenAI farklı bir yüzey kullanır; GPT gerçek zamanlı API rehberimiz bu durumu kapsar. Ve tüm bunların üzerine çok adımlı ajanlar düzenliyorsanız, modeller OpenAI Ajan SDK'sı ile uyumludur.

Apidog'da nasıl test edilir?

Apidog bir API test, tasarım ve taklit platformudur. Bir OpenAI SDK'sı veya kod kütüphanesi değildir, bu yüzden ona karşı Python yazmazsınız. Bunun yerine ne yaparsınız: `/v1/responses` adresine ham HTTP isteğini oluşturur, gönderir ve gelen JSON üzerinde doğrulama yapar. Bu, kullanıcılarınızdan önce bozuk bir entegrasyonu yakalayan tam da böyle bir sözleşme kontrolüdür.

İşte adım adım kurulum.

Anahtarı bir ortam değişkeninde saklayın

Apidog'da bir ortam oluşturun (örneğin, "OpenAI Prod") ve `OPENAI_API_KEY` gibi bir değişken ekleyin. Değeri isteğe değil, ortama kaydedin, böylece sır asla paylaşılan bir koleksiyona kaydedilmez. Ardından `https://api.openai.com/v1/responses` adresine yeni bir `POST` isteği oluşturun ve `Authorization: Bearer {{OPENAI_API_KEY}}` başlığını ekleyin. Apidog, gönderme sırasında değişkeni değiştirir.

Gövdeyi JSON olarak ayarlayın ve önceki isteği yapıştırın. Gönder'e tıklayın. Biçimlendirilmiş, iç içe `output` dizisiyle tam yanıt nesnesini göreceksiniz.

Yanıt alanlarını doğrulayın

Başarılı bir 200, yanıtın uygulamanızın beklediği şekilde olduğunun kanıtı değildir. Bir regresyonun yüksek sesle başarısız olması için doğrulamalar ekleyin. `/v1/responses` yanıtına karşı yararlı kontroller:

`status` değeri `completed`'a eşittir.
`output[0].content[0].text` mevcuttur ve boş değildir.
`usage.total_tokens` 0'dan büyüktür.
`tools` gönderdiğinizde, `output` içinde bir öğenin `type` değeri `web_search_call`'a eşittir.

Apidog'un görsel doğrulama oluşturucusu, test betikleri yazmadan bu JSON yollarını hedeflemenizi sağlar ve API test senaryosu şablonumuz bu tür kontrollerin nasıl yapılandırılacağını gösterir. İsteği bir koleksiyona kaydedin ve bu, CI'da çalıştırabileceğiniz tekrarlanabilir bir teste dönüşür.

Çevrimdışı geliştirme için yanıtı taklit edin

OpenAI çağrıları para maliyetli ve ağ erişimi gerektirir, bu da yanıtı tüketen kullanıcı arayüzünü geliştirirken veya ücretli bir API'yi hedeflememesi gereken bir işlem hattında testler çalıştırırken zahmetlidir. Apidog'un taklit özelliği bunu çözer. Temsili bir `/v1/responses` yükünü bir taklit olarak kaydedin, uygulamanızı Apidog taklit URL'sine yönlendirin ve ön uçunuz sıfır token harcamasıyla doğru JSON şeklini alır. Gerçek uç nokta değiştiğinde, her testteki hataları kovalamak yerine bir taklidi güncellersiniz. Taklit API açıklayıcımız genel yaklaşımı anlatır.

Bu ayrım önemlidir. OpenAI'nin sözleşmesini doğrulamak için canlı uç noktaya karşı test yapar ve hızlı, çevrimdışı, deterministik geliştirme için taklit edersiniz. Her ikisi de aynı Apidog projesinden çalışır.

Sıkça Sorulan Sorular

Responses API, Chat Completions'ın yerini mi alıyor?

Zorunlu olarak değil. OpenAI, Responses'ı Chat Completions'ın evrimi olarak adlandırıyor ve yeni projeler için tavsiye ediyor, ancak Chat Completions, kullanım dışı kalma tarihi açıklanmadan desteklenmeye devam ediyor. Bir akışı tek seferde taşıyabilirsiniz. Assistants API, 2026'da sona erme tarihiyle kullanımdan kaldırılan API'dir.

`store` ve `previous_response_id` arasındaki fark nedir?

`store`, OpenAI'nin yanıt nesnesini kaydedip kaydetmediğini kontrol eder (varsayılan olarak doğrudur ve 30 gün boyunca saklanır). `previous_response_id`, yeni bir isteği saklanmış bir istekle nasıl bağlayacağınızdır, böylece model konuşmayı sunucu tarafında devam ettirir. Durum bilgisi olan iş parçacıkları için bunları birlikte kullanır ve durum bilgisi olmayan davranış istediğinizde `store`'u kapatırsınız.

Responses API'yi hangi modeller destekler?

OpenAI'nin mevcut genel amaçlı modelleri, Responses API ile çalışacak şekilde tasarlanmıştır, ancak kullanılabilirlik hesabınıza ve seçtiğiniz modele bağlıdır. Bir model adını sabit kodlamak yerine, OpenAI kontrol panelinizdeki model listesini kontrol edin, ardından uç noktaya karşı onaylayın. Apidog aracılığıyla hızlı bir istek gönderip yanıttaki `model` alanını okumak, anahtarınızın gerçekten neyi çağırabileceğini doğrulamanın hızlı bir yoludur.

Yerleşik araçları kod yazmadan test edebilir miyim?

Evet. Apidog'da JSON gövdesine bir `tools` dizisi ekleyin, isteği gönderin ve eşleşen araç çağrısı öğesinin (web_search_call gibi) `output` dizisinde göründüğünü doğrulayın. OpenAI'nin HTTP üzerindeki davranışını kontrol ediyorsunuz, bu yüzden bir SDK'ya gerek yoktur. Ajan araç çağrılarını daha geniş çapta test etmek için, OpenAPI spesifikasyonlarından API test koleksiyonları nasıl oluşturulur bölümüne bakın.

Özet

Artık tam bir döngünüz var: metin, barındırılan araçlar ve sunucu tarafı konuşma durumunu yöneten tek bir uç nokta, POST /v1/responses. Bir istek gönderin, iç içe `output`'u okuyun, arama veya kod yürütmeye ihtiyacınız olduğunda bir `tools` dizisi ekleyin ve bir iş parçacığını devam ettirmek için `previous_response_id`'yi zincirleyin. Şekil Chat Completions'tan farklı olduğu için, en güvenli hareket, eski API hakkındaki hafızanıza güvenmek yerine sözleşmeyi kendiniz doğrulamaktır.

Apidog'un devreye girdiği yer burasıdır. İsteği oluşturun, anahtarınızı bir ortam değişkeni olarak saklayın, iç içe `output` alanlarını doğrulayın ve çevrimdışı çalışma için yanıtı taklit edin, hepsi tek bir projede. Apidog'u indirin ve entegrasyonunuzun tam olarak ne aldığını görmek için `/v1/responses` adresine bir test yönlendirin. Tek bir test kodu yazmadan tüm kurulumu Apidog içinde yapabilirsiniz.

button