Πιστοποίηση και εφήμερα διακριτικά
Σε αυτήν τη σελίδα
Δύο τρόποι πιστοποίησης
Το Voice Agent API προσφέρει δύο τρόπους για την πιστοποίηση της σύνδεσής σας μέσω WebSocket. Ο τρόπος που θα επιλέξετε εξαρτάται από το πού εκτελείται ο κώδικάς σας: στον διακομιστή (server) ή στον πελάτη (client).
Άμεσο κλειδί API (πλευρά διακομιστή)
Η απλούστερη μέθοδος είναι να περάσετε το κλειδί API σας στην κεφαλίδα authorization κατά το άνοιγμα του WebSocket. Αυτό λειτουργεί για εφαρμογές διακομιστή, όπου το κλειδί παραμένει προστατευμένο:
const ws = new WebSocket("wss://api.x.ai/v1/realtime", {
headers: {
"Authorization": "Bearer xai-your-api-key"
}
});
Μην χρησιμοποιήσετε ποτέ αυτή τη μέθοδο σε κώδικα που εκτελείται στον φυλλομετρητή: το κλειδί API θα εκτίθετο στον πηγαίο κώδικα ή στα εργαλεία προγραμματιστή.
Εφήμερα διακριτικά (πλευρά πελάτη)
Για εφαρμογές front-end (φυλλομετρητής, κινητά), το xAI παρέχει εφήμερα διακριτικά. Το backend σας δημιουργεί ένα διακριτικό μικρής διάρκειας, το οποίο στη συνέχεια περνάτε στον πελάτη για να ανοίξει τη σύνδεση WebSocket.
Δημιουργείτε ένα διακριτικό με ένα αίτημα POST:
curl -X POST "https://api.x.ai/v1/realtime/client_secrets" \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"expires_after": {"seconds": 300}}'
Το πεδίο expires_after.seconds ορίζει πόσο χρόνο είναι έγκυρο το διακριτικό, σε δευτερόλεπτα. Το παράδειγμα της επίσημης τεκμηρίωσης χρησιμοποιεί 300 δευτερόλεπτα (5 λεπτά): ένα εφήμερο διακριτικό προορίζεται να καλύψει μια συνεδρία φωνής, όχι να διαρκεί επ’ αόριστον. Στοχεύστε στη συντομότερη διάρκεια ζωής που λειτουργεί για τις συνεδρίες σας.
Συνιστώμενη αρχιτεκτονική με εφήμερα διακριτικά
Ακολουθεί η πλήρης ροή για μια web εφαρμογή:
// 1. Πλευρά διακομιστή (Node.js/Express): δημιουργία του διακριτικού
app.post("/api/realtime-token", async (req, res) => {
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 } })
}
);
// Επιστροφή του σώματος απόκρισης xAI ως έχει·
// περιέχει το εφήμερο διακριτικό
res.json(await response.json());
});
// 2. Πλευρά πελάτη (φυλλομετρητής): χρήση του διακριτικού
// Ο κατασκευαστής WebSocket του φυλλομετρητή δεν δέχεται κεφαλίδες:
// το διακριτικό περνάει ως SUBPROTOCOL, με πρόθεμα "xai-client-secret."
async function startVoiceSession(ephemeralToken) {
const ws = new WebSocket(
"wss://api.x.ai/v1/realtime",
[`xai-client-secret.${ephemeralToken}`]
);
ws.onopen = () => {
console.log("Voice session started");
};
}
Ανανέωση διακριτικών
Η τεκμηρίωση δεν διευκρινίζει εάν ένα διακριτικό που λήγει κλείνει μια ήδη ανοιχτή σύνδεση. Σε κάθε περίπτωση, η εφαρμογή σας χρειάζεται ένα σχέδιο για την περίπτωση διακοπής της σύνδεσης: παρακολουθήστε το συμβάν close, ζητήστε από το backend σας ένα νέο διακριτικό και επανασυνδεθείτε:
ws.onclose = async () => {
// Η σύνδεση χάθηκε ή έκλεισε: αίτημα νέου διακριτικού
const newToken = await fetchNewToken();
reconnect(newToken);
};
Βέλτιστες πρακτικές ασφαλείας
Μερικοί βασικοί κανόνες διατηρούν τις συνδέσεις σας ασφαλείς:
- Μην εκθέτετε ποτέ το κύριο κλειδί API σας στον πελάτη
- Διατηρήστε τη διάρκεια ζωής (
expires_after.seconds) όσο το δυνατόν συντομότερη: αν η μέση συνεδρία σας διαρκεί πέντε λεπτά, τα 300 έως 600 δευτερόλεπτα αρκούν - Επικυρώστε τα αιτήματα διακριτικών στον διακομιστή (πιστοποίηση χρήστη, όριο ρυθμού αιτημάτων)
- Καταγράψτε τη δημιουργία διακριτικών ώστε να εντοπίζετε ανώμαλη χρήση
- Ανανεώστε το κύριο κλειδί API σας εάν υποψιάζεστε ότι έχει compromiserθεί
Βασικά σημεία
- Ένα άμεσο κλειδί API είναι κατάλληλο μόνο για εφαρμογές διακομιστή
- Τα εφήμερα διακριτικά είναι απαραίτητα για εφαρμογές πλευράς πελάτη (φυλλομετρητής, κινητά)
- Ορίστε τη διάρκεια ζωής του διακριτικού με το
expires_after.secondsκαι κρατήστε τη σύντομη (300 δευτερόλεπτα στο επίσημο παράδειγμα) - Η συνιστώμενη ροή: το backend σας δημιουργεί το διακριτικό και το front end το περνάει ως υποπρωτόκολλο
xai-client-secret.για να ανοίξει το WebSocket - Σχεδιάστε πάντα για αυτόματη ανανέωση διακριτικών