Usa Rivya Chat API per turni non streaming o SSE, sessioni create via API, allegati immagine file_id e regolamento crediti basato su token.

Usa POST /api/v1/chat/completions per una risposta chat completa non streaming, oppure POST /api/v1/chat/completions/stream per Server-Sent Events.

Chat API è basata su sessioni. Ometti session_id per avviare una nuova sessione chat API. Passa un session_id restituito per continuare la stessa sessione creata via API.

Ambito attuale

Chat API v1 supporta:

risposte assistant non streaming
streaming SSE con text/event-stream
sessioni chat create via API
prenotazione crediti account e regolamento finale basato su token
web search, reasoning effort e thought mode opzionali quando supportati dal modello selezionato
allegati immagine tramite valori file_id della Files API

Chat API v1 non supporta:

cronologia raw messages fornita dall'utente
continuazione di sessioni chat solo Studio
URL arbitrari di allegati esterni
eventi webhook Chat

Scope richiesti

Usa una chiave API con:

chat:create
chat:read

Le nuove chiavi create in Settings includono entrambi gli scope per impostazione predefinita. Le chiavi più vecchie potrebbero dover essere ricreate prima di chiamare Chat API.

Creare una 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": "Write a concise launch plan for a new product image campaign",
    "client_request_id": "chat-001"
  }'

Risposta:

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

Streaming di una Chat Completion

Usa POST /api/v1/chat/completions/stream quando il tuo server vuole ricevere i delta assistant appena arrivano:

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": "Write a concise launch plan for a new product image campaign",
    "client_request_id": "chat-stream-001"
  }'

Le risposte streaming usano Content-Type: text/event-stream; charset=utf-8.

Eventi:

Event	Significato
`session.created`	I controlli su chiave API, modello, sessione, allegati, rate limit e prenotazione crediti sono passati.
`message.delta`	Delta visualizzato per il messaggio assistant. Non è ancora un messaggio confermato.
`message.completed`	Il messaggio assistant è stato salvato nella sessione creata via API.
`usage.completed`	Token usage e crediti finali sono stati regolati.
`heartbeat`	Evento keepalive durante pause lunghe.
`error`	Envelope di errore Public API per un errore dopo l'avvio dello streaming.
`done`	Lo stream è terminato correttamente.

Esempio di 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":"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}

Se si verifica un errore dopo il primo evento SSE, lo stream invia event: error e poi si chiude:

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

Se il client si disconnette prima del completamento, Rivya interrompe quando possibile lo stream di generazione in corso. I delta parziali non vengono salvati come messaggio assistant finale. Se il server ha già confermato message.completed, il risultato finale può essere letto più tardi con GET /api/v1/chat/sessions/{sessionId}.

Continuare una sessione

Usa il session_id restituito:

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": "Now turn that into a 5-step execution checklist."
  }'

La sessione deve appartenere allo stesso account Rivya e deve essere stata creata dalla Public API. Le sessioni chat solo Studio non vengono restituite o continuate da Chat API.

Allegati immagine

Gli allegati Chat usano record Files API, non URL esterni.

Carica un'immagine con POST /api/v1/files.
Usa l'id restituito come attachments[].file_id.

{
  "model": "gpt-5-2-chat",
  "message": "Review this product photo and suggest a cleaner editorial direction.",
  "attachments": [
    {
      "file_id": "file_..."
    }
  ]
}

Il file deve appartenere allo stesso account, avere kind: "image" ed essere disponibile. I modelli che non supportano allegati immagine restituiscono chat_attachment_not_supported.

Controlli opzionali

{
  "model": "gpt-5-2-chat",
  "message": "Compare three launch options.",
  "enable_web_search": false,
  "reasoning_effort": "default",
  "thought_mode": "default"
}

Il supporto dei controlli varia in base al modello. Leggi /api/v1/models e controlla chat_capabilities prima di esporre controlli nella tua UI.

Elencare le sessioni

Usa GET /api/v1/chat/sessions con una chiave che includa chat:read.

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

Restituisce solo sessioni create via API:

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

Leggere una sessione

Usa GET /api/v1/chat/sessions/{sessionId} per leggere una sessione creata via API e i suoi messaggi confermati.

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

La risposta include messaggi user e assistant confermati. Non espone campi interni del provider.

Idempotenza

Usa Idempotency-Key per ogni richiesta di produzione POST /api/v1/chat/completions e POST /api/v1/chat/completions/stream.

Se un retry usa la stessa chiave e lo stesso body, Rivya può restituire la risposta salvata senza creare un altro messaggio o consumare di nuovo crediti. Se la stessa chiave viene riutilizzata con input diverso, l'API restituisce idempotency_conflict.

Per i retry streaming, Rivya non riproduce i delta token storici. Un replay completato restituisce una sequenza SSE minima con session.created, message.completed, usage.completed e done.

Errori comuni

Code	Significato
`chat_model_not_supported`	Il modello selezionato non è disponibile per Chat API.
`chat_session_conflict`	La sessione non può essere usata per questa richiesta.
`chat_attachment_not_supported`	L'allegato manca, non appartiene all'account, non è un'immagine o non è supportato dal modello.
`insufficient_credits`	L'account non ha crediti sufficienti per il turno.
`idempotency_conflict`	La chiave di idempotenza è stata riutilizzata con input diverso.

Chat API