nolgia 0.1.0

Official Rust SDK for the Nolgia API: image, video, audio and agent generation, generated from the OpenAPI spec
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108

//! The official Rust SDK for the [Nolgia API](https://docs.nolgia.ai):
//! generate images, video, audio and 3D, run the NOLGIA Agent, and manage
//! your library.
//!
//! ```no_run
//! #[nolgia::tokio::main(crate = "nolgia::tokio")]
//! async fn main() -> nolgia::Result<()> {
//!     let nolgia = nolgia::Client::from_env()?; // NOLGIA_API_KEY
//!     let done = nolgia.subscribe(nolgia::image("gpt-image-2", "a red fox in the snow")).await?;
//!     nolgia.download(done.url().unwrap(), "fox.png").await?;
//!     Ok(())
//! }
//! ```
//!
//! # Layout
//!
//! - [`Client`] is the entry point. Build it with [`Client::new`] (an API
//!   key), [`Client::from_env`] (`NOLGIA_API_KEY`, `NOLGIA_BASE_URL`) or
//!   [`Client::builder`] (base URL, timeouts, [`RetryPolicy`], idempotency).
//! - Every API operation is a method on it, generated from the OpenAPI spec
//!   ([`api::Client`]): `nolgia.list_models().send()`. Request and response
//!   types live in [`types`]. Append [`.typed()`](Typed::typed) to get a
//!   [`Result`] with a typed [`Error`].
//! - Hand-written helpers cover the workflows: [`image`], [`video`] and
//!   [`audio`] build a request, [`Client::submit`] /
//!   [`Client::subscribe`] / [`Client::wait_job`] for generation,
//!   [`Client::quote`] for prices, [`Client::upload_file`] and
//!   [`Client::download`] for files, [`Client::paginate_assets`] for lists,
//!   [`Client::job_events`] and [`Client::session_events`] for live streams,
//!   and [`Client::run_agent`] for the agent.
//! - [`blocking::Client`] (feature `blocking`) does the same without async.
//!
//! # Errors
//!
//! [`Error::Api`] is a refusal: its [`ApiError`] carries the HTTP status, the
//! machine-readable [`ErrorCode`], the `detail` to show and the `request_id`
//! for support, with [`is_out_of_credits`](ApiError::is_out_of_credits),
//! [`is_plan_required`](ApiError::is_plan_required) and
//! [`is_rate_limited`](ApiError::is_rate_limited) for the common branches.
//! [`Error::Job`] is a generation that failed or was canceled, with its code
//! and whether the credits were refunded.
//!
//! # Retries and idempotency
//!
//! Requests the server refused for now (`429`) or failed to answer (`5xx`,
//! a dropped connection) are retried with exponential backoff, honouring
//! `Retry-After`, when repeating them cannot do the work twice. Generation
//! submits are safe to repeat: the API refuses an identical submit within
//! five minutes with `409` naming the existing job, and [`Client::submit`]
//! resolves its own retry onto that job. Set an `Idempotency-Key`
//! ([`SubmitOptions`], [`Client::with_idempotency_key`]) to declare a
//! deliberate new generation of an identical request.
//!
//! # Runtime
//!
//! The SDK is async on [tokio], re-exported as [`nolgia::tokio`](tokio) with
//! [`serde_json`] and [`json!`], so `cargo add nolgia` is the whole install.
//! `#[tokio::main]` needs `use nolgia::tokio;` in scope, or write
//! `#[nolgia::tokio::main(crate = "nolgia::tokio")]`.

#![cfg_attr(docsrs, feature(doc_cfg))]
#![warn(missing_docs)]

/// The generated client: one method per API operation, request builders in
/// [`api::builder`], schemas in [`api::types`]. Generated by `make sdk-rust`
/// from the public OpenAPI spec; do not edit.
#[allow(missing_docs)]
#[rustfmt::skip]
pub mod api;

mod agent;
#[cfg(feature = "blocking")]
#[cfg_attr(docsrs, doc(cfg(feature = "blocking")))]
pub mod blocking;
mod client;
mod error;
mod files;
mod jobs;
mod pagination;
mod stream;
mod transport;

pub use agent::{AgentRunResult, AgentRunStatus, QuestionHandler, RunAgentOptions};
pub use api::types;
pub use client::{
    API_KEY_ENV, BASE_URL_ENV, Client, ClientBuilder, DEFAULT_BASE_URL, STAGING_BASE_URL,
    TOKEN_ENV, Typed,
};
pub use error::{ApiError, Error, ErrorCode, JobError, Result};
pub use files::{UploadOptions, content_type_for};
pub use jobs::{
    Generation, GenerationResult, IntoGeneration, JobHandle, Media, StatusCallback, SubmitOptions,
    WaitOptions, audio, image, video,
};
pub use pagination::{Page, paginate};
pub use stream::{JobEvent, SessionEvent, SseEvent};
pub use transport::RetryPolicy;

pub use futures_util::{Stream, StreamExt};
pub use serde_json::{self, Value, json};
pub use tokio;
pub use uuid::{self, Uuid};

/// The README's code blocks, compiled as doctests so they cannot drift from
/// the crate.
#[cfg(doctest)]
#[doc = include_str!("../README.md")]
pub struct ReadmeDoctests;