Chat API

Nutze POST /api/v1/chat/completions für eine vollständige Chatantwort oder POST /api/v1/chat/completions/stream für Server-Sent Events.

Die Chat API arbeitet sitzungsbasiert. Lasse session_id weg, um eine neue API-Chatsitzung zu starten. Übergib eine zurückgegebene session_id, um dieselbe über die API erstellte Sitzung fortzusetzen.

Diese Seite dokumentiert den implementierten Vertrag der Public API v1. Der Zugriff zur Laufzeit setzt weiterhin voraus, dass die Public API für die Bereitstellung aktiviert ist, das Konto einen aktiven API-Schlüssel besitzt und das gewählte Modell einen verfügbaren API-Status meldet. Prüfe vor einer Produktionsanfrage die aktuelle Modellliste.

Aktueller Umfang

Chat API v1 unterstützt:

• nicht streamende Assistant-Antworten

• SSE-Übertragung mit text/event-stream

• über die API erstellte Chatsitzungen

• Reservierung von Konto-Credits und abschließende tokenbasierte Abrechnung

• optionale Websuche, Reasoning Effort und Thought Mode, wenn das gewählte Modell sie unterstützt

• Bildanhänge über file_id-Werte der Datei-API

Chat API v1 unterstützt nicht:

• vom Nutzer bereitgestellter unverarbeiteter messages-Verlauf

• Fortsetzen von Chatsitzungen, die nur in Studio bestehen

• beliebige externe Anhangs-URLs

• Webhook-Ereignisse für Chat

Erforderliche Scopes

Nutze einen API Key mit:

chat:create
chat:read

Neue Schlüssel, die in den Einstellungen erstellt werden, enthalten standardmäßig beide Berechtigungsbereiche. Ältere Schlüssel müssen möglicherweise neu erstellt werden, bevor du die Chat API aufrufst.

Chatantwort erstellen

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": "Schreibe einen knappen Launch-Plan für eine neue Produktbild-Kampagne",
    "client_request_id": "chat-001"
  }'

Antwort:

{
  "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
  }
}

Chatantwort fortlaufend übertragen

Nutze POST /api/v1/chat/completions/stream, wenn dein Server Teilstücke der Assistentenantwort direkt beim Eintreffen erhalten soll:

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": "Schreibe einen knappen Launch-Plan für eine neue Produktbild-Kampagne",
    "client_request_id": "chat-stream-001"
  }'

Fortlaufend übertragene Antworten verwenden Content-Type: text/event-stream; charset=utf-8.

Events:

Beispielstream:

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":"Entwurf ","index":0}

event: message.completed
data: {"request_id":"req_...","session_id":"session_id","message":{"id":"assistant_message_id","role":"assistant","content":"Entwurf ...","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}

Wenn nach dem ersten SSE-Ereignis ein Fehler auftritt, sendet die Übertragung event: error und wird anschließend geschlossen:

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

Wenn der Client die Verbindung vor Abschluss trennt, stoppt Rivya nach Möglichkeit die laufende Generierungsübertragung. Teilstücke werden nicht als abschließende Assistentenantwort gespeichert. Hat der Server message.completed bereits gespeichert, kann das endgültige Ergebnis später mit GET /api/v1/chat/sessions/{sessionId} gelesen werden.

Sitzung fortsetzen

Nutze die zurückgegebene session_id:

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": "Mache daraus jetzt eine Ausführungscheckliste mit fünf Schritten."
  }'

Die Sitzung muss zum selben Rivya-Konto gehören und von der Public API erstellt worden sein. Chatsitzungen, die nur in Studio bestehen, werden von der Chat API weder zurückgegeben noch fortgesetzt.

Bildanhänge

Chat-Anhänge verwenden Einträge der Datei-API, keine externen URLs.

1. Lade ein Bild mit POST /api/v1/files hoch.

2. Nutze die zurückgegebene id als attachments[].file_id.

{
  "model": "<image-capable-chat-model-id>",
  "message": "Prüfe dieses Produktfoto und schlage eine sauberere redaktionelle Richtung vor.",
  "attachments": [
    {
      "file_id": "file_..."
    }
  ]
}

Die Datei muss zum selben Konto gehören, kind: "image" haben und verfügbar sein. Ersetze den Platzhalter durch ein aktuell verfügbares Chatmodell, dessen Eintrag in /api/v1/models Bildanhänge unter chat_capabilities ausweist. claude-sonnet-5-chat ist auf dieser Seite das reine Textbeispiel und darf für diese Anfrage mit Anhang nicht verwendet werden. Nicht kompatible Modelle geben chat_attachment_not_supported zurück.

Optionale Controls

{
  "model": "claude-sonnet-5-chat",
  "message": "Vergleiche drei Launch-Optionen.",
  "enable_web_search": false,
  "reasoning_effort": "default",
  "thought_mode": "default"
}

Control-Unterstützung variiert je nach Modell. Lies /api/v1/models und prüfe chat_capabilities, bevor du Controls in deiner UI anbietest.

Sessions auflisten

Nutze GET /api/v1/chat/sessions mit einem Schlüssel, der chat:read enthält.

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

Dies gibt nur API-erstellte Sessions zurück:

{
  "object": "list",
  "data": [
    {
      "id": "session_id",
      "object": "chat.session",
      "model": "claude-sonnet-5-chat",
      "tool_slug": null,
      "title": "Schreibe einen knappen 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"
    }
  ]
}

Sitzung abrufen

Nutze GET /api/v1/chat/sessions/{sessionId}, um eine über die API erstellte Sitzung und ihre gespeicherten Nachrichten zu lesen.

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

Die Antwort enthält gespeicherte Nutzer- und Assistentennachrichten. Sie legt keine internen Anbieterfelder offen.

Idempotenz

Nutze Idempotency-Key für jede produktive Anfrage an POST /api/v1/chat/completions und POST /api/v1/chat/completions/stream.

Wenn eine Wiederholung denselben Schlüssel und denselben Anfragekörper verwendet, kann Rivya die gespeicherte Antwort zurückgeben, ohne eine weitere Nachricht zu erstellen oder erneut Credits zu verbrauchen. Wird derselbe Schlüssel mit einer anderen Eingabe wiederverwendet, gibt die API idempotency_conflict zurück.

Bei wiederholten SSE-Anfragen spielt Rivya frühere Token-Teilstücke nicht erneut ab. Eine abgeschlossene Wiederholung gibt eine minimale SSE-Sequenz mit session.created, message.completed, usage.completed und done zurück.

Häufige Fehler

Verwandte Seiten

• API-Modelle

• Datei-API

• API-Credits

• API-Fehler und Limits

• OpenAPI- und Schema-Vertrag