Ajanlar için Responses API ve Chat Completions: Bir Sözleşme Seçimi

Responses API ile Chat Completions arasındaki fark, hangi uç noktanın daha yeni göründüğünden ziyade, büyük ölçüde konuşma durumunun (conversation state) kime ait olduğu sorusudur. Chat Completions, orkestratörünüzün her adımda tüm messages dizisini yeniden göndermesini gerektirir. Responses ise saklanan bir yanıt kimliğinden (response ID) devam edebilir. TokenLab'in yayınlanmış API belgelerini ve 2026-10-03 tarihindeki canlı model API'sini inceledik; cevap aynı zamanda modelinizin hangi formatları kabul ettiğine de bağlıdır. Bu yüzden bir karar tablosu ile başlıyoruz.

Ajan gereksinimi	Seçim	Neden
Mevcut OpenAI uyumlu sohbet istemcisi, birçok model arasında taşınabilir	Chat Completions (/v1/chat/completions)	API formatları kılavuzuna (2026-10-03 tarihinde gözlemlenmiştir) göre en geniş model uyumluluğu
Bir konuşmayı sunucu tarafında saklanan bir yanıttan devam ettirme	Responses (/v1/responses)	previous_response_id ve store, Responses alanlarıdır
Adımlar arasında keyfi geçmiş düzenlemeleri, budama veya mesaj maskeleme	Chat Completions	Tüm messages dizisinin sahibi sizsiniz
Arka plan yanıtları veya Responses etkinlikleri	Responses	Bunları destekleyen modeller için belgelenmiştir
Devamlılık içeren kalıcı WebSocket bağlantısı	Responses	wss://api.tokenlab.sh/v1/responses
Taşınabilir JSON nesnesi çıktısı	Chat Completions	response_format: {"type": "json_object"}
Model openai_responses listelemiyor	Chat Completions veya modelin yerel formatı	Responses yalnızca onu listeleyen modeller içindir
Claude düşünme blokları, Claude araç kullanımı, prompt-cache alanları	Anthropic Messages (/v1/messages)	Chat Completions bu alanları garanti etmez
Gemini contents, dosyalar, önbelleğe alınmış içerik, Gemini araçları	Gemini (/v1beta/models/:model:generateContent)	Gemini'ye özgü alanları Gemini rotasında tutun

Önemli Çıkarımlar

• Chat Completions, istemci tarafından yönetilen durumdur. Responses, previous_response_id aracılığıyla sunucu referanslı olabilir.
• Araç çağrıları, iç içe geçmiş tool_calls ve role: "tool" mesajlarından, tipli function_call ve function_call_output öğelerine geçer.
• Akış (streaming), choices[0].delta parçalarından adlandırılmış etkinliklere dönüşür ve bir Responses istemcisi ayrıca response.failed ve response.incomplete durumlarını izlemelidir.
• Format desteği modele göredir. 2026-10-03 tarihinde, üç örnek modelimizden sadece gpt-5.6-terra openai_responses kabul ediyordu.
• Bir konuşma içinde asla formatları karıştırmayın. Bir sonraki istekten önce saklanan geçmişi dönüştürün ve doğrulayın.

Responses API vs Chat Completions: aynı görev, iki istek

Tek adımlı bir görev ele alalım: gökyüzünün neden mavi olduğunu iki cümlede açıklayın. API formatları kılavuzundaki (2026-10-03 tarihinde gözlemlenmiştir) istemci kurulumunu kullanarak Chat Completions isteği olarak şu şekildedir:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1",
)

response = client.chat.completions.create(
    model="gpt-5.6-terra",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain why the sky is blue in two sentences."},
    ],
    max_tokens=1000,
)

print(response.choices[0].message.content)

Aynı görev Responses isteği olarak şu şekildedir:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1",
)

response = client.responses.create(
    model="gpt-5.6-terra",
    instructions="You are a helpful assistant.",
    input="Explain why the sky is blue in two sentences.",
    max_output_tokens=1000,
)

print(response.output_text)

Bu basit durumda alanlar bire bir eşleşir. Sistem mesajı üst düzey instructions olur. messages, bir dize veya öğe dizisi kabul eden input olur. max_tokens, max_output_tokens olur.

