zai_rs/
realtime.rs

1//! # Realtime API (WebSocket)
2//!
3//! Realtime text and audio conversations over the GLM-Realtime WebSocket
4//! protocol (`wss://open.bigmodel.cn/api/paas/v4/realtime`). The protocol types
5//! also model passive-video frames, conversation history, function calls, and
6//! response lifecycle events.
7//!
8//! Verified against the official protocol:
9//! - <https://github.com/MetaGLM/glm-realtime-sdk/blob/main/GLM-Realtime-doc-for-llm.md>
10//! - <https://docs.bigmodel.cn/cn/asyncapi/realtime>
11//!
12//! ## Quick start
13//!
14//! ```rust,no_run
15//! use zai_rs::{
16//!     model::GLM_realtime_flash,
17//!     realtime::{RealtimeClient, TurnDetectionType},
18//! };
19//!
20//! # async fn demo(key: String) -> zai_rs::ZaiResult<()> {
21//! let session = RealtimeClient::new(key)
22//!     .session(GLM_realtime_flash {})
23//!     .turn_detection(TurnDetectionType::ServerVad)
24//!     .build()
25//!     .await?;
26//! session.send_text("你好").await?;
27//! session.create_response().await?;
28//! # Ok(())
29//! # }
30//! ```
31//!
32//! ## Auth modes
33//!
34//! - **Bearer** (default, server-side): `Authorization: Bearer {API_KEY}`.
35//! - **JWT**: `.with_jwt(ttl_seconds)` derives a short-lived token locally and
36//!   sends that token, rather than the raw API key, in the WebSocket handshake.
37//!   Generating the token on a trusted server before handing it to an untrusted
38//!   browser or device is still the application's responsibility.
39
40pub mod audio;
41pub mod client;
42pub mod events;
43pub mod jwt;
44pub mod protocol;
45pub mod session;
46pub mod transport;
47
48pub use audio::{InputAudioFormat, OutputAudioFormat};
49pub use client::{AuthMode, RealtimeClient};
50pub use events::{
51    ClientEvent, RealtimeConversation, RealtimeRateLimit, RealtimeSessionInfo, ServerErrorBody,
52    ServerEvent,
53};
54pub use protocol::{
55    BetaFields, ChatMode, GreetingConfig, InputAudioNoiseReduction, ItemContent, ItemType,
56    NoiseReductionType, RealtimeConversationItem, RealtimeModality, RealtimeResponse, RealtimeTool,
57    RealtimeUsage, RealtimeVoice, SessionConfig, TokenDetails, TurnDetection, TurnDetectionType,
58};
59pub use session::{RealtimeAudioChunk, RealtimeSession, SessionBuilder};
60pub use transport::{RealtimeTransport, TungsteniteTransport, WsMessage};
61
62use crate::model::traits::ModelName;
63
64/// Marker trait for model ids usable in a realtime session.
65///
66/// This trait is sealed and implemented only for the current official realtime
67/// model ids, so arbitrary or retired model markers cannot reach session
68/// construction.
69///
70/// ```compile_fail
71/// use zai_rs::{model::GLM4_voice, realtime::RealtimeClient};
72///
73/// let client = RealtimeClient::new("abc.secret-value");
74/// // `GLM4_voice` is an HTTP voice-chat model, not a Realtime WebSocket model.
75/// let _session = client.session(GLM4_voice {});
76/// ```
77pub trait RealtimeModel: ModelName + sealed::Sealed {}
78
79impl RealtimeModel for crate::model::GLM_realtime_flash {}
80impl RealtimeModel for crate::model::GLM_realtime_air {}
81
82mod sealed {
83    pub trait Sealed {}
84
85    impl Sealed for crate::model::GLM_realtime_flash {}
86    impl Sealed for crate::model::GLM_realtime_air {}
87}
zai_rs/realtime.rs

zai_rs/
realtime.rs
