API συνομιλίας

Χρησιμοποιήστε POST /api/v1/chat/completions για μία πλήρη απόκριση συνομιλίας ή POST /api/v1/chat/completions/stream για τμηματική μετάδοση μέσω Server-Sent Events.

Το API συνομιλίας βασίζεται σε συνεδρίες. Παραλείψτε το session_id για να ξεκινήσετε νέα συνεδρία μέσω API. Χρησιμοποιήστε το session_id που επιστρέφεται για να συνεχίσετε την ίδια συνεδρία.

Η σελίδα αυτή τεκμηριώνει την υλοποιημένη σύμβαση του δημόσιου API v1. Η πρόσβαση κατά την εκτέλεση εξαρτάται από το αν το δημόσιο API είναι ενεργοποιημένο για την εγκατάσταση, από το αν ο λογαριασμός διαθέτει ενεργό κλειδί API και από το αν το επιλεγμένο μοντέλο εμφανίζεται ως διαθέσιμο μέσω API. Ελέγξτε την ενεργή λίστα μοντέλων πριν στείλετε αίτημα παραγωγής.

Τρέχον εύρος

Το API συνομιλίας v1 υποστηρίζει:

• πλήρεις απαντήσεις βοηθού

• τμηματική μετάδοση SSE με text/event-stream

• συνεδρίες συνομιλίας που δημιουργούνται μέσω API

• κράτηση πιστωτικών μονάδων του λογαριασμού και τελικό διακανονισμό βάσει διακριτικών

• προαιρετική αναζήτηση στον ιστό, ένταση συλλογισμού και λειτουργία σκέψης, όταν υποστηρίζονται από το επιλεγμένο μοντέλο

• συνημμένα εικόνας μέσω τιμών file_id από το API αρχείων

Το API συνομιλίας v1 δεν υποστηρίζει:

• ανεπεξέργαστο ιστορικό messages που παρέχει ο χρήστης

• συνέχιση συνεδριών συνομιλίας που υπάρχουν μόνο στο Studio

• αυθαίρετα εξωτερικά URL συνημμένων

• συμβάντα webhook συνομιλίας

Απαιτούμενα πεδία πρόσβασης

Χρησιμοποιήστε κλειδί API με:

chat:create
chat:read

Τα νέα κλειδιά που δημιουργούνται στις ρυθμίσεις περιλαμβάνουν και τα δύο πεδία πρόσβασης από προεπιλογή. Παλαιότερα κλειδιά μπορεί να χρειάζεται να δημιουργηθούν ξανά πριν καλέσετε το API συνομιλίας.

Δημιουργία ολοκλήρωσης συνομιλίας

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": "Γράψε ένα σύντομο σχέδιο λανσαρίσματος για μια νέα καμπάνια εικόνων προϊόντος",
    "client_request_id": "chat-001"
  }'

Απάντηση:

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

Τμηματική μετάδοση απόκρισης συνομιλίας

Χρησιμοποιήστε POST /api/v1/chat/completions/stream όταν ο διακομιστής σας χρειάζεται τα τμήματα της απάντησης του βοηθού μόλις φτάνουν:

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": "Γράψε ένα σύντομο σχέδιο λανσαρίσματος για μια νέα καμπάνια εικόνων προϊόντος",
    "client_request_id": "chat-stream-001"
  }'

Οι τμηματικά μεταδιδόμενες απαντήσεις χρησιμοποιούν Content-Type: text/event-stream; charset=utf-8.

Συμβάντα:

Παράδειγμα μετάδοσης:

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":"Προσχέδιο ","index":0}

