Foloseste Rivya Chat API pentru ture non-streaming sau SSE, sesiuni create prin API, atasamente imagine file_id si decontare a creditelor pe baza de tokeni.

Foloseste POST /api/v1/chat/completions pentru un raspuns complet de chat non-streaming sau POST /api/v1/chat/completions/stream pentru Server-Sent Events.

Chat API este bazat pe sesiuni. Omite session_id pentru a porni o sesiune noua de chat API. Trimite un session_id returnat pentru a continua aceeasi sesiune creata prin API.

Scope curent

Chat API v1 accepta:

raspunsuri de asistent non-streaming
streaming SSE cu text/event-stream
sesiuni de chat create prin API
rezervare de credite din cont si decontare finala pe baza de tokeni
cautare web optionala, efort de rationament si mod de gandire atunci cand modelul selectat le accepta
atasamente imagine prin valori file_id din Files API

Chat API v1 nu accepta:

istoric brut messages furnizat de utilizator
continuarea sesiunilor exclusiv Studio
URL-uri arbitrare pentru atasamente externe
evenimente webhook pentru Chat

Scope-uri necesare

Foloseste o cheie API cu:

chat:create
chat:read

Cheile noi create in Settings includ implicit ambele scope-uri. Cheile mai vechi pot trebui recreate inainte de a apela Chat API.

Creeaza un chat completion

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

Raspuns:

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

Transmite un chat completion in streaming

Foloseste POST /api/v1/chat/completions/stream cand serverul tau vrea delta-uri de asistent pe masura 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": "gpt-5-2-chat",
    "message": "Scrie un plan concis de lansare pentru o campanie noua de imagini de produs",
    "client_request_id": "chat-stream-001"
  }'

Raspunsurile streaming folosesc Content-Type: text/event-stream; charset=utf-8.

Evenimente:

Eveniment	Semnificatie
`session.created`	Cheia API, modelul, sesiunea, atasamentele, limita de rata si verificarile de rezervare a creditelor au trecut.
`message.delta`	Un delta de afisare pentru mesajul asistentului. Acesta nu este inca un mesaj confirmat.
`message.completed`	Mesajul asistentului a fost confirmat in sesiunea creata prin API.
`usage.completed`	Utilizarea tokenilor si creditele finale au fost decontate.
`heartbeat`	Eveniment keepalive in pauze lungi.
`error`	Pachet public de eroare API pentru un esec dupa pornirea streamingului.
`done`	Streamul s-a incheiat cu succes.

Exemplu de 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":"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}

Daca apare o eroare dupa primul eveniment SSE, streamul trimite event: error si apoi se inchide:

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

Daca clientul se deconecteaza inainte de finalizare, Rivya opreste streamul de generare in curs atunci cand este posibil. Delta-urile partiale nu sunt salvate ca mesaj final de asistent. Daca serverul a confirmat deja message.completed, rezultatul final poate fi citit mai tarziu cu GET /api/v1/chat/sessions/{sessionId}.

Continua o sesiune

Foloseste 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": "gpt-5-2-chat",
    "session_id": "session_id",
    "message": "Acum transforma asta intr-un checklist de executie in 5 pasi."
  }'

Sesiunea trebuie sa apartina aceluiasi cont Rivya si trebuie sa fi fost creata de Public API. Sesiunile de chat exclusiv Studio nu sunt returnate sau continuate de Chat API.

Atasamente imagine

Atasamentele de chat folosesc inregistrari Files API, nu URL-uri externe.

Incarca o imagine cu POST /api/v1/files.
Foloseste id returnat ca attachments[].file_id.

{
  "model": "gpt-5-2-chat",
  "message": "Revizuieste aceasta fotografie de produs si sugereaza o directie editoriala mai curata.",
  "attachments": [
    {
      "file_id": "file_..."
    }
  ]
}

Fisierul trebuie sa apartina aceluiasi cont, sa aiba kind: "image" si sa fie disponibil. Modelele care nu accepta atasamente imagine returneaza chat_attachment_not_supported.

Controale optionale

{
  "model": "gpt-5-2-chat",
  "message": "Compara trei optiuni de lansare.",
  "enable_web_search": false,
  "reasoning_effort": "default",
  "thought_mode": "default"
}

Suportul pentru controale variaza in functie de model. Citeste /api/v1/models si verifica chat_capabilities inainte sa expui controale in UI-ul tau.

Listeaza sesiunile

Foloseste 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 returneaza doar sesiuni create prin API:

{
  "object": "list",
  "data": [
    {
      "id": "session_id",
      "object": "chat.session",
      "model": "gpt-5-2-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"
    }
  ]
}

Obtine o sesiune

Foloseste GET /api/v1/chat/sessions/{sessionId} pentru a citi o sesiune creata prin API si mesajele ei confirmate.

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

Raspunsul include mesajele confirmate ale utilizatorului si asistentului. Nu expune campuri interne ale providerului.

Idempotenta

Foloseste Idempotency-Key pentru fiecare cerere de productie POST /api/v1/chat/completions si POST /api/v1/chat/completions/stream.

Daca o reincercare foloseste aceeasi cheie si acelasi body, Rivya poate returna raspunsul stocat fara sa creeze alt mesaj sau sa consume din nou credite. Daca aceeasi cheie este refolosita cu input diferit, API-ul returneaza idempotency_conflict.

Pentru reincercari de streaming, Rivya nu reda delta-uri istorice de tokeni. Un replay finalizat returneaza o secventa SSE minima cu session.created, message.completed, usage.completed si done.

Erori comune

Cod	Semnificatie
`chat_model_not_supported`	Modelul selectat nu este disponibil pentru Chat API.
`chat_session_conflict`	Sesiunea nu poate fi folosita pentru aceasta cerere.
`chat_attachment_not_supported`	Atasamentul lipseste, nu este detinut de cont, nu este o imagine sau nu este acceptat de model.
`insufficient_credits`	Contul nu are suficiente credite pentru tura.
`idempotency_conflict`	Cheia de idempotenta a fost refolosita cu input diferit.

Chat API