Chat API

Tam bir stream olmayan sohbet yanıtı için POST /api/v1/chat/completions, Server-Sent Events için POST /api/v1/chat/completions/stream kullanın.

Chat API oturum tabanlıdır. Yeni bir API sohbet oturumu başlatmak için session_id alanını atlayın. Aynı API tarafından oluşturulan oturuma devam etmek için dönen session_id değerini gönderin.

Güncel Kapsam

Chat API v1 şunları destekler:

• stream olmayan asistan yanıtları
• text/event-stream ile SSE streaming
• API tarafından oluşturulan sohbet oturumları
• hesap kredisi rezervasyonu ve token tabanlı nihai mutabakat
• seçilen model desteklediğinde isteğe bağlı web araması, reasoning effort ve thought mode
• Files API file_id değerleriyle görüntü ekleri

Chat API v1 şunları desteklemez:

• kullanıcının sağladığı ham messages geçmişi
• yalnızca Studio'da oluşturulmuş sohbet oturumlarına devam etme
• rastgele harici ek URL'leri
• Chat webhook olayları

Gerekli Scope'lar

Şu scope'lara sahip bir API anahtarı kullanın:

chat:create
chat:read

Settings içinde oluşturulan yeni anahtarlar varsayılan olarak iki scope'u da içerir. Daha eski anahtarların Chat API çağrısından önce yeniden oluşturulması gerekebilir.

Chat Completion Oluşturma

curl https://rivya.ai/api/v1/chat/completions \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: chat-turn-001" \
  -d '{
    "model": "gpt-5-2-chat",
    "message": "Write a concise launch plan for a new product image campaign",
    "client_request_id": "chat-001"
  }'

Yanıt:

{
  "id": "chatcmpl_...",
  "object": "chat.completion",
  "session_id": "session_id",
  "model": "gpt-5-2-chat",
  "created_at": "2026-05-11T00:00:00.000Z",
  "message": {
    "id": "assistant_message_id",
    "role": "assistant",
    "content": "..."
  },
  "usage": {
    "input_tokens": 1200,
    "output_tokens": 320,
    "total_tokens": 1520
  },
  "credits": {
    "reserved": 3,
    "final": 2
  }
}

Chat Completion Stream Etme

Sunucunuz asistan delta'larını geldikçe almak istediğinde POST /api/v1/chat/completions/stream kullanın:

curl -N https://rivya.ai/api/v1/chat/completions/stream \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -H "Idempotency-Key: chat-stream-001" \
  -d '{
    "model": "gpt-5-2-chat",
    "message": "Write a concise launch plan for a new product image campaign",
    "client_request_id": "chat-stream-001"
  }'

Streaming yanıtları Content-Type: text/event-stream; charset=utf-8 kullanır.

Olaylar:

Örnek stream:

event: session.created
data: {"request_id":"req_...","session_id":"session_id","model":"gpt-5-2-chat"}

event: message.delta
data: {"request_id":"req_...","session_id":"session_id","delta":"Draft ","index":0}

event: message.completed
data: {"request_id":"req_...","session_id":"session_id","message":{"id":"assistant_message_id","role":"assistant","content":"Draft ...","created_at":"2026-05-11T00:00:00.000Z"}}

event: usage.completed
data: {"request_id":"req_...","session_id":"session_id","usage":{"input_tokens":1200,"output_tokens":320,"total_tokens":1520},"credits":{"reserved":3,"final":2}}

event: done
data: {"request_id":"req_...","ok":true}

İlk SSE olayından sonra hata oluşursa stream event: error gönderir ve kapanır:

event: error
data: {"error":{"code":"internal_error","message":"The request could not be completed.","requestId":"req_..."}}

İstemci tamamlanmadan önce bağlantıyı keserse Rivya, mümkün olduğunda devam eden üretim stream'ini durdurur. Kısmi delta'lar nihai asistan mesajı olarak kaydedilmez. Sunucu message.completed kaydını zaten tamamladıysa nihai sonuç daha sonra GET /api/v1/chat/sessions/{sessionId} ile okunabilir.

