DEV Community

Cover image for OpenAI Responses API Nasıl Kullanılır
Tobias Hoffmann
Tobias Hoffmann

Posted on • Originally published at apidog.com

OpenAI Responses API Nasıl Kullanılır

Bu rehberde OpenAI Responses API'yi uçtan uca uygulamalı olarak test edeceksiniz: POST /v1/responses isteği gönderecek, iç içe output alanını okuyacak, yerleşik araçları etkinleştirecek, konuşma durumunu çağrılar arasında taşıyacak ve sözleşmeyi Apidog içinde doğrulayacaksınız. Responses API, OpenAI'nin model çıktısı üretmek için önerdiği daha yeni arayüzdür; ayrıntılar için resmi Responses rehberine bakabilirsiniz. Eski uç noktayı test ettiyseniz, ChatGPT API test rehberindeki iş akışının büyük kısmını burada da kullanabilirsiniz.

Apidog'u bugün deneyin

Önce gereksinimleri hazırlayın

İlk isteği göndermeden önce şu üç şeyi netleştirin:

  • OpenAI API anahtarınız hazır olsun. Anahtarı komut içine yazmayın; ortam değişkeni kullanın.
  • Hesabınızın erişebildiği model adını kontrol edin. Model adını sabit kodlamadan önce OpenAI kontrol panelindeki kullanılabilir model listesini doğrulayın.
  • Ham HTTP isteği gönderebileceğiniz bir araç seçin. İlk deneme için curl, sözleşme doğrulaması ve mock senaryoları için Apidog kullanabilirsiniz.

Responses API'nin ana uç noktası şudur:

POST https://api.openai.com/v1/responses
Enter fullscreen mode Exit fullscreen mode

Bu uç noktaya bir model ve input gönderirsiniz. Yanıt olarak metin çıktısı, araç çağrıları ve gerekirse web araması, dosya araması veya kod çalıştırma gibi OpenAI tarafından barındırılan araçların sonuçlarını içeren bir response nesnesi alırsınız.

Chat Completions ile farkı nedir?

POST /v1/chat/completions kullandıysanız, temel fark istek/yanıt şekli ve durum yönetimidir.

Chat Completions tarafında:

  • messages dizisini gönderirsiniz.
  • choices[].message okursunuz.
  • Konuşma geçmişini her çağrıda siz yeniden gönderirsiniz.

Responses API tarafında:

  • input gönderirsiniz.
  • output içindeki typed item listesini okursunuz.
  • Konuşmayı previous_response_id ile sunucu tarafında sürdürebilirsiniz.
  • Yerleşik araçları tools dizisiyle etkinleştirebilirsiniz.
Yön Chat Completions Responses API
Uç nokta POST /v1/chat/completions POST /v1/responses
İstek gövdesi messages input + instructions
Çıktı şekli choices[].message output typed item listesi
Konuşma durumu Geçmişi siz gönderirsiniz store + previous_response_id
Yerleşik araçlar Siz uygularsınız web_search, file_search, code_interpreter vb.
Önerilen kullanım Desteklenmeye devam ediyor Yeni projeler için öneriliyor

OpenAI, Chat Completions'ın desteklenmeye devam ettiğini belirtir; bu yüzden mevcut uygulamayı tek seferde taşımak zorunda değilsiniz. Bir kullanıcı akışını seçip Responses API'ye kademeli geçiş yapabilirsiniz. Assistants API ise kullanımdan kaldırma takvimine alınmıştır; yeni ajan tabanlı çalışmalar için Responses API ile başlamak daha doğru yaklaşımdır.

İlk Responses API isteğini gönderin

Aşağıdaki örnek minimal bir çağrıdır. model değerini kendi hesabınızda kullanılabilir bir modelle değiştirin.

export OPENAI_API_KEY="sk-..."

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
  }'
Enter fullscreen mode Exit fullscreen mode

Bu istekteki temel alanlar:

  • model: Kullanılacak OpenAI modeli.
  • input: Modele gönderilen kullanıcı girdisi.
  • instructions: Sistem seviyesinde davranış yönergesi.
  • store: Yanıtın saklanıp saklanmayacağını belirler. true olduğunda bu yanıtı sonraki çağrılarda previous_response_id ile bağlayabilirsiniz.

Yanıt yapısını okuyun

Kısaltılmış örnek yanıt:

{
  "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
  }
}
Enter fullscreen mode Exit fullscreen mode

Burada en önemli nokta: metin çıktısı doğrudan üst seviyede değildir.

Ham HTTP yanıtında metin genellikle şu yoldadır:

output[0].content[0].text
Enter fullscreen mode Exit fullscreen mode

Örnek olarak jq ile okuyabilirsiniz:

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 about API testing."
  }' | jq -r '.output[0].content[0].text'
