Chat API

Tam bir akış 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.

Bu sayfa uygulanmış Public API v1 sözleşmesini belgeler. Çalışma zamanı erişimi Public API'nin dağıtımda etkin olmasına, hesabın etkin API anahtarına ve seçilen modelin kullanılabilir API durumu bildirmesine bağlıdır. Üretim isteğinden önce canlı model listesini kontrol edin.

Güncel Kapsam

Chat API v1 şunları destekler:

• akış olmayan asistan yanıtları

• text/event-stream ile SSE akışlı

• 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 mod

• Dosyalar 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 Kapsam'lar

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

chat:create
chat:read

Settings içinde oluşturulan yeni anahtarlar varsayılan olarak iki kapsam'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": "claude-sonnet-5-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": "claude-sonnet-5-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 Akış 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": "claude-sonnet-5-chat",
    "message": "Write a concise launch plan for a new product image campaign",
    "client_request_id": "chat-stream-001"
  }'

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

Olaylar:

Örnek akış:

event: session.created
data: {"request_id":"req_...","session_id":"session_id","model":"claude-sonnet-5-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 akış 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 akış'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": "claude-sonnet-5-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, Dosyalar 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": "<image-capable-chat-model-id>",
  "message": "Review this product photo and suggest a cleaner editorial direction.",
  "attachments": [
    {
      "file_id": "file_..."
    }
  ]
}

Dosya aynı hesaba ait, kind: "image" değerinde ve kullanılabilir olmalıdır. Placeholder'ı, /api/v1/models girdisinde chat_capabilities içinde görsel eki desteği bildiren güncel bir sohbet modeliyle değiştirin. claude-sonnet-5-chat bu sayfadaki yalnızca metin örneğidir ve bu ek isteğinde kullanılmamalıdır. Desteklemeyen modeller chat_attachment_not_supported döndürür.

İsteğe Bağlı Kontroller

{
  "model": "claude-sonnet-5-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": "claude-sonnet-5-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. İç sağlayıcı 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ı girdi ile yeniden kullanılırsa API idempotency_conflict döndürür.

Akışlı 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

• Dosyalar API

• API Kredileri

• API Hataları ve Limitleri

• OpenAPI ve Şema Sözleşmesi