Yanıt gövdeleri daha fazla farklılık gösterir. Chat Completions, choices[0].message ve bir finish_reason döndürür. Responses, tipli öğelerden oluşan bir output dizisi ve bir status alanı döndürür. Create Response referansı (2026-10-03 tarihinde gözlemlenmiştir); queued, in_progress, completed, incomplete, failed ve cancelled durumlarını listeler ve HTTP isteği başarılı olsa bile status alanını kontrol etmenizi söyler. Kullanım anahtarları da farklıdır: bir tarafta prompt_tokens ve completion_tokens, diğer tarafta input_tokens ve output_tokens. Referans örnekleri sırasıyla 20/9/29 ve 10/12/22 değerlerini gösterir. Bunlar ölçüm değil, örnek yüklerdir.

Bir konuşmayı devam ettirme

Bir soruyu yeni yanıtlamış ve şimdi "Peki ya #4472 numaralı sipariş?" sorusunu alan bir destek ajanı hayal edin. Chat Completions ile yeni kullanıcı mesajını saklanan diziye eklersiniz ve her şeyi yeniden gönderirsiniz. Responses ile önceki yanıtın id değerini iletir ve sadece yeni adımı gönderirsiniz:

{
  "model": "gpt-5.6-terra",
  "previous_response_id": "resp_abc123",
  "input": "What about order #4472?"
}

store varsayılan olarak true değerindedir, bu nedenle siz kapatmadığınız sürece önceki yanıt daha sonra alınmak üzere saklanır. Uygulamanızın, döndürülen id değerini hoplar arasında kalıcı olarak saklaması gerekir. Özel budama veya mesaj maskeleme gerekiyorsa, durumsuz (stateless) format daha doğrudan bir uyum sağlar.

Kaba bir tahmin, durumsuz yeniden göndermenin ajan ölçeğinde neden önemli olduğunu gösterir. 20 çağrının her birinde yeniden gönderilen 10.000 tokenlık bir geçmiş varsayalım. Bu 200.000 girdi tokenı eder. gpt-5.6-terra girdi fiyatı olan 1M token başına 0,60$ üzerinden hesaplanırsa: 200.000 × 0,60 / 1.000.000 = 0,12$ (tahmini; varsayılan token sayıları, önbellekleme yok). Fiyat, 2026-10-02T16:53:30.068Z tarihinde güncellenen fiyatlandırma ile 2026-10-03 tarihinde gözlemlenen canlı model API'sinden gelmektedir.

İki uyarı geçerlidir. Okuduğumuz belgeler, sunucuda tutulan bağlamın girdi tokenı olarak faturalandırılıp faturalandırılmadığını belirtmemektedir, bu nedenle kendi trafiğinizdeki usage değerlerini karşılaştırın. Ayrıca 272K girdi tokenının üzerindeki istekler, tam istek için 2 kat girdi ve 1,5 kat çıktı fiyatıyla ücretlendirilir: 0,60$ ve 3,60$ yerine 1M başına 1,20$ ve 5,40$. Uzun durumsuz geçmişler bu sınırı aşabilir.

Araç çağırma: istek ve yanıt şekli

Her iki format da Structured Outputs & Tool Calling kılavuzundaki (2026-10-03 tarihinde gözlemlenmiştir) döngüyü izler. Araçları gönderin, çağrıyı okuyun, kendi arka ucunuzda çalıştırın, sonucu aynı formatta döndürün ve nihai yanıt gelene kadar tekrarlayın. Şekiller farklılık gösterir.

Chat Completions. Araçlar {"type": "function", "function": {...}} olarak bildirilir. Model, choices[0].message üzerinde tool_calls ile yanıt verir ve finish_reason tool_calls olur. Devam etmek için, tool_calls içeren asistan mesajı ve tool_call_id taşıyan bir role: "tool" mesajı dahil olmak üzere tüm diziyi yeniden gönderirsiniz. Aşağıdaki değerler açıklayıcıdır; lookup_customer kılavuzda kullanılan araç adıdır:

