Struct Client 

pub struct Client { /* private fields */ }

The Quantum AI API client.

Client is cheaply cloneable (backed by Arc) and safe to share across tasks.

Example

let client = quantum_sdk::Client::new("qai_key_xxx");

Implementations

impl Client

pub async fn account_balance(&self) -> Result<BalanceResponse>

Gets the account credit balance.

pub async fn account_usage(&self, query: &UsageQuery) -> Result<UsageResponse>

Gets paginated usage history.

pub async fn account_usage_summary( &self, months: Option<i32>, ) -> Result<UsageSummaryResponse>

Gets monthly usage summary.

pub async fn account_pricing(&self) -> Result<PricingResponse>

Gets the full pricing table (model → pricing entry map).

impl Client

pub async fn agent_run(&self, req: &AgentRequest) -> Result<AgentStream>

Starts an agent run and returns an SSE event stream.

The agent orchestrates one or more worker models to accomplish the task, streaming progress events as it works.

pub async fn mission_run(&self, req: &MissionRequest) -> Result<AgentStream>

Starts a mission run and returns an SSE event stream.

Missions are higher-level than agents – they can auto-plan, assign named workers, and manage context across multiple steps.

impl Client

pub async fn speak( &self, req: &TextToSpeechRequest, ) -> Result<TextToSpeechResponse>

Generates speech from text.

pub async fn transcribe( &self, req: &SpeechToTextRequest, ) -> Result<SpeechToTextResponse>

Converts speech to text.

pub async fn sound_effects( &self, req: &SoundEffectRequest, ) -> Result<SoundEffectResponse>

Generates sound effects from a text prompt (ElevenLabs).

pub async fn generate_music(&self, req: &MusicRequest) -> Result<MusicResponse>

Generates music from a text prompt.

pub async fn dialogue(&self, req: &DialogueRequest) -> Result<AudioResponse>

Generates multi-speaker dialogue audio.

pub async fn speech_to_speech( &self, req: &SpeechToSpeechRequest, ) -> Result<AudioResponse>

Converts speech to a different voice.

pub async fn isolate_voice( &self, req: &IsolateVoiceRequest, ) -> Result<AudioResponse>

Isolates voice from background noise and music.

pub async fn remix_voice( &self, req: &RemixVoiceRequest, ) -> Result<AudioResponse>

Remixes audio with a different voice.

pub async fn dub(&self, req: &DubRequest) -> Result<AudioResponse>

Dubs audio or video into a target language.

pub async fn align(&self, req: &AlignRequest) -> Result<AlignResponse>

Performs forced alignment of text against audio.

pub async fn voice_design( &self, req: &VoiceDesignRequest, ) -> Result<AudioResponse>

Designs a new voice from a text description and generates sample audio.

pub async fn starfish_tts( &self, req: &StarfishTTSRequest, ) -> Result<AudioResponse>

Generates speech using Starfish TTS (HeyGen).

pub async fn generate_music_advanced( &self, req: &ElevenMusicRequest, ) -> Result<ElevenMusicResponse>

Generates music via ElevenLabs Eleven Music (advanced: sections, finetunes, edits).

pub async fn list_finetunes(&self) -> Result<ListFinetunesResponse>

Lists all music finetunes for the authenticated user.

pub async fn create_finetune( &self, name: &str, files: Vec<CloneVoiceFile>, ) -> Result<FinetuneInfo>

Creates a new music finetune from audio sample files.

pub async fn delete_finetune(&self, id: &str) -> Result<Value>

Deletes a music finetune by ID.

impl Client

pub async fn auth_apple(&self, req: &AuthAppleRequest) -> Result<AuthResponse>

Authenticate with Apple Sign-In.

The id_token is the JWT received from the Sign in with Apple flow. On first sign-in, pass the user’s name so the account is created with a display name.

impl Client

pub async fn batch_submit( &self, jobs: &[BatchJob], ) -> Result<BatchSubmitResponse>

Submit a batch of jobs for processing.

Each job runs independently and can be polled via the Jobs API.

pub async fn batch_submit_jsonl( &self, jsonl: &str, ) -> Result<BatchJsonlResponse>

