Crate nolgia 

The official Rust SDK for the Nolgia API: generate images, video, audio and 3D, run the NOLGIA Agent, and manage your library.

#[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() 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, is_plan_required and 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 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")].

Re-exports

pub use api::types;

pub use self;

pub use tokio;

pub use self;

Modules

api

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.

blockingblocking

A synchronous client, for programs without an async runtime (feature blocking).

Macros

json

Construct a serde_json::Value from a JSON literal.

Structs

AgentRunResult

The outcome of Client::run_agent.

ApiError

A refusal from the API: a non-2xx response, usually an RFC 7807 problem.

Client

A Nolgia API client.

ClientBuilder

Configures a Client.

Generation

A generation request ready to send: the endpoint and its JSON body.

GenerationResult

A finished, successful generation.

JobError

A job that reached failed or canceled.

JobEvent

One frame of a job’s status stream.

JobHandle

A submitted job. Cheap to clone.

Media

One file a finished job produced.

Page

One page from a cursor-paginated list.

RetryPolicy

How the SDK retries a request the server refused for now (429) or failed to answer (500, 502, 503, 504, or a dropped connection).

RunAgentOptions

Options for Client::run_agent.

SessionEvent

One frame of an agent session’s event stream.

SseEvent

One raw server-sent event.

SubmitOptions

Options for Client::submit_with.

UploadOptions

Options for Client::upload_file and Client::upload_bytes.

Uuid

A Universally Unique Identifier (UUID).

WaitOptions

Options for Client::wait_job.

Enums

AgentRunStatus

How an agent run ended.

Error

Every way an SDK call can fail.

ErrorCode

The machine-readable code the API puts on a refusal (error.code) or a failed job (failure.code).

Value

Represents any valid JSON value.

Constants

API_KEY_ENV

The environment variable Client::from_env reads the API key from.

BASE_URL_ENV

The environment variable Client::from_env reads the base URL from.

DEFAULT_BASE_URL

The production API.

STAGING_BASE_URL

The staging API. Staging keys are minted on stg.nolgia.ai and do not work against production.

TOKEN_ENV

Also accepted for the API key, as the CLI and the other SDKs’ examples use it.

Traits

IntoGeneration

Anything Client::submit accepts. Implemented for the typed generation requests, their builders, and Generation.

Stream

A stream of values produced asynchronously.

StreamExt

An extension trait for Streams that provides a variety of convenient combinator functions.

Typed

Turns a generated call’s result into nolgia::Result<T>: the response body, or a typed Error whose ApiError carries the problem’s status, code, detail and request_id.

Functions

audio

Audio: POST /generate/audio with model and prompt (the text to speak for a voice model, the description for music and sound). Pick a voice with .set("voice", "..."); GET /voices and GET /models list them.

content_type_for

The MIME type the upload endpoint expects for a file name, from its extension. None for a type the API does not accept.

image

An image generation: POST /generate/image with model and prompt. Add any other field of GenerateImageRequest with Generation::set.

paginate

Every item of a cursor-paginated list, fetching pages as the stream is read.

video

A video generation: POST /generate/video with model and prompt. Add duration_seconds, aspect_ratio, reference assets and the rest with Generation::set.

Type Aliases

QuestionHandler

Answers the agent’s closing question; None ends the run with AgentRunStatus::AwaitingInput.

Result

Result<T, nolgia::Error>.

StatusCallback

Called with each new state of a job while waiting.