Εφήμερα διακριτικά και ασφάλεια
Σε αυτήν τη σελίδα
Ενημερώθηκε στις 3 Νοεμβρίου 2026, με βάση την αναφορά API του xAI Voice. Πηγές: Εφήμερα Διακριτικά · Αναφορά API Voice · Επανέναρξη Συνεδρίας.
Το πρόβλημα με το κλειδί API στον πελάτη
Μια εφαρμογή φωνής που εκτελείται σε πρόγραμμα περιήγησης ή σε κινητό τηλέφωνο δεν μπορεί να ενσωματώνει το κλειδί API σας. Οποιοσδήποτε επισκέπτης μπορεί να ανοίξει τα εργαλεία προγραμματιστή, να διαβάσει το κλειδί από τη δέσμη JavaScript ή από μια κεφαλίδα αιτήματος και στη συνέχεια να το χρησιμοποιήσει στον λογαριασμό σας μέχρι να εξαντληθεί η ποσόστωσή σας. Κανένα επίπεδο συσκότισης δεν προστατεύει μια τιμή που ο πελάτης πρέπει να διαθέτει για να καλέσει το API.
Η απάντηση του xAI είναι τα εφήμερα διακριτικά, γνωστά και ως μυστικά πελάτη: ένα διακριτικό μικρής διάρκειας, που δημιουργείται από τον διακομιστή σας, το οποίο εξουσιοδοτεί μια συνεδρία φωνής και τίποτα άλλο.
Πώς λειτουργεί
Η ροή συνοψίζεται σε πέντε βήματα:
- Το backend σας (ένας ασφαλής διακομιστής) καλεί το
POST /v1/realtime/client_secretsμε το κλειδί API σας - Το API επιστρέφει ένα προσωρινό διακριτικό με περιορισμένη διάρκεια ζωής
- Το backend σας στέλνει αυτό το διακριτικό στον πελάτη (πρόγραμμα περιήγησης ή εφαρμογή για κινητά)
- Ο πελάτης χρησιμοποιεί το διακριτικό για να συνδεθεί στο WebSocket του Voice Agent
- Το διακριτικό λήγει μετά τη διάρκεια ζωής που επιλέξατε (
expires_after.seconds)
Αυτό που μπορεί να διαρρεύσει στην πλευρά του πελάτη έχει πλέον πολύ μικρότερη αξία: ένα διακριτικό που λήγει μέσα σε λίγα λεπτά και μπορεί μόνο να ανοίξει μια συνεδρία φωνής, όχι το κλειδί API σας. Στον διακομιστή, η δημιουργία ενός τέτοιου διακριτικού απαιτεί μερικές μόνο γραμμές κώδικα. Σημειώστε ότι ο χειριστής ξεκινά ελέγχοντας τον χρήστη: χωρίς αυτόν τον έλεγχο, το backend σας λειτουργεί απλώς ως δημόσιος διανομέας διακριτικών.
// Node.js backend (Express)
app.post("/api/voice-token", async (req, res) => {
// Check that the user is authenticated
if (!req.user) return res.status(401).json({ error: "Unauthorized" });
const response = await fetch(
"https://api.x.ai/v1/realtime/client_secrets",
{
method: "POST",
headers: {
"Authorization": "Bearer " + process.env.XAI_API_KEY,
"Content-Type": "application/json"
},
body: JSON.stringify({
expires_after: { seconds: 600 } // 10 minutes, the default
})
}
);
const data = await response.json(); // { value, expires_at }
res.json({ token: data.value, expiresAt: data.expires_at });
});
Ο πελάτης γνωρίζει μόνο τη δική σας διαδρομή: ζητά ένα διακριτικό και στη συνέχεια ανοίγει το WebSocket με αυτό.
// Frontend (browser)
async function startVoiceSession() {
// Ask the backend for a token
const tokenRes = await fetch("/api/voice-token", { method: "POST" });
const { token } = await tokenRes.json();
// The browser WebSocket doesn't accept headers:
// the token goes in a subprotocol, prefixed with "xai-client-secret."
const ws = new WebSocket(
"wss://api.x.ai/v1/realtime?model=grok-voice-latest",
[`xai-client-secret.${token}`]
);
// ... session configuration
}
Η αρχιτεκτονική από άκρο σε άκρο
Συνολικά, η ροή ξεκινά με τον χρήστη να συνδέεται στην εφαρμογή σας. Στη συνέχεια, ο πελάτης του ζητά από το backend σας ένα διακριτικό φωνής και το backend ελέγχει την ταυτοποίηση και τα δικαιώματα πριν δημιουργήσει το εφήμερο διακριτικό μέσω του API του xAI. Το διακριτικό επιστρέφει στον πελάτη, ο οποίος το χρησιμοποιεί για να ανοίξει τη συνεδρία του Voice Agent, και λήγει αυτόματα στο τέλος της διάρκειας ζωής του.
Αυτός ο έλεγχος μεταξύ του αιτήματος και της δημιουργίας μετατρέπει μια απλή αναμετάδοση σε σημείο ελέγχου, και εκεί είναι που εφαρμόζονται οι επιχειρηματικοί σας κανόνες. Μπορείτε να θέσετε όριο στον αριθμό των συνεδριών φωνής ανά χρήστη ανά ημέρα, ώστε ένας μοναδικός λογαριασμός να μην μπορεί να καταναλώσει τον μηνιαίο προϋπολογισμό σας μέσα σε μία νύχτα. Μπορείτε να δεσμεύετε διακριτικά για ενεργές συνδρομές, επιβάλλοντας το επιχειρηματικό σας μοντέλο κάπου αλλού εκτός από το περιβάλλον χρήστη. Μπορείτε να περιορίσετε τον ρυθμό των αιτημάτων, ώστε ένας ελαττωματικός ή κακόβουλος πελάτης να μην μπορεί να ζητά χίλια διακριτικά το λεπτό. Και μπορείτε να καταγράφετε κάθε διακριτικό που δημιουργείτε: αποτελεί τη μοναδική αξιόπιστη βάση σας για παρακολούθηση, εσωτερική τιμολόγηση και ανάλυση περιστατικών.
Κανόνες που δεν πρέπει ποτέ να παραβιάσετε
Το κλειδί API δεν πηγαίνει ποτέ στον πελάτη, υπό καμία μορφή. Κρατήστε το εκτός του JavaScript του front-end και εκτός οποιασδήποτε μεταβλητής περιβάλλοντος που εκτίθεται στη δόμηση του προγράμματος περιήγησης (οι μεταβλητές με πρόθεμα για έγχυση στη δέσμη καταλήγουν δημόσιες). Κρατήστε το επίσης εκτός URL, αρχείων καταγραφής και μηνυμάτων σφάλματος που εμφανίζονται στους χρήστες.
Στη συνέχεια, διατηρήστε τη διάρκεια ζωής όσο το δυνατόν συντομότερη είναι πρακτικό. Σύμφωνα με την αναφορά API, το expires_after.seconds έχει προεπιλογή τα 600 δευτερόλεπτα και μέγιστο όριο τα 3.600· η τεκμηρίωση χρησιμοποιεί το 300 στα παραδείγματά της. Πάνω απ’ όλα, το διακριτικό πρέπει να είναι έγκυρο όταν ο πελάτης ανοίγει τη σύνδεση. Μια σύντομη διάρκεια ζωής μειώνει το χρονικό περιθώριο κατά το οποίο ένα υποκλαπέν διακριτικό μπορεί να χρησιμοποιηθεί.
Η τεκμηρίωση δεν διευκρινίζει εάν ένα διακριτικό που λήγει διακόπτει μια σύνδεση που είναι ήδη ανοιχτή. Εάν ο πελάτης σας χρειάζεται να επανασυνδεθεί, μετά από διακοπή δικτύου ή κατά τη διάρκεια μιας πολύ μεγάλης συνεδρίας, ζητήστε ένα νέο διακριτικό και χρησιμοποιήστε την επανέναρξη συνεδρίας: ενεργοποιήστε το resumption.enabled στο session.update, διατηρήστε το ID που λαμβάνετε στο conversation.created και, στη συνέχεια, ανοίξτε ξανά το WebSocket με ?conversation_id=<id>. Οι προηγούμενες εναλλαγές επαναλαμβάνονται και το μοντέλο συνεχίζει από εκεί που σταμάτησε.
async function reconnect(conversationId) {
const { token } = await (await fetch("/api/voice-token", { method: "POST" })).json();
const url = `wss://api.x.ai/v1/realtime?model=grok-voice-latest&conversation_id=${conversationId}`;
const ws = new WebSocket(url, [`xai-client-secret.${token}`]);
ws.onopen = () => ws.send(JSON.stringify({
type: "session.update",
session: { resumption: { enabled: true } }, // send again on every connection
}));
return ws;
}
Για το TTS σε λειτουργία HTTP, υπάρχει μια ακόμη πιο απλή εναλλακτική λύση στα διακριτικά: ένας διακομιστής μεσολάβησης (proxy). Ο πελάτης στέλνει το κείμενό του στο backend σας και το backend σας καλεί το TTS και επιστρέφει τον ήχο. Το κλειδί δεν φεύγει ποτέ από τον διακομιστή σας και αποκτάτε ένα φυσικό σημείο για φιλτράρισμα περιεχομένου και μέτρηση χρήσης στη διαδικασία.
Βασικά σημεία
- Τα εφήμερα διακριτικά ασφαλίζουν την πρόσβαση στον Voice Agent από εφαρμογές πλευράς πελάτη
- Το
POST /v1/realtime/client_secretsεπιστρέφειvalueκαιexpires_at· τοexpires_after.secondsέχει προεπιλογή 600 και μέγιστο όριο 3.600 - Στο πρόγραμμα περιήγησης, το διακριτικό τοποθετείται στο υποπρωτόκολλο
xai-client-secret.<token> - Το backend σας πρέπει να ελέγχει την ταυτοποίηση και τα δικαιώματα πριν δημιουργήσει ένα διακριτικό
- Μην εκθέτετε ποτέ το κλειδί API σας στον πελάτη, σε URL ή σε αρχεία καταγραφής
- Για HTTP TTS, η μεσολάβηση μέσω του backend σας αποτελεί έγκυρη εναλλακτική λύση στα εφήμερα διακριτικά