Submit a batch of jobs using JSONL format.

Each line in the JSONL string is a JSON object with model, prompt, etc.

pub async fn batch_jobs(&self) -> Result<BatchJobsResponse>

List all batch jobs for the account.

pub async fn batch_job(&self, id: &str) -> Result<BatchJobInfo>

Get the status and result of a single batch job.

impl Client

pub async fn chat(&self, req: &ChatRequest) -> Result<ChatResponse>

Sends a non-streaming text generation request.

Examples found in repository

examples/chat.rs (lines 21-27)

async fn main() {
    let api_key = std::env::var("QAI_API_KEY").expect("QAI_API_KEY environment variable is required");

    let client = Client::new(api_key);

    // --- Non-streaming example ---
    println!("=== Non-streaming Chat ===");

    let resp = client
        .chat(&ChatRequest {
            model: "claude-sonnet-4-6".into(),
            messages: vec![ChatMessage::user(
                "What is quantum computing in one sentence?",
            )],
            ..Default::default()
        })
        .await
        .expect("Chat failed");

    println!("Model: {}", resp.model);
    println!("Response: {}", resp.text());
    if let Some(usage) = &resp.usage {
        println!(
            "Tokens: {} in / {} out (cost: {} ticks)",
            usage.input_tokens, usage.output_tokens, usage.cost_ticks
        );
    }
    println!("Request ID: {}\n", resp.request_id);

    // --- Streaming example ---
    println!("=== Streaming Chat ===");

    let mut stream = client
        .chat_stream(&ChatRequest {
            model: "claude-sonnet-4-6".into(),
            messages: vec![ChatMessage::user(
                "Count from 1 to 5, one number per line.",
            )],
            ..Default::default()
        })
        .await
        .expect("ChatStream failed");

    while let Some(ev) = stream.next().await {
        match ev.event_type.as_str() {
            "content_delta" => {
                if let Some(delta) = &ev.delta {
                    print!("{}", delta.text);
                }
            }
            "usage" => {
                if let Some(usage) = &ev.usage {
                    println!("\n[Cost: {} ticks]", usage.cost_ticks);
                }
            }
            "error" => {
                eprintln!("Stream error: {}", ev.error.as_deref().unwrap_or("unknown"));
                std::process::exit(1);
            }
            "done" => {
                println!("\n[Stream complete]");
            }
            _ => {}
        }
    }
}

pub async fn chat_stream(&self, req: &ChatRequest) -> Result<ChatStream>

Sends a streaming text generation request and returns an async stream of events.

Example

use futures_util::StreamExt;

let client = quantum_sdk::Client::new("key");
let req = quantum_sdk::ChatRequest {
    model: "claude-sonnet-4-6".into(),
    messages: vec![quantum_sdk::ChatMessage::user("Hello!")],
    ..Default::default()
};
let mut stream = client.chat_stream(&req).await?;
while let Some(ev) = stream.next().await {
    if let Some(delta) = &ev.delta {
        print!("{}", delta.text);
    }
}

Examples found in repository

examples/chat.rs (lines 45-51)

async fn main() {
    let api_key = std::env::var("QAI_API_KEY").expect("QAI_API_KEY environment variable is required");

    let client = Client::new(api_key);

    // --- Non-streaming example ---
    println!("=== Non-streaming Chat ===");

    let resp = client
        .chat(&ChatRequest {
            model: "claude-sonnet-4-6".into(),
            messages: vec![ChatMessage::user(
                "What is quantum computing in one sentence?",
            )],
            ..Default::default()
        })
        .await
        .expect("Chat failed");

    println!("Model: {}", resp.model);
    println!("Response: {}", resp.text());
    if let Some(usage) = &resp.usage {
        println!(
            "Tokens: {} in / {} out (cost: {} ticks)",
            usage.input_tokens, usage.output_tokens, usage.cost_ticks
        );
    }
    println!("Request ID: {}\n", resp.request_id);

    // --- Streaming example ---
    println!("=== Streaming Chat ===");

    let mut stream = client
        .chat_stream(&ChatRequest {
            model: "claude-sonnet-4-6".into(),
            messages: vec![ChatMessage::user(
                "Count from 1 to 5, one number per line.",
            )],
            ..Default::default()
        })
        .await
        .expect("ChatStream failed");

    while let Some(ev) = stream.next().await {
        match ev.event_type.as_str() {
            "content_delta" => {
                if let Some(delta) = &ev.delta {
                    print!("{}", delta.text);
                }
            }
            "usage" => {
                if let Some(usage) = &ev.usage {
                    println!("\n[Cost: {} ticks]", usage.cost_ticks);
                }
            }
            "error" => {
                eprintln!("Stream error: {}", ev.error.as_deref().unwrap_or("unknown"));
                std::process::exit(1);
            }
            "done" => {
                println!("\n[Stream complete]");
            }
            _ => {}
        }
    }
}