{
  "model": "gpt-5.6-terra",
  "messages": [
    {"role": "user", "content": "Look up ana@example.com"},
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [
        {
          "id": "call_xyz789",
          "type": "function",
          "function": {"name": "lookup_customer", "arguments": "{\"email\": \"ana@example.com\"}"}
        }
      ]
    },
    {"role": "tool", "tool_call_id": "call_xyz789", "content": "{\"status\": \"active\"}"}
  ]
}

Responses. Model, output içinde her biri bir call_id, name ve arguments taşıyan function_call öğeleriyle yanıt verir. Sonucu bir function_call_output girdi öğesi olarak döndürür ve önceki yanıtı işaret edersiniz:

{
  "model": "gpt-5.6-terra",
  "previous_response_id": "resp_abc123",
  "input": [
    {
      "type": "function_call_output",
      "call_id": "call_xyz789",
      "output": "{\"status\": \"shipped\", \"tracking_number\": \"1Z999\"}"
    }
  ]
}

Ara asistan aracı mesajını asla yeniden oluşturmazsınız. parallel_tool_calls her iki formatta da mevcuttur. Create Response referansında varsayılan olarak true değerindedir. Chat referansı ise onu varsayılan olmadan listeler ve "seçilen model tarafından desteklendiğinde" geçerli olduğunu belirtir.

Bir boşluk bulduk. Okuduğumuz sayfalar, Responses tools ve tool_choice özelliklerini sadece genel terimlerle tanımlıyor. Araç şemalarını taşımadan önce, Create Response referansındaki araç tanımı şeklini okuyun ve hedef modelinizde test edin. Ayrıca kılavuzdaki şu kuralları aklınızda bulundurun:

• TokenLab, yerleşik araçları formatlar arasında dönüştürmez.
• Herhangi bir yan etkiden önce araç argümanlarını doğrulayın.
• Araç yürütmeyi idempotent (eşgüçlü) hale getirin, çünkü bir istemci yeniden denemesi aynı çağrıyı tekrarlayabilir.
• Kendi izin kontrollerinizi uygulayın.

Akış (Streaming): bir istemcinin işlemesi gereken etkinlikler

Chat Completions, SSE parçalarını akıtır. İstemciniz choices[0].delta.content değerini okur, finish_reason değerini kaydeder ve choices içermeyen parçaları atlar. stream_options={"include_usage": True} ile kullanım bilgisi böyle bir parçada gelir. Streaming kılavuzu (2026-10-03 tarihinde gözlemlenmiştir), stop değerini tamamlandı, length değerini token sınırı ve tool_calls değerini araçları çalıştırma isteği olarak ele alır.

Responses, adlandırılmış etkinlikleri akıtır. Kılavuzun tüketicisi şunları işler:

• Eklenecek metin için response.output_text.delta
• Başarı işareti için response.completed
• Terminal sorunları olarak response.failed, response.incomplete ve error

import os
from openai import OpenAI

with OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1",
    timeout=30.0,
    max_retries=0,
) as client:
    completed = False
    with client.responses.create(
        model="gpt-5.6-terra",
        input="Write a short poem.",
        stream=True,
    ) as stream:
        for event in stream:
            if event.type == "response.output_text.delta":
                print(event.delta, end="", flush=True)
            elif event.type == "response.completed":
                completed = True
            elif event.type in {"response.failed", "response.incomplete", "error"}:
                raise RuntimeError(f"Stream ended with {event.type}")
    if not completed:
        raise RuntimeError("Stream closed before response.completed")

Kılavuzdan üç istemci kuralı çıkar:

1. İlk etkinlik geldikten sonra, kesintiye uğrayan bir akış tamamlanmamış sayılır ve otomatik olarak yeniden başlatılmaz. Yardımcı oluyorsa kısmi çıktıyı saklayın, ancak tamamlandı olarak işaretlemeyin. Tekrarlanan bir istek farklılık gösterebilir ve tekrar maliyet oluşturabilir.
2. SSE'yi ayrıştırmak için SDK'yı kullanın, çünkü bir ağ parçası mutlaka tam bir etkinlik değildir.
3. Kullanıcı durduğunda veya bağlantıyı kestiğinde yukarı yönlü akışı iptal edin ve anahtarı sunucunuzda tutun.