event: message.completed
data: {"request_id":"req_...","session_id":"session_id","message":{"id":"assistant_message_id","role":"assistant","content":"Προσχέδιο ...","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}

Αν συμβεί σφάλμα μετά το πρώτο συμβάν SSE, η μετάδοση στέλνει event: error και μετά κλείνει:

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

Αν ο πελάτης αποσυνδεθεί πριν από την ολοκλήρωση, το Rivya σταματά, όταν είναι δυνατό, τη μετάδοση της δημιουργίας που βρίσκεται σε εξέλιξη. Τα επιμέρους τμήματα δεν αποθηκεύονται ως τελικό μήνυμα βοηθού. Αν ο διακομιστής έχει ήδη δεσμεύσει το message.completed, το τελικό αποτέλεσμα μπορεί να διαβαστεί αργότερα με GET /api/v1/chat/sessions/{sessionId}.

Συνέχιση συνεδρίας

Χρησιμοποιήστε το επιστρεφόμενο 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": "Τώρα μετέτρεψέ το σε λίστα ελέγχου εκτέλεσης με πέντε βήματα."
  }'

Η συνεδρία πρέπει να ανήκει στον ίδιο λογαριασμό Rivya και να έχει δημιουργηθεί μέσω του δημόσιου API. Το API συνομιλίας δεν επιστρέφει ούτε συνεχίζει συνεδρίες που υπάρχουν μόνο στο Studio.

Συνημμένα εικόνας

Τα συνημμένα συνομιλίας χρησιμοποιούν εγγραφές του API αρχείων και όχι εξωτερικά URL.

1. Ανεβάστε εικόνα με POST /api/v1/files.

2. Χρησιμοποιήστε το επιστρεφόμενο id ως attachments[].file_id.

{
  "model": "<image-capable-chat-model-id>",
  "message": "Αξιολόγησε αυτή τη φωτογραφία προϊόντος και πρότεινε μια πιο καθαρή συντακτική κατεύθυνση.",
  "attachments": [
    {
      "file_id": "file_..."
    }
  ]
}

Το αρχείο πρέπει να ανήκει στον ίδιο λογαριασμό, να έχει kind: "image" και να είναι διαθέσιμο. Αντικαταστήστε το δείγμα με ένα διαθέσιμο μοντέλο συνομιλίας, του οποίου η εγγραφή στο /api/v1/models δηλώνει στο chat_capabilities ότι υποστηρίζει συνημμένες εικόνες. Το claude-sonnet-5-chat είναι το παράδειγμα μόνο με κείμενο που χρησιμοποιείται στην υπόλοιπη σελίδα και δεν πρέπει να χρησιμοποιηθεί σε αυτό το αίτημα συνημμένου. Τα μοντέλα που δεν υποστηρίζουν συνημμένα εικόνας επιστρέφουν chat_attachment_not_supported.

Προαιρετικές ρυθμίσεις

{
  "model": "claude-sonnet-5-chat",
  "message": "Σύγκρινε τρεις επιλογές λανσαρίσματος.",
  "enable_web_search": false,
  "reasoning_effort": "default",
  "thought_mode": "default"
}

Η υποστήριξη των ρυθμίσεων διαφέρει ανά μοντέλο. Διαβάστε το /api/v1/models και ελέγξτε το chat_capabilities πριν τις εμφανίσετε στο περιβάλλον χρήστη.

Λίστα συνεδριών

Χρησιμοποιήστε GET /api/v1/chat/sessions με κλειδί που περιλαμβάνει chat:read.

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

Αυτό επιστρέφει μόνο συνεδρίες που δημιουργήθηκαν μέσω API:

{
  "object": "list",
  "data": [
    {
      "id": "session_id",
      "object": "chat.session",
      "model": "claude-sonnet-5-chat",
      "tool_slug": null,
      "title": "Γράψε ένα σύντομο σχέδιο λανσαρίσματος...",
      "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"
    }
  ]
}

Λήψη συνεδρίας

Χρησιμοποιήστε GET /api/v1/chat/sessions/{sessionId} για να διαβάσετε μια συνεδρία που δημιουργήθηκε μέσω API και τα δεσμευμένα μηνύματά της.

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

Η απάντηση περιλαμβάνει αποθηκευμένα μηνύματα χρήστη και βοηθού. Δεν εκθέτει εσωτερικά πεδία παρόχου.

Idempotency

Χρησιμοποιήστε Idempotency-Key για κάθε αίτημα παραγωγής POST /api/v1/chat/completions και POST /api/v1/chat/completions/stream.

Αν μια επανάληψη χρησιμοποιεί το ίδιο κλειδί και το ίδιο σώμα, το Rivya μπορεί να επιστρέψει την αποθηκευμένη απάντηση χωρίς να δημιουργήσει άλλο μήνυμα ή να καταναλώσει ξανά credits. Αν το ίδιο κλειδί επαναχρησιμοποιηθεί με διαφορετική είσοδο, το API επιστρέφει idempotency_conflict.

Στις επαναλήψεις τμηματικής μετάδοσης, το Rivya δεν αναπαράγει παλαιότερα τμήματα διακριτικών. Μια ολοκληρωμένη επανάληψη επιστρέφει την ελάχιστη ακολουθία SSE με session.created, message.completed, usage.completed και done.

Συνηθισμένα σφάλματα

Σχετικές σελίδες

• Μοντέλα API

• API αρχείων

• Πιστωτικές μονάδες του API

• Σφάλματα και όρια API

• OpenAPI και σύμβαση σχήματος