Chat API

Folosește POST /api/v1/chat/completions pentru un răspuns complet sau POST /api/v1/chat/completions/stream pentru Server-Sent Events.

Chat API funcționează pe bază de sesiuni. Omite session_id pentru a porni o sesiune nouă și trimite valoarea returnată pentru a continua aceeași sesiune creată prin API.

Această pagină documentează contractul Public API v1 implementat. Accesul la rulare depinde în continuare de activarea Public API pentru implementare, de o cheie API activă în cont și de starea API disponibilă a modelului ales. Verifică lista actuală de modele înainte de o cerere de producție.

Domeniul actual

Chat API v1 acceptă:

• răspunsuri complete ale asistentului

• transmitere progresivă prin SSE cu text/event-stream

• sesiuni de chat create prin API

• rezervarea creditelor din cont și decontarea finală pe baza tokenurilor

• căutare web opțională, nivel de raționament și mod de gândire, atunci când modelul ales le acceptă

• imagini atașate prin valori file_id din Files API

Chat API v1 nu acceptă:

• istoric brut messages furnizat de utilizator

• continuarea sesiunilor create exclusiv în Studio

• adrese URL arbitrare pentru fișiere externe

• evenimente webhook pentru Chat

Permisiuni necesare

Folosește o cheie API cu:

chat:create
chat:read

Cheile noi create în Settings includ implicit ambele permisiuni. Cheile mai vechi pot necesita recreare înainte de apelarea Chat API.

Creează un răspuns Chat

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": "Scrie un plan concis de lansare pentru o campanie nouă cu imagini de produs",
    "client_request_id": "chat-001"
  }'

Răspuns:

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

Transmite progresiv un răspuns Chat

Folosește POST /api/v1/chat/completions/stream când serverul tău trebuie să primească fragmentele răspunsului pe măsură ce sosesc:

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": "Scrie un plan concis de lansare pentru o campanie nouă cu imagini de produs",
    "client_request_id": "chat-stream-001"
  }'

Răspunsurile transmise progresiv folosesc Content-Type: text/event-stream; charset=utf-8.

Evenimente:

Exemplu de flux SSE:

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

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

Dacă apare o eroare după primul eveniment SSE, fluxul trimite event: error, apoi se închide:

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

Dacă clientul se deconectează înainte de finalizare, Rivya oprește fluxul în curs atunci când este posibil. Fragmentele parțiale nu sunt salvate drept mesaj final. Dacă serverul a confirmat deja message.completed, rezultatul poate fi citit ulterior prin GET /api/v1/chat/sessions/{sessionId}.

Continuă o sesiune

Folosește valoarea session_id returnată:

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": "Transformă acum planul într-o listă de verificare cu 5 pași."
  }'

Sesiunea trebuie să aparțină aceluiași cont Rivya și să fi fost creată prin Public API. Chat API nu returnează și nu continuă sesiunile create exclusiv în Studio.

Imagini atașate

Imaginile atașate folosesc înregistrări Files API, nu adrese URL externe.

1. Încarcă o imagine prin POST /api/v1/files.

2. Folosește valoarea id returnată ca attachments[].file_id.

{
  "model": "<image-capable-chat-model-id>",
  "message": "Evaluează această fotografie de produs și sugerează o direcție editorială mai curată.",
  "attachments": [
    {
      "file_id": "file_..."
    }
  ]
}

Fișierul trebuie să aparțină aceluiași cont, să aibă kind: "image" și să fie disponibil. Înlocuiește placeholderul cu un model chat disponibil a cărui intrare /api/v1/models declară suport pentru atașamente imagine în chat_capabilities. claude-sonnet-5-chat este exemplul doar-text folosit în restul paginii și nu trebuie utilizat pentru această cerere cu atașament. Modelele fără suport returnează chat_attachment_not_supported.

Opțiuni suplimentare

{
  "model": "claude-sonnet-5-chat",
  "message": "Compară trei opțiuni de lansare.",
  "enable_web_search": false,
  "reasoning_effort": "default",
  "thought_mode": "default"
}

Opțiunile acceptate diferă în funcție de model. Citește /api/v1/models și verifică chat_capabilities înainte să afișezi controalele în interfața ta.

Listează sesiunile

Folosește GET /api/v1/chat/sessions cu o cheie care include chat:read.

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

Acest endpoint returnează numai sesiunile create prin API:

{
  "object": "list",
  "data": [
    {
      "id": "session_id",
      "object": "chat.session",
      "model": "claude-sonnet-5-chat",
      "tool_slug": null,
      "title": "Scrie un plan concis de lansare...",
      "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"
    }
  ]
}

Obține o sesiune

Folosește GET /api/v1/chat/sessions/{sessionId} pentru a citi o sesiune creată prin API și mesajele sale confirmate.

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

Răspunsul include mesajele confirmate ale utilizatorului și asistentului. Nu expune câmpurile interne ale furnizorului.

Idempotență

Folosește Idempotency-Key pentru fiecare cerere de producție POST /api/v1/chat/completions și POST /api/v1/chat/completions/stream.

Dacă o nouă încercare folosește aceeași cheie și același corp al cererii, Rivya poate returna răspunsul stocat fără să creeze alt mesaj sau să consume din nou credite. Dacă aceeași cheie este refolosită cu intrări diferite, API-ul returnează idempotency_conflict.

La reluarea transmiterii progresive, Rivya nu repetă fragmentele istorice de tokenuri. Reluarea unei cereri finalizate întoarce o secvență SSE minimă cu session.created, message.completed, usage.completed și done.

Erori comune

Pagini asociate

• Modele API

• Files API

• Credite API

• Erori și limite API

• Contract OpenAPI și schemă