novel_doubao/lib.rs
1//! Rust library for Doubao (ByteDance Volcengine) APIs.
2//!
3//! This crate provides clients for various Doubao APIs:
4//!
5//! - **TTS**: Text-to-Speech API
6//! - **ASR**: Automatic Speech Recognition API
7//! - **Chat**: Chat completion API (OpenAI-compatible)
8//! - **Embeddings**: Text and multimodal embeddings API
9//! - **Images**: Image generation API
10//! - **Tokenization**: Text tokenization API
11//!
12//! ## Creating a client
13//!
14//! ```no_run
15//! use novel_doubao::Client;
16//! use novel_doubao::config::DoubaoConfig;
17//!
18//! // Create a client with default configuration from environment variables.
19//! let client = Client::new();
20//!
21//! // Or create with custom configuration.
22//! let config = DoubaoConfig::new()
23//! .with_app_id("your-app-id")
24//! .with_api_key("your-api-key")
25//! .with_access_token("your-access-token")
26//! .with_resource_id("seed-tts-2.0");
27//! let client = Client::with_config(config);
28//! ```
29//!
30//! ## Making TTS requests
31//!
32//! ```no_run
33//! # tokio_test::block_on(async {
34//! use novel_doubao::Client;
35//! use novel_doubao::spec::tts::CreateSpeechRequestArgs;
36//!
37//! let client = Client::new();
38//!
39//! let request = CreateSpeechRequestArgs::default()
40//! .text("Hello, world!")
41//! .speaker("zh_female_cancan_mars_bigtts")
42//! .sample_rate(24000u32)
43//! .build()?;
44//!
45//! let response = client.tts().speech().create(request).await?;
46//!
47//! // Save to file
48//! response.save("output.mp3").await?;
49//!
50//! println!("Generated {} bytes of audio", response.bytes.len());
51//! # Ok::<(), Box<dyn std::error::Error>>(())
52//! # });
53//! ```
54//!
55//! ## Making ASR requests
56//!
57//! ### Flash recognition (fastest, single request)
58//!
59//! ```no_run
60//! # tokio_test::block_on(async {
61//! use novel_doubao::Client;
62//!
63//! let client = Client::new();
64//!
65//! // Recognize from URL
66//! let result = client
67//! .asr()
68//! .recognition()
69//! .flash_url("https://example.com/audio.wav", "user-id")
70//! .await?;
71//!
72//! println!("Recognized: {}", result.result.text);
73//! # Ok::<(), Box<dyn std::error::Error>>(())
74//! # });
75//! ```
76//!
77//! ### Standard recognition (for long audio files)
78//!
79//! ```no_run
80//! # tokio_test::block_on(async {
81//! use novel_doubao::Client;
82//!
83//! let client = Client::new();
84//!
85//! // Submit and wait for result
86//! let result = client
87//! .asr()
88//! .recognition()
89//! .recognize_url("https://example.com/audio.wav", "user-id")
90//! .await?;
91//!
92//! println!("Recognized: {}", result.result.text);
93//! # Ok::<(), Box<dyn std::error::Error>>(())
94//! # });
95//! ```
96//!
97//! ### Streaming recognition (real-time)
98//!
99//! ```no_run
100//! # tokio_test::block_on(async {
101//! use bytes::Bytes;
102//! use novel_doubao::Client;
103//! use novel_doubao::spec::asr::StreamingAsrConfigArgs;
104//!
105//! let client = Client::new();
106//!
107//! let config = StreamingAsrConfigArgs::default().rate(16000u32).build()?;
108//!
109//! let mut session = client.asr().streaming().create_session(config).await?;
110//!
111//! // Send audio data
112//! session
113//! .send_audio(Bytes::from_static(b"audio data..."))
114//! .await?;
115//!
116//! // Receive results
117//! while let Some(result) = session.recv().await {
118//! println!(
119//! "Partial: {} (final: {})",
120//! result.result.text, result.is_final
121//! );
122//! }
123//! # Ok::<(), Box<dyn std::error::Error>>(())
124//! # });
125//! ```
126//!
127//! ## Environment Variables
128//!
129//! The client reads these environment variables by default:
130//! - `DOUBAO_APP_ID`: Application ID
131//! - `DOUBAO_API_KEY`: API key
132//! - `DOUBAO_ACCESS_TOKEN`: Access token
133//! - `DOUBAO_RESOURCE_ID`: Resource ID (default: "seed-tts-2.0")
134//! - `DOUBAO_HTTP_BASE`: HTTP base URL (default: "https://ark.cn-beijing.volces.com/api/v3")
135//!
136//! ## Features
137//!
138//! - `tts`: Enable TTS (Text-to-Speech) API
139//! - `asr`: Enable ASR (Automatic Speech Recognition) API
140//! - `chat`: Enable Chat completion API
141//! - `embeddings`: Enable Embeddings API
142//! - `images`: Enable Image generation API
143//! - `tokenization`: Enable Tokenization API
144//! - `full`: Enable all features
145//! - `rustls`: Use rustls for TLS (default)
146//! - `native-tls`: Use native-tls for TLS
147#![cfg_attr(docsrs, feature(doc_cfg))]
148
149#[cfg(feature = "asr")]
150mod asr;
151#[cfg(feature = "chat")]
152mod chat;
153mod client;
154pub mod config;
155#[cfg(feature = "embeddings")]
156mod embeddings;
157pub mod error;
158#[cfg(feature = "images")]
159mod images;
160pub mod spec;
161#[cfg(feature = "tokenization")]
162mod tokenization;
163#[cfg(feature = "tts")]
164mod tts;
165
166#[cfg(feature = "asr")]
167#[cfg_attr(docsrs, doc(cfg(feature = "asr")))]
168pub use asr::{Asr, Recognition, Streaming, StreamingSession};
169#[cfg(feature = "chat")]
170#[cfg_attr(docsrs, doc(cfg(feature = "chat")))]
171pub use chat::Chat;
172pub use client::Client;
173#[cfg(feature = "embeddings")]
174#[cfg_attr(docsrs, doc(cfg(feature = "embeddings")))]
175pub use embeddings::Embeddings;
176#[cfg(feature = "images")]
177#[cfg_attr(docsrs, doc(cfg(feature = "images")))]
178pub use images::Images;
179#[cfg(feature = "tokenization")]
180#[cfg_attr(docsrs, doc(cfg(feature = "tokenization")))]
181pub use tokenization::Tokenization;
182#[cfg(feature = "tts")]
183#[cfg_attr(docsrs, doc(cfg(feature = "tts")))]
184pub use tts::{Speech, Tts};