Responses ayrıca wss://api.tokenlab.sh/v1/responses adresinde bir WebSocket sunar. Oradaki yanıtlar her zaman akıtılır, background ve response.cancel desteklenmez, her bağlantı aynı anda bir aktif yanıt çalıştırır ve bir bağlantı 60 dakikaya kadar sürer. Etkinlikler, yanıt kapsamlı bir sequence_number taşır. error olarak adlandırılan akış etkinlikleri düz nesnelerdir, bağlantı ve protokol hataları ise iç içe geçmiş bir error nesnesi kullanır, bu nedenle her iki şekli de işleyin.

Göndermeden önce bir modelin hangi formatları kabul ettiğini kontrol edin

Get a Model referansında (2026-10-03 tarihinde gözlemlenmiştir) açıklandığı gibi, model sayfasından veya GET /v1/models/{model} üzerinden tokenlab.accepted_request_formats değerini okuyun:

curl "https://api.tokenlab.sh/v1/models/gpt-5.6-terra"

Yanıt, accepted_request_formats, pricing, sınırlar ve lifecycle içeren bir tokenlab nesnesi içerir. Değerler, hata kılavuzunda açıklandığı gibi uç noktalarla eşleşir: openai_chat_completions, /v1/chat/completions ile; openai_responses, /v1/responses ile; anthropic_messages, /v1/messages ile ve gemini_generate_content, /v1beta/models/{model}:generateContent ile. Kabul edilen bir format yalnızca uç noktayı doğrular. Bireysel araçlar ve alanlar modele göre hala değişebilir.

Bu makalenin referans aldığı üç modeli 2026-10-03 tarihinde canlı model API'sine karşı kontrol ettik:

Model	Kabul edilen formatlar	Maks girdi / çıktı tokenı	1M girdi / çıktı başına fiyat (USD)	Kaynak
gpt-5.6-terra	openai_chat_completions, openai_responses	1.050.000 / 128.000	0.60 / 3.60 (272K'ya kadar girdi)	canlı API
claude-sonnet-5	anthropic_messages, openai_chat_completions	1.000.000 / 128.000	0.90 / 4.50	canlı API
gemini-3.5-flash	gemini_generate_content, openai_chat_completions	1.048.576 / 65.536	0.75 / 4.50	canlı API

Üçü de aktif yaşam döngüsü aşamasındaydı ve yerini alacak bir model yoktu; fiyatlandırma 2026-10-02T16:53:30.068Z tarihinde güncellenmişti. Yani bugün sadece gpt-5.6-terra bir Responses isteği alıyor. Diğer ikisi Chat Completions veya kendi yerel rotaları üzerinden çalışıyor. Göndermeden önce tekrar kontrol edin, çünkü yaşam döngüsü ve fiyatlar değişebilir.

Hata işleme de burada önemlidir. Bir oluşturma çağrısında yanlış yazılmış bir model 400 model_not_found döndürür ve did_you_mean içerebilir. Bilinmeyen bir kimlik hakkında GET /v1/models/{model} sorgusu 404 model_not_found döndürür. retryable: false içeren bir 503 all_channels_failed, isteği tekrarlamanın yardımcı olmayacağı anlamına gelir. Ürününüzün bunu yapma izni yoksa modelleri otomatik olarak değiştirmeyin.

Geçiş kontrol listesi: Responses API vs Chat Completions

Bir ajanı Chat Completions'tan Responses'a taşırken bu sırayı kullanın.

1. Modelin openai_responses listelediğini doğrulayın. Listelemiyorsa burada durun. Chat Completions'ta kalmak desteklenen yoldur.
2. Bir kesim sınırı seçin. Yeni konuşmaları Responses üzerinde başlatın. Canlı bir iş parçacığını (thread) orta yerinde değiştirmeyin, çünkü formatlar durumu ve araç çağrılarını farklı şekilde temsil eder.
3. Saklanan geçmişi bilinçli olarak dönüştürün. Eski iş parçacıklarını taşımanız gerekiyorsa, bir sonraki istekten önce bunları uygulamanızda dönüştürün ve doğrulayın.
4. Temel alanları yeniden adlandırın. messages, input olur; sistem veya geliştirici mesajları instructions olur ve max_tokens veya max_completion_tokens, max_output_tokens olur.
5. Araç döngüsünü yeniden yazın. choices[0].message.tool_calls ayrıştırmasını function_call öğeleriyle değiştirin ve role: "tool" mesajlarını call_id ile anahtarlanmış function_call_output öğeleriyle değiştirin.
6. Yanıt kimliklerini kalıcı hale getirin. previous_response_id değerini iletebilmek için her id değerini saklayın. store ve saklama süresine önceden karar verin ve TokenLab'in saklanan yanıtları ne kadar süre tuttuğunu kontrol edin, çünkü okuduğumuz sayfalar bunu belirtmiyor.
7. Akış tüketicisini yeniden yazın. response.output_text.delta, response.completed, response.failed, response.incomplete ve error durumlarını işleyin. response.completed içermeyen kapalı bir akışı hata olarak kabul edin.
8. status alanını kontrol edin. Bir HTTP başarısı hala incomplete veya failed durumunu taşıyabilir.
9. Taşınmayabilecek parametreleri denetleyin. Create Response sayfası temperature, top_p, tools, parallel_tool_calls, reasoning ve text değerlerini listeler. n, logprobs, logit_bias, frequency_penalty, presence_penalty, seed, top_k, stop, user veya stream_options değerlerini listelemez. Güvenmeden önce her birini modelinizde doğrulayın. TokenLab bilinmeyen alanları iletebilir, ancak bu modelin onları kabul ettiği anlamına gelmez.
10. JSON çıktısını eşleyin. Chat, response_format kullanır. Responses, text nesnesini kullanır ve text.format desteği modele bağlıdır.
11. Eksik uç noktalar etrafında plan yapın. İptal, girdi öğeleri ve girdi tokenları uç noktaları şu anda mevcut değildir. Saklanan bir yanıtı silmek üretimi iptal etmez.
12. Yeniden denemeler kapalıyken tekrar testi yapın. max_retries=0 değerini koruyun ve bir yeniden denemenin ne zaman güvenli olduğuna kendi kodunuzda karar verin. Zaman aşımına uğrayan üretimler otomatik olarak tekrar oynatılmamalıdır.

SSS

Claude Sonnet 5 veya Gemini 3.5 Flash'a bir Responses isteği gönderebilir miyim?

2026-10-03 tarihindeki canlı model API'sine göre hayır. claude-sonnet-5, anthropic_messages ve openai_chat_completions listeler. gemini-3.5-flash, gemini_generate_content ve openai_chat_completions listeler. Chat Completions veya yerel rotayı kullanın ve göndermeden önce accepted_request_formats değerini tekrar kontrol edin.

previous_response_id kullandığımda önceki adımlar için ödeme yapmayı bırakıyor muyum?

Okuduğumuz sayfalar bunu belirtmiyor. Sunucunun saklanan bir yanıttan devam edebileceğini belgeliyorlar, ancak geri yüklenen bağlamın nasıl faturalandırıldığını belirtmiyorlar. Tasarruf etmeyi planlamadan önce birkaç çok adımlı çağrı çalıştırın ve usage alanlarını durumsuz temel değerlerinizle karşılaştırın.

Bir konuşmanın ortasında formatları değiştirebilir miyim?

Hayır. TokenLab'in kılavuzları, her format durumu ve araç çağrılarını farklı şekilde temsil ettiği için konuşma başına bir format tutulmasını söylüyor. Saklanan geçmişi taşımanız gerekiyorsa, bir sonraki isteği göndermeden önce bunu uygulamanızda dönüştürün ve doğrulayın.

Çalışan bir Responses isteğini nasıl iptal ederim?

Bir iptal uç noktası şu anda mevcut değildir. Saklanan bir yanıtı silmek üretimi iptal etmez ve WebSocket yanıtları response.cancel desteklemez. Akışlar için, kullanıcı durduğunda veya bağlantıyı kestiğinde yukarı yönlü akışı sunucunuzdan kapatın.

Uç noktaları değiştirmeden önce TokenLab model kataloğunu açın ve ajanınızın çağırdığı tam model için accepted_request_formats değerini doğrulayın.