impl Client

pub fn new(api_key: impl Into<String>) -> Self

Creates a new client with the given API key and default settings.

Examples found in repository

examples/chat.rs (line 15)

async fn main() {
    let api_key = std::env::var("QAI_API_KEY").expect("QAI_API_KEY environment variable is required");

    let client = Client::new(api_key);

    // --- Non-streaming example ---
    println!("=== Non-streaming Chat ===");

    let resp = client
        .chat(&ChatRequest {
            model: "claude-sonnet-4-6".into(),
            messages: vec![ChatMessage::user(
                "What is quantum computing in one sentence?",
            )],
            ..Default::default()
        })
        .await
        .expect("Chat failed");

    println!("Model: {}", resp.model);
    println!("Response: {}", resp.text());
    if let Some(usage) = &resp.usage {
        println!(
            "Tokens: {} in / {} out (cost: {} ticks)",
            usage.input_tokens, usage.output_tokens, usage.cost_ticks
        );
    }
    println!("Request ID: {}\n", resp.request_id);

    // --- Streaming example ---
    println!("=== Streaming Chat ===");

    let mut stream = client
        .chat_stream(&ChatRequest {
            model: "claude-sonnet-4-6".into(),
            messages: vec![ChatMessage::user(
                "Count from 1 to 5, one number per line.",
            )],
            ..Default::default()
        })
        .await
        .expect("ChatStream failed");

    while let Some(ev) = stream.next().await {
        match ev.event_type.as_str() {
            "content_delta" => {
                if let Some(delta) = &ev.delta {
                    print!("{}", delta.text);
                }
            }
            "usage" => {
                if let Some(usage) = &ev.usage {
                    println!("\n[Cost: {} ticks]", usage.cost_ticks);
                }
            }
            "error" => {
                eprintln!("Stream error: {}", ev.error.as_deref().unwrap_or("unknown"));
                std::process::exit(1);
            }
            "done" => {
                println!("\n[Stream complete]");
            }
            _ => {}
        }
    }
}

pub fn builder(api_key: impl Into<String>) -> ClientBuilder

Returns a ClientBuilder for custom configuration.

pub async fn post_json<Req: Serialize, Resp: DeserializeOwned>( &self, path: &str, body: &Req, ) -> Result<(Resp, ResponseMeta)>

Sends a JSON POST request and deserializes the response.

pub async fn get_json<Resp: DeserializeOwned>( &self, path: &str, ) -> Result<(Resp, ResponseMeta)>

Sends a GET request and deserializes the response.

pub async fn delete_json<Resp: DeserializeOwned>( &self, path: &str, ) -> Result<(Resp, ResponseMeta)>

Sends a DELETE request and deserializes the response.

pub async fn post_multipart<Resp: DeserializeOwned>( &self, path: &str, form: Form, ) -> Result<(Resp, ResponseMeta)>

Sends a multipart POST request and deserializes the response.

pub async fn get_stream_raw( &self, path: &str, ) -> Result<(Response, ResponseMeta)>

Sends a GET request expecting an SSE stream response. Returns the raw reqwest::Response for the caller to read events from. Uses a separate client without timeout — cancellation is via drop.

pub async fn post_stream_raw( &self, path: &str, body: &impl Serialize, ) -> Result<(Response, ResponseMeta)>

