nolgia/
lib.rs

1//! The official Rust SDK for the [Nolgia API](https://docs.nolgia.ai):
2//! generate images, video, audio and 3D, run the NOLGIA Agent, and manage
3//! your library.
4//!
5//! ```no_run
6//! #[nolgia::tokio::main(crate = "nolgia::tokio")]
7//! async fn main() -> nolgia::Result<()> {
8//!     let nolgia = nolgia::Client::from_env()?; // NOLGIA_API_KEY
9//!     let done = nolgia.subscribe(nolgia::image("gpt-image-2", "a red fox in the snow")).await?;
10//!     nolgia.download(done.url().unwrap(), "fox.png").await?;
11//!     Ok(())
12//! }
13//! ```
14//!
15//! # Layout
16//!
17//! - [`Client`] is the entry point. Build it with [`Client::new`] (an API
18//!   key), [`Client::from_env`] (`NOLGIA_API_KEY`, `NOLGIA_BASE_URL`) or
19//!   [`Client::builder`] (base URL, timeouts, [`RetryPolicy`], idempotency).
20//! - Every API operation is a method on it, generated from the OpenAPI spec
21//!   ([`api::Client`]): `nolgia.list_models().send()`. Request and response
22//!   types live in [`types`]. Append [`.typed()`](Typed::typed) to get a
23//!   [`Result`] with a typed [`Error`].
24//! - Hand-written helpers cover the workflows: [`image`], [`video`] and
25//!   [`audio`] build a request, [`Client::submit`] /
26//!   [`Client::subscribe`] / [`Client::wait_job`] for generation,
27//!   [`Client::quote`] for prices, [`Client::upload_file`] and
28//!   [`Client::download`] for files, [`Client::paginate_assets`] for lists,
29//!   [`Client::job_events`] and [`Client::session_events`] for live streams,
30//!   and [`Client::run_agent`] for the agent.
31//! - [`blocking::Client`] (feature `blocking`) does the same without async.
32//!
33//! # Errors
34//!
35//! [`Error::Api`] is a refusal: its [`ApiError`] carries the HTTP status, the
36//! machine-readable [`ErrorCode`], the `detail` to show and the `request_id`
37//! for support, with [`is_out_of_credits`](ApiError::is_out_of_credits),
38//! [`is_plan_required`](ApiError::is_plan_required) and
39//! [`is_rate_limited`](ApiError::is_rate_limited) for the common branches.
40//! [`Error::Job`] is a generation that failed or was canceled, with its code
41//! and whether the credits were refunded.
42//!
43//! # Retries and idempotency
44//!
45//! Requests the server refused for now (`429`) or failed to answer (`5xx`,
46//! a dropped connection) are retried with exponential backoff, honouring
47//! `Retry-After`, when repeating them cannot do the work twice. Generation
48//! submits are safe to repeat: the API refuses an identical submit within
49//! five minutes with `409` naming the existing job, and [`Client::submit`]
50//! resolves its own retry onto that job. Set an `Idempotency-Key`
51//! ([`SubmitOptions`], [`Client::with_idempotency_key`]) to declare a
52//! deliberate new generation of an identical request.
53//!
54//! # Runtime
55//!
56//! The SDK is async on [tokio], re-exported as [`nolgia::tokio`](tokio) with
57//! [`serde_json`] and [`json!`], so `cargo add nolgia` is the whole install.
58//! `#[tokio::main]` needs `use nolgia::tokio;` in scope, or write
59//! `#[nolgia::tokio::main(crate = "nolgia::tokio")]`.
60
61#![cfg_attr(docsrs, feature(doc_cfg))]
62#![warn(missing_docs)]
63
64/// The generated client: one method per API operation, request builders in
65/// [`api::builder`], schemas in [`api::types`]. Generated by `make sdk-rust`
66/// from the public OpenAPI spec; do not edit.
67#[allow(missing_docs)]
68#[rustfmt::skip]
69pub mod api;
70
71mod agent;
72#[cfg(feature = "blocking")]
73#[cfg_attr(docsrs, doc(cfg(feature = "blocking")))]
74pub mod blocking;
75mod client;
76mod error;
77mod files;
78mod jobs;
79mod pagination;
80mod stream;
81mod transport;
82
83pub use agent::{AgentRunResult, AgentRunStatus, QuestionHandler, RunAgentOptions};
84pub use api::types;
85pub use client::{
86    API_KEY_ENV, BASE_URL_ENV, Client, ClientBuilder, DEFAULT_BASE_URL, STAGING_BASE_URL,
87    TOKEN_ENV, Typed,
88};
89pub use error::{ApiError, Error, ErrorCode, JobError, Result};
90pub use files::{UploadOptions, content_type_for};
91pub use jobs::{
92    Generation, GenerationResult, IntoGeneration, JobHandle, Media, StatusCallback, SubmitOptions,
93    WaitOptions, audio, image, video,
94};
95pub use pagination::{Page, paginate};
96pub use stream::{JobEvent, SessionEvent, SseEvent};
97pub use transport::RetryPolicy;
98
99pub use futures_util::{Stream, StreamExt};
100pub use serde_json::{self, Value, json};
101pub use tokio;
102pub use uuid::{self, Uuid};
103
104/// The README's code blocks, compiled as doctests so they cannot drift from
105/// the crate.
106#[cfg(doctest)]
107#[doc = include_str!("../README.md")]
108pub struct ReadmeDoctests;
nolgia/lib.rs

nolgia/
lib.rs
