Chat API

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

Chat API ist sessionbasiert. Lasse session_id weg, um eine neue API-Chat-Session zu starten. Übergib eine zurückgegebene session_id, um dieselbe API-erstellte Session fortzusetzen.

Aktueller Umfang

Chat API v1 unterstützt:

• nicht streamende Assistant-Antworten
• SSE-Streaming mit text/event-stream
• API-erstellte Chat-Sessions
• Reservierung von Account Credits und finale tokenbasierte Abrechnung
• optionale Websuche, Reasoning Effort und Thought Mode, wenn das gewählte Modell sie unterstützt
• Bildanhänge über Files API-file_id-Werte

Chat API v1 unterstützt nicht:

• vom Nutzer gelieferte rohe messages-History
• Fortsetzen von Studio-only-Chat-Sessions
• beliebige externe Anhangs-URLs
• Chat-Webhook-Events

Erforderliche Scopes

Nutze einen API Key mit:

chat:create
chat:read

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

Chat Completion 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": "gpt-5-2-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": "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 streamen

Nutze POST /api/v1/chat/completions/stream, wenn dein Server Assistant-Deltas 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": "gpt-5-2-chat",
    "message": "Schreibe einen knappen Launch-Plan für eine neue Produktbild-Kampagne",
    "client_request_id": "chat-stream-001"
  }'

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

Events:

Beispielstream:

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":"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-Event ein Fehler auftritt, sendet der Stream event: error und schließt dann:

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

Wenn der Client vor Abschluss trennt, stoppt Rivya den laufenden Generation-Stream, sofern möglich. Teil-Deltas werden nicht als finale Assistant-Nachricht gespeichert. Wenn der Server message.completed bereits gespeichert hat, kann das finale Ergebnis später mit GET /api/v1/chat/sessions/{sessionId} gelesen werden.

Session 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": "gpt-5-2-chat",
    "session_id": "session_id",
    "message": "Mache daraus jetzt eine Ausführungscheckliste mit 5 Schritten."
  }'

Die Session muss zum selben Rivya-Konto gehören und von der Public API erstellt worden sein. Studio-only-Chat-Sessions werden von Chat API weder zurückgegeben noch fortgesetzt.

Bildanhänge

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

1. Lade ein Bild mit POST /api/v1/files hoch.
2. Nutze die zurückgegebene id als attachments[].file_id.

{
  "model": "gpt-5-2-chat",
  "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. Modelle, die Bildanhänge nicht unterstützen, geben chat_attachment_not_supported zurück.

Optionale Controls

{
  "model": "gpt-5-2-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 Key, 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": "gpt-5-2-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"
    }
  ]
}

Session abrufen

Nutze GET /api/v1/chat/sessions/{sessionId}, um eine API-erstellte Session 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 Assistant-Nachrichten. Sie legt keine internen Provider-Felder offen.

Idempotenz

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

Wenn ein Retry denselben Key und denselben Body verwendet, kann Rivya die gespeicherte Antwort zurückgeben, ohne eine weitere Nachricht zu erstellen oder erneut Credits zu verbrauchen. Wenn derselbe Key mit anderem Input wiederverwendet wird, gibt die API idempotency_conflict zurück.

Bei Streaming-Retries spielt Rivya historische Token-Deltas nicht erneut ab. Ein abgeschlossener Replay gibt eine minimale SSE-Sequenz mit session.created, message.completed, usage.completed und done zurück.

Häufige Fehler

Verwandte Seiten

• API Models
• Files API
• API Credits
• API-Fehler und Limits
• OpenAPI- und Schema-Vertrag