Sends a JSON POST request expecting an SSE stream response. Returns the raw reqwest::Response for the caller to read events from. Uses a separate client without timeout – cancellation is via drop.

impl Client

pub async fn compute_templates(&self) -> Result<TemplatesResponse>

Lists available compute templates (GPU configurations and pricing).

pub async fn compute_provision( &self, req: &ProvisionRequest, ) -> Result<ProvisionResponse>

Provisions a new GPU compute instance.

pub async fn compute_instances(&self) -> Result<InstancesResponse>

Lists all compute instances for the account.

pub async fn compute_instance(&self, id: &str) -> Result<InstanceResponse>

Gets details for a specific compute instance.

pub async fn compute_delete(&self, id: &str) -> Result<DeleteResponse>

Deletes (tears down) a compute instance.

pub async fn compute_ssh_key( &self, id: &str, req: &SSHKeyRequest, ) -> Result<StatusResponse>

Adds an SSH public key to a running compute instance.

pub async fn compute_keepalive(&self, id: &str) -> Result<StatusResponse>

Sends a keepalive to prevent auto-teardown of a compute instance.

pub async fn compute_billing( &self, req: &BillingRequest, ) -> Result<BillingResponse>

Queries compute billing from BigQuery via the QAI backend.

impl Client

pub async fn contact(&self, req: &ContactRequest) -> Result<StatusResponse>

Sends a contact form message.

This endpoint does not require authentication. A separate HTTP client is used to avoid sending API key headers.

impl Client

pub async fn credit_packs(&self) -> Result<CreditPacksResponse>

List available credit packs. No authentication required.

pub async fn credit_purchase( &self, req: &CreditPurchaseRequest, ) -> Result<CreditPurchaseResponse>

Purchase a credit pack. Returns a checkout URL for payment.

pub async fn credit_balance(&self) -> Result<CreditBalanceResponse>

Get the current credit balance.

pub async fn credit_tiers(&self) -> Result<CreditTiersResponse>

List available credit tiers. No authentication required.

pub async fn dev_program_apply( &self, req: &DevProgramApplyRequest, ) -> Result<DevProgramApplyResponse>

Apply for the developer program.

impl Client

pub async fn extract_document( &self, req: &DocumentRequest, ) -> Result<DocumentResponse>

Extracts text content from a document (PDF, image, etc.).

pub async fn chunk_document( &self, req: &ChunkDocumentRequest, ) -> Result<ChunkDocumentResponse>

Splits a document into chunks suitable for embeddings or RAG.

pub async fn process_document( &self, req: &ProcessDocumentRequest, ) -> Result<ProcessDocumentResponse>

Processes a document with AI (extraction + analysis in one step).

impl Client

pub async fn embed(&self, req: &EmbedRequest) -> Result<EmbedResponse>

Generates text embeddings for the given inputs.

impl Client

pub async fn generate_image(&self, req: &ImageRequest) -> Result<ImageResponse>

Generates images from a text prompt.

pub async fn edit_image( &self, req: &ImageEditRequest, ) -> Result<ImageEditResponse>

Edits images using an AI model.

impl Client

pub async fn create_job( &self, req: &JobCreateRequest, ) -> Result<JobCreateResponse>

Creates an async job. Returns the job ID for polling.

pub async fn get_job(&self, job_id: &str) -> Result<JobStatusResponse>

Checks the status of an async job.

pub async fn list_jobs(&self) -> Result<ListJobsResponse>

Lists all jobs for the account.

pub async fn stream_job(&self, job_id: &str) -> Result<Response>

Opens an SSE stream for a job, returning the raw response. Events: progress, complete, error. Auto-closes on terminal state.

pub async fn poll_job( &self, job_id: &str, poll_interval: Duration, max_attempts: usize, ) -> Result<JobStatusResponse>

Polls a job until completion or timeout. Returns the final status response.

pub async fn generate_3d( &self, model: &str, prompt: Option<&str>, image_url: Option<&str>, ) -> Result<JobCreateResponse>

Convenience method for 3D model generation via the async jobs system.

Submits a job with type "3d/generate" and the given parameters. Returns the job creation response – use poll_job to wait for completion.