Oturuma Devam Etme

Dönen session_id değerini kullanın:

curl https://rivya.ai/api/v1/chat/completions \
  -H "Authorization: Bearer rvya_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: chat-turn-002" \
  -d '{
    "model": "gpt-5-2-chat",
    "session_id": "session_id",
    "message": "Now turn that into a 5-step execution checklist."
  }'

Oturum aynı Rivya hesabına ait olmalı ve Public API tarafından oluşturulmuş olmalıdır. Yalnızca Studio'da oluşturulmuş sohbet oturumları Chat API tarafından döndürülmez veya devam ettirilmez.

Görüntü Ekleri

Chat ekleri harici URL'leri değil, Files API kayıtlarını kullanır.

1. POST /api/v1/files ile bir görüntü yükleyin.
2. Dönen id değerini attachments[].file_id olarak kullanın.

{
  "model": "gpt-5-2-chat",
  "message": "Review this product photo and suggest a cleaner editorial direction.",
  "attachments": [
    {
      "file_id": "file_..."
    }
  ]
}

Dosya aynı hesaba ait olmalı, kind: "image" değerine sahip olmalı ve kullanılabilir durumda olmalıdır. Görüntü eklerini desteklemeyen modeller chat_attachment_not_supported döndürür.

İsteğe Bağlı Kontroller

{
  "model": "gpt-5-2-chat",
  "message": "Compare three launch options.",
  "enable_web_search": false,
  "reasoning_effort": "default",
  "thought_mode": "default"
}

Kontrol desteği modele göre değişir. Kendi UI'nizde kontrolleri göstermeden önce /api/v1/models okuyun ve chat_capabilities alanını kontrol edin.

Oturumları Listeleme

chat:read içeren bir anahtarla GET /api/v1/chat/sessions kullanın.

curl https://rivya.ai/api/v1/chat/sessions \
  -H "Authorization: Bearer rvya_sk_..."

Bu yalnızca API tarafından oluşturulan oturumları döndürür:

{
  "object": "list",
  "data": [
    {
      "id": "session_id",
      "object": "chat.session",
      "model": "gpt-5-2-chat",
      "tool_slug": null,
      "title": "Write a concise launch plan...",
      "controls": {
        "enable_web_search": false,
        "reasoning_effort": null,
        "thought_mode": null
      },
      "created_at": "2026-05-11T00:00:00.000Z",
      "updated_at": "2026-05-11T00:00:00.000Z",
      "last_message_at": "2026-05-11T00:00:00.000Z"
    }
  ]
}

Oturumu Alma

API tarafından oluşturulan bir oturumu ve kaydedilmiş mesajlarını okumak için GET /api/v1/chat/sessions/{sessionId} kullanın.

curl https://rivya.ai/api/v1/chat/sessions/session_id \
  -H "Authorization: Bearer rvya_sk_..."

Yanıt, kaydedilmiş kullanıcı ve asistan mesajlarını içerir. İç provider alanlarını göstermez.

İdempotency

Her üretim POST /api/v1/chat/completions ve POST /api/v1/chat/completions/stream isteğinde Idempotency-Key kullanın.

Yeniden deneme aynı anahtar ve aynı gövdeyle yapılırsa Rivya başka bir mesaj oluşturmadan veya yeniden kredi tüketmeden saklanan yanıtı döndürebilir. Aynı anahtar farklı input ile yeniden kullanılırsa API idempotency_conflict döndürür.

Streaming yeniden denemelerinde Rivya geçmiş token delta'larını yeniden oynatmaz. Tamamlanmış bir replay, session.created, message.completed, usage.completed ve done içeren minimal bir SSE dizisi döndürür.

Yaygın Hatalar

İlgili Sayfalar

• API Modelleri
• Files API
• API Kredileri
• API Hataları ve Limitleri
• OpenAPI ve Şema Sözleşmesi