Enter fullscreen mode Exit fullscreen mode

Ayrıca şu alanları da kaydedin:

  • id: Sonraki çağrıda previous_response_id olarak kullanılabilir.
  • status: İsteğin tamamlanıp tamamlanmadığını gösterir.
  • usage.total_tokens: Token kullanımını izlemek için kullanılır.

Yerleşik araçları etkinleştirin

Responses API, bazı araçları sunucu tarafında çalıştırabilir. Bunları tools dizisine eklersiniz; model, aracı ne zaman kullanacağına karar verir.

Yaygın yerleşik araç türleri:

  • web_search: Canlı web araması.
  • file_search: Yüklenen dosyalar üzerinde arama.
  • code_interpreter: Kod çalıştırma ve analiz.
  • computer_use: Bilgisayar arayüzü kullanımı.
  • image_generation: Görsel üretimi.

Örnek web araması isteği:

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

curl ile:

curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "input": "What changed in the latest OpenAPI release? Cite sources.",
    "tools": [{ "type": "web_search" }]
  }'
Enter fullscreen mode Exit fullscreen mode

Model araç kullandığında output dizisinde yalnızca final mesajı değil, araç çağrısını temsil eden öğeler de görürsünüz. Örneğin web_search_call türünde bir item, aramanın gerçekten tetiklendiğini doğrulamak için kullanılabilir.

Konuşmayı çağrılar arasında sürdürün

Responses API'de konuşma durumu iki alanla yönetilir:

  • store: Yanıtın OpenAI tarafında saklanıp saklanmayacağını belirler.
  • previous_response_id: Yeni çağrıyı önceki response ile ilişkilendirir.

İlk çağrı:

{
  "model": "gpt-5.5",
  "input": "Explain what an API mock server does in one sentence.",
  "store": true
}
Enter fullscreen mode Exit fullscreen mode

Yanıttan id değerini alın:

{
  "id": "resp_abc123"
}
Enter fullscreen mode Exit fullscreen mode

Sonraki çağrıda bu değeri kullanın:

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

Bu yöntemle tüm konuşma geçmişini tekrar göndermeniz gerekmez.

Durum tutmak istemiyorsanız:

{
  "model": "gpt-5.5",
  "input": "Explain API mocking.",
  "store": false
}
Enter fullscreen mode Exit fullscreen mode

Sıfır veri tutma veya kendi bağlam yönetiminizi uygulama gereksiniminiz varsa store: false kullanın ve geçmişi uygulama tarafında yönetin.

Gerçek zamanlı, düşük gecikmeli ses veya işitsel akış senaryoları için farklı bir yüzey gerekir; bu durumda GPT gerçek zamanlı API rehberine bakabilirsiniz. Daha geniş ajan akışları için modeller OpenAI Ajan SDK'sı ile de kullanılabilir.

Apidog'da Responses API nasıl test edilir?

Apidog bir API test, tasarım ve mock platformudur. OpenAI SDK'sı değildir; yani Apidog içinde Python kodu yazmak yerine HTTP isteğini tanımlar, gönderir, yanıtı doğrular ve gerekirse mock üretirsiniz.

1. Ortam değişkeni oluşturun

Apidog'da bir environment oluşturun. Örneğin:

OpenAI Prod
Enter fullscreen mode Exit fullscreen mode

Ardından şu değişkeni ekleyin:

OPENAI_API_KEY=sk-...
Enter fullscreen mode Exit fullscreen mode

API anahtarını doğrudan request body veya header içine yazmayın. Header'da değişken kullanın:

Authorization: Bearer {{OPENAI_API_KEY}}
Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode

2. POST isteğini oluşturun

Yeni bir request oluşturun:

POST https://api.openai.com/v1/responses
Enter fullscreen mode Exit fullscreen mode

Body tipini JSON seçin ve örnek payload ekleyin:

{
  "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
}
Enter fullscreen mode Exit fullscreen mode

İsteği gönderdiğinizde Apidog, {{OPENAI_API_KEY}} değişkenini runtime sırasında gerçek değerle değiştirir.

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

HTTP 200 almak tek başına yeterli değildir. Uygulamanızın beklediği JSON şeklinin korunduğunu da doğrulamalısınız.

Pratik kontroller:

  • status değeri completed olmalı.
  • output[0].content[0].text mevcut ve boş olmamalı.
  • usage.total_tokens 0 değerinden büyük olmalı.
  • tools gönderildiyse output içinde beklenen araç çağrısı item'ı bulunmalı; örneğin web_search_call.

Örnek doğrulama mantığı:

status == "completed"
output[0].content[0].text exists
usage.total_tokens > 0
Enter fullscreen mode Exit fullscreen mode

Apidog'un görsel doğrulama oluşturucusu ile bu JSON yollarını test betiği yazmadan hedefleyebilirsiniz. Daha yapılandırılmış test senaryoları için API test senaryosu şablonuna bakabilirsiniz.

4. Araç çağrılarını doğrulayın

Web araması gibi bir araç test ediyorsanız request body şu şekilde olabilir:

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

Bu durumda doğrulamanız yalnızca final metni kontrol etmemeli. output dizisinde araç çağrısı item'ı olup olmadığını da kontrol edin.

Örnek beklenti:

output[*].type contains "web_search_call"
Enter fullscreen mode Exit fullscreen mode

Bu kontrol, modelin yalnızca genel bilgiyle cevap vermediğini; gerçekten araç çağrısı yaptığını doğrulamanıza yardımcı olur.

5. Yanıtı mock olarak kaydedin

Canlı OpenAI çağrıları hem maliyetlidir hem de ağ bağlantısı gerektirir. UI geliştirme, CI testi veya deterministik testler için canlı endpoint yerine mock kullanabilirsiniz.

Akış:

  1. Canlı /v1/responses isteğini Apidog'da çalıştırın.
  2. Temsili yanıtı mock response olarak kaydedin.
  3. Uygulamanızın OpenAI endpoint'i yerine Apidog mock URL'sini kullanmasını sağlayın.
  4. Frontend veya entegrasyon testleri aynı JSON şeklini token harcamadan tüketir.

Bu yaklaşım özellikle şu durumlarda işe yarar:

  • Frontend geliştirme sırasında gerçek OpenAI çağrısı yapmak istemiyorsanız.
  • CI pipeline içinde ücretli API çağrılarından kaçınmak istiyorsanız.
  • Yanıt şeklini sabit tutarak deterministik test yapmak istiyorsanız.

Mock API yaklaşımı için Taklit API açıklayıcısına bakabilirsiniz.

Sıkça Sorulan Sorular

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

Zorunlu olarak değil. OpenAI, Responses API'yi Chat Completions'ın evrimi olarak konumlandırır ve yeni projeler için önerir. Ancak Chat Completions desteklenmeye devam eder. Mevcut uygulamalarda tek seferde geçiş yapmak yerine bir akışı seçip kademeli taşıma yapabilirsiniz.

store ve previous_response_id arasındaki fark nedir?

store, yanıt nesnesinin OpenAI tarafında saklanıp saklanmayacağını belirler. previous_response_id, yeni isteği daha önce saklanan bir response ile bağlar.

Durum bilgili konuşma için:

{
  "store": true
}
Enter fullscreen mode Exit fullscreen mode

Sonraki çağrıda:

{
  "previous_response_id": "resp_abc123"
}
Enter fullscreen mode Exit fullscreen mode

Durum tutmak istemiyorsanız:

{
  "store": false
}
Enter fullscreen mode Exit fullscreen mode

Responses API'yi hangi modeller destekler?

Kullanılabilirlik hesabınıza ve seçtiğiniz modele bağlıdır. Model adını sabit kodlamadan önce OpenAI kontrol panelinizdeki kullanılabilir modelleri kontrol edin. Ardından Apidog veya curl ile küçük bir istek gönderip yanıttaki model alanını doğrulayın.

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

Evet. Apidog'da request body içine tools dizisini ekleyin, isteği gönderin ve output içinde beklenen araç çağrısı item'ını doğrulayın.

Örneğin:

{
  "tools": [
    {
      "type": "web_search"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Beklenen doğrulama:

output[*].type contains "web_search_call"
Enter fullscreen mode Exit fullscreen mode

Daha geniş API test koleksiyonları üretmek için OpenAPI spesifikasyonlarından API test koleksiyonları oluşturma rehberine bakabilirsiniz.

Özet

Responses API ile tek bir uç noktadan metin üretimi, yerleşik araçlar ve konuşma durumu yönetimi yapabilirsiniz:

POST /v1/responses
Enter fullscreen mode Exit fullscreen mode

Uygulama akışı basittir:

  1. model, input ve gerekirse instructions gönderin.
  2. Yanıttaki metni output[0].content[0].text yolundan okuyun.
  3. Web araması veya kod çalıştırma gerekiyorsa tools ekleyin.
  4. Konuşmayı sürdürmek için response id değerini previous_response_id olarak kullanın.
  5. Sözleşmeyi Apidog'da doğrulayın ve çevrimdışı geliştirme için mock response oluşturun.

Apidog'u indirin, /v1/responses isteğinizi oluşturun, API anahtarınızı environment değişkeni olarak saklayın ve entegrasyonunuzun gerçekten hangi JSON şeklini aldığını doğrulayın. Tüm bu akışı tek bir projede Apidog içinde kurabilirsiniz.

Top comments (0)