pub async fn chat_job(&self, req: &ChatRequest) -> Result<JobCreateResponse>

Submits a chat completion as an async job.

Useful for long-running models (e.g. Opus) where synchronous /qai/v1/chat may time out. Params are the same shape as ChatRequest. Use [stream_job()] or [poll_job()] to get the result.

impl Client

pub async fn remesh(&self, req: &RemeshRequest) -> Result<JobStatusResponse>

Submit a 3D remesh job and poll until completion.

Returns the job result containing model_urls with download links for each requested format (including STL for 3D printing).

pub async fn retexture( &self, req: &RetextureRequest, ) -> Result<JobStatusResponse>

Submit a retexture job — apply new AI-generated textures to a 3D model.

Returns the job result containing model_urls with the retextured model.

pub async fn rig(&self, req: &RigRequest) -> Result<JobStatusResponse>

Submit a rigging job — add a humanoid skeleton to a 3D model.

Returns the job result containing rigged FBX/GLB URLs and basic animations.

pub async fn animate(&self, req: &AnimateRequest) -> Result<JobStatusResponse>

Submit an animation job — apply a motion to a rigged character.

Returns the job result containing animated FBX/GLB URLs.

impl Client

pub async fn create_key( &self, req: &CreateKeyRequest, ) -> Result<CreateKeyResponse>

Creates a new API key with optional scope and spend restrictions.

pub async fn list_keys(&self) -> Result<ListKeysResponse>

Lists all API keys for the account.

pub async fn revoke_key(&self, id: &str) -> Result<StatusResponse>

Revokes an API key by its ID.

impl Client

pub async fn list_models(&self) -> Result<Vec<ModelInfo>>

Returns all available models with provider and pricing information.

pub async fn get_pricing(&self) -> Result<Vec<PricingInfo>>

Returns the complete pricing table for all models.

impl Client

pub async fn rag_search( &self, req: &RagSearchRequest, ) -> Result<RagSearchResponse>

Searches Vertex AI RAG corpora for relevant documentation.

pub async fn rag_corpora(&self) -> Result<Vec<RagCorpus>>

Lists available Vertex AI RAG corpora.

pub async fn surreal_rag_search( &self, req: &SurrealRagSearchRequest, ) -> Result<SurrealRagSearchResponse>

Searches provider API documentation via SurrealDB vector search.

pub async fn surreal_rag_providers(&self) -> Result<SurrealRagProvidersResponse>

Lists available SurrealDB RAG documentation providers.

pub async fn collections_list(&self) -> Result<Vec<Collection>>

Lists the user’s collections plus shared collections.

pub async fn collections_create(&self, name: &str) -> Result<Collection>

Creates a new user-owned collection.

pub async fn collections_get(&self, id: &str) -> Result<Collection>

Gets details for a single collection (must be owned or shared).

pub async fn collections_delete(&self, id: &str) -> Result<String>

Deletes a collection (owner only).

pub async fn collections_documents( &self, collection_id: &str, ) -> Result<Vec<CollectionDocument>>

Lists documents in a collection.

pub async fn collections_upload( &self, collection_id: &str, filename: &str, content: Vec<u8>, ) -> Result<CollectionUploadResult>

Uploads a file to a collection. The server handles the two-step xAI upload (files API + management API) with the master key.

pub async fn collections_search( &self, req: &CollectionSearchRequest, ) -> Result<Vec<CollectionSearchResult>>

Searches across collections (user’s + shared) with hybrid/semantic/keyword mode.

impl Client

pub async fn realtime_connect( &self, config: &RealtimeConfig, ) -> Result<(RealtimeSender, RealtimeReceiver)>

Opens a realtime voice session via WebSocket.

Returns (sender, receiver) for bidirectional communication. The connection is made to {base_url}/qai/v1/realtime with the client’s auth token.

impl Client

pub async fn realtime_session(&self) -> Result<RealtimeSession>

Request an ephemeral token from the QAI proxy for direct voice connection. Call this before realtime_connect_direct to get a scoped token. Pass an optional provider to route to a specific backend (e.g. “openai”).

pub async fn realtime_session_for( &self, provider: Option<&str>, ) -> Result<RealtimeSession>

Request an ephemeral token for a specific provider.

pub async fn realtime_session_with( &self, provider: Option<&str>, body: Value, ) -> Result<RealtimeSession>

Request a realtime session with full configuration. The body is sent as-is to POST /qai/v1/realtime/session. Use this to pass voice, prompt, tools, etc. for ElevenLabs ConvAI.

pub async fn realtime_end( &self, session_id: &str, duration_seconds: u64, ) -> Result<()>

End a realtime session and finalize billing.

pub async fn realtime_refresh(&self, session_id: &str) -> Result<String>

Refresh an ephemeral token for long sessions (>4 min).

impl Client

pub async fn scrape(&self, req: &ScrapeRequest) -> Result<ScrapeResponse>

Submits a doc-scraping job. Returns a job ID for polling.

pub async fn screenshot( &self, req: &ScreenshotRequest, ) -> Result<ScreenshotResponse>

Takes screenshots of URLs. For <=5 URLs, returns results inline. For >5, returns a job ID for async processing.

pub async fn screenshot_job( &self, req: &ScreenshotRequest, ) -> Result<JobCreateResponse>

Submits a large screenshot batch as an async job.

impl Client

pub async fn web_search( &self, req: &WebSearchRequest, ) -> Result<WebSearchResponse>

Performs a Brave web search, returning structured results across web, news, videos, discussions, and infoboxes.

pub async fn search_context( &self, req: &SearchContextRequest, ) -> Result<SearchContextResponse>

Searches the web and returns chunked page content suitable for RAG or context injection into LLM prompts.

pub async fn search_answer( &self, req: &SearchAnswerRequest, ) -> Result<SearchAnswerResponse>

Generates an AI-powered answer grounded in live web search results, with citations.

impl Client

pub async fn chat_session( &self, req: &SessionChatRequest, ) -> Result<SessionChatResponse>

Sends a message within a persistent session.

Sessions maintain conversation history server-side with automatic context compaction. Omit session_id to start a new session.

impl Client

pub async fn generate_video(&self, req: &VideoRequest) -> Result<VideoResponse>

Generates a video from a text prompt.

Video generation is slow (30s-5min). For production use, consider submitting via the Jobs API instead.

pub async fn video_studio( &self, req: &VideoStudioRequest, ) -> Result<JobResponse>

Creates a HeyGen studio video from clips.

pub async fn video_translate( &self, req: &VideoTranslateRequest, ) -> Result<JobResponse>

Translates a video into another language (HeyGen).

pub async fn video_photo_avatar( &self, req: &PhotoAvatarRequest, ) -> Result<JobResponse>

Creates a video from a photo avatar (HeyGen).

pub async fn video_digital_twin( &self, req: &DigitalTwinRequest, ) -> Result<JobResponse>

Creates a video from a digital twin avatar (HeyGen).

pub async fn video_avatars(&self) -> Result<AvatarsResponse>

Lists available HeyGen avatars.

pub async fn video_templates(&self) -> Result<VideoTemplatesResponse>

Lists available HeyGen video templates.

pub async fn video_heygen_voices(&self) -> Result<HeyGenVoicesResponse>

Lists available HeyGen voices.

impl Client

pub async fn list_voices(&self) -> Result<VoicesResponse>

Lists all available TTS voices (built-in and cloned).

pub async fn clone_voice( &self, name: &str, files: Vec<CloneVoiceFile>, ) -> Result<CloneVoiceResponse>

Clones a voice from audio samples.

Sends audio files as multipart form data along with a name for the new voice.

pub async fn delete_voice(&self, id: &str) -> Result<StatusResponse>

Deletes a cloned voice by its ID.

pub async fn voice_library( &self, query: &VoiceLibraryQuery, ) -> Result<SharedVoicesResponse>

Browses the shared voice library with optional filters.

pub async fn add_voice_from_library( &self, public_owner_id: &str, voice_id: &str, name: Option<&str>, ) -> Result<AddVoiceFromLibraryResponse>

Adds a shared voice from the library to the user’s account.

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.