OpenAI Responses API rehberi: Temel istek, kaynaklı cevap ve izlenebilir örnek akış

OpenAI Responses API nedir?

Son kontrol: 18 Ekim 2026. OpenAI Responses API, API referansındaki tanımıyla model cevabı oluşturan POST /responses uç noktasıdır; metin ya da görsel girdisinden metin veya JSON çıktı üretir. OpenAI’ın geçiş rehberine göre Chat Completions desteklenmeye devam ediyor, ancak tüm yeni projeler için Responses öneriliyor.

• Girdi: input alanı düz metin ya da mesaj listesi alır; sistem düzeyindeki yönerge instructions alanına yazılır.
• Çıktı: Cevap, output dizisindeki öğelerden (mesaj, akıl yürütme, fonksiyon çağrısı) oluşur; SDK’daki output_text yardımcısı metni tek seferde verir.
• Araçlar: Web araması, dosya araması, bilgisayar kullanımı, kod yorumlayıcı, uzak MCP sunucuları ve görsel üretimi yerleşik araç olarak eklenebilir.
• Not: Geçiş rehberine göre Assistants API 26 Ağustos 2026’da kapatıldı.

Responses API ile ilk istek nasıl gönderilir?

İlk istek, resmî SDK kurulduktan ve API anahtarı OPENAI_API_KEY ortam değişkenine yazıldıktan sonra client.responses.create ile gönderilir. Aşağıdaki kod OpenAI’ın geçiş rehberindeki örneğe dayanır:

from openai import OpenAI

client = OpenAI()  # anahtarı OPENAI_API_KEY ortam değişkeninden okur

response = client.responses.create(
    model="gpt-6-astra",
    instructions="Kısa ve net Türkçe cevap ver.",
    input="Responses API ile Chat Completions arasındaki temel fark nedir?",
)
print(response.output_text)

Model adı OpenAI’ın örneklerinde kullanılan modeldir; kendi işinize göre seçin. Anahtar alma ve güvenli saklama adımları OpenAI API anahtarı rehberimizde. API kullanımı ücretlidir ve yeni hesaplar ön ödemeli kredilerle çalışır (ön ödemeli faturalama).

Responses API ile Chat Completions arasındaki fark nedir?

Responses API; yerleşik araçları, öğe tabanlı çıktısı, output_text yardımcısı ve sunucuda saklanan konuşma durumuyla Chat Completions’tan ayrılır. Geçiş rehberindeki farklar:

Ölçüt	Responses API	Chat Completions
Girdi	input (metin veya mesaj listesi) + instructions	messages
Çıktı	output öğeleri; SDK’da output_text	output_text yardımcısı yok
Yerleşik araçlar	Web araması, dosya araması, bilgisayar kullanımı, kod yorumlayıcı, uzak MCP, görsel üretimi	Araç entegrasyonunu geliştirici yazar
Yapılandırılmış çıktı	text.format	response_format
Konuşma durumu	previous_response_id veya Conversations API; cevaplar varsayılan olarak saklanır	Geçmiş istemci tarafında tutulur
Akıl yürütme modelleri	Araç kullanımıyla daha zengin deneyim	GPT-5.4’ten itibaren reasoning_effort “none” dışındayken araç çağrısı yok

Rehber ayrıca önceki cevaba previous_response_id ile bağlanıldığında zincirdeki tüm önceki girdi tokenlarının yeniden girdi olarak faturalandığını belirtiyor; uzun zincirlerde maliyet bu yüzden büyür. Tekrarlanan girdilerin maliyetini düşürme yolu prompt caching nedir yazısında.

Kaynaklı içerik için izlenebilir örnek akış

Kaynaklı içerik görevinde amaç, modelin hangi siteleri okuduğunu ve hangi cümleyi hangi kaynağa dayandırdığını kayıt altına almaktır; Responses API’de web_search aracı, kaynak listesi seçeneği ve url_citation notları bunu sağlar. OpenAI’ın web araması rehberine göre:

• tools içine {“type”: “web_search”} eklenir; filters ile en çok 100 izinli (allowed_domains) ya da 100 engelli alan adı tanımlanabilir.
• include içine “web_search_call.action.sources” yazılırsa modelin baktığı tüm adreslerin listesi döner.
• Mesaj öğesindeki notlar (annotations), atıf yapılan adresi, başlığı ve metindeki konumu (start_index, end_index) içerir.
• Son kullanıcıya gösterilen satır içi atıflar açıkça görünür ve tıklanabilir olmalıdır.

Bu blogu yazarken uyguladığımız kurala (bilgiyi yalnız resmî alan adlarından almak) göre hazırlanmış örnek betik:

import json
from openai import OpenAI

client = OpenAI()
response = client.responses.create(
    model="gpt-6-astra",
    instructions="Her iddiayı yalnız verilen alan adlarındaki sayfalara dayandır; kaynak bulunamazsa 'doğrulanamadı' yaz.",
    input="ChatGPT Go planına neler dahil? Türkçe ve maddeler hâlinde yaz.",
    tools=[{"type": "web_search", "filters": {"allowed_domains": ["help.openai.com", "chatgpt.com"]}}],
    include=["web_search_call.action.sources"],
)

kayit = {"id": response.id, "model": response.model, "metin": response.output_text, "atiflar": [], "bakilan": []}
for oge in response.output:
    if oge.type == "web_search_call" and getattr(oge.action, "sources", None):
        kayit["bakilan"] += [s.url for s in oge.action.sources]
    if oge.type == "message":
        for parca in oge.content:
            for not_ in getattr(parca, "annotations", []) or []:
                if not_.type == "url_citation":
                    kayit["atiflar"].append({"url": not_.url, "baslik": not_.title})

with open("kaynakli_cevap.json", "w", encoding="utf-8") as f:
    json.dump(kayit, f, ensure_ascii=False, indent=1)

Kayıt dosyası; cevabın kimliğini, modelini, metnini, atıflarını ve bakılan adresleri birlikte tutar. Sonraki adım elle doğrulamadır: her atıfı açıp cümlenin kaynakta geçtiğini kontrol edin. Bu kontrolün nasıl yapıldığını deep research rehberimizdeki iddia-kaynak tablosunda gösterdik. Betik, SDK’nın güncel sürümüne göre küçük ad değişiklikleri gerektirebilir; çalıştırmadan önce referans sayfasını kontrol edin.

Cevaplar nerede saklanır, veri nasıl kullanılır?

Responses API’de cevaplar varsayılan olarak saklanır; saklamayı kapatmak için istekte store: false gönderilir. Geçiş rehberine göre Sıfır Veri Saklama (ZDR) kullanan kuruluşlarda store: false otomatik uygulanıyor; akıl yürütmeyi korurken durumsuz çalışmak için dönen akıl yürütme öğeleri (encrypted_content dahil) saklanıp tekrar gönderiliyor.

OpenAI’ın Codex yardım sayfasındaki veri notuna göre şirket, API dahil kurumsal ürünlerin girdi ve çıktılarını varsayılan olarak model iyileştirmede kullanmıyor; API kuruluş sahipleri isterse veri paylaşımını açabiliyor.

Responses API'de sık görülen hatalar

Responses API isteklerinde sık görülen hatalar kimlik doğrulama (401), hız ve kredi sınırı (429) ile sunucu kaynaklı (500, 503) hatalardır; hata kodları belgesi her biri için ne yapılacağını yazıyor.

• 401 Incorrect API key provided: Anahtardaki yazım ve boşluk hatasını kontrol edin ya da yeni anahtar oluşturun.
• 429 Rate limit reached: Retry-After başlığı kadar bekleyin, yoksa üstel geri çekilme uygulayın.
• 429 credit_balance_exhausted: Ön ödemeli kredi bitmiştir; tekrar denemek düzeltmez, kredi eklenmelidir.
• 500 / 503: Kısa süre bekleyip yeniden deneyin; sürerse OpenAI durum sayfasındaki Responses bileşenine bakın (durum sayfası rehberi).

Uzak MCP ve dosya araması gibi araçlarla daha uzun görevleri Codex’te yürütmek için Codex kullanım rehberimize, başka bir sağlayıcının API akışı için DeepSeek API kullanımı yazısına bakabilirsiniz.

İçerik ve SEO ekipleri Responses API'yi nasıl kullanabilir?

İçerik ve SEO ekipleri Responses API’yi; kaynaklı taslak üretimi, mevcut sayfaların kaynak kontrolü ve tekrarlanan rapor işleri için kullanabilir; her durumda çıktının insan tarafından doğrulanması gerekir. Kaynak kısıtlı web araması, yanlış ya da eski bilginin taslağa girme riskini azaltır.

Taslakların yayına hazırlanması için SEO uyumlu içerik yazımı, çok sayfalı üretimde kalite kapısı için programatik SEO kalite kontrolü, yapay zekâ cevaplarının kaynak tercihleri için yapay zekâ kaynak analizi sayfalarımıza bakın. İçerik ve teknik SEO süreçlerinizi otomasyonla birlikte kurmak için SEO hizmetimizi inceleyin; diğer geliştirici yazıları blog sayfamızda.

Sık sorulan sorular