Model APIs

Client setup

On this page
  1. Installation
  2. Configuration
  3. Making your first call
    1. Parameters reference
  4. Client methods
  5. Server-side or browser?
  6. Error responses
  7. Client versions
  8. Next steps

Choose a published client, set NOLGIA_TOKEN in your server environment, and check the connection with GET /me. The clients use the same endpoint paths and request fields as the API reference and OpenAPI spec.

Installation #

Choose one client. These are the installation commands used by the Quick Start.

shell
npm install @nolgia/sdk
shell
yarn add @nolgia/sdk
shell
pnpm add @nolgia/sdk
shell
bun add @nolgia/sdk
shell
pip install nolgia
shell
uv add nolgia
shell
cargo add nolgia-client
shell
brew install nolgiainc/nolgia/nolgia
shell
curl -fsSL https://raw.githubusercontent.com/nolgiainc/nolgia-cli/main/install.sh | bash
shell
curl https://api.nolgia.ai/v1/me -H "Authorization: Bearer $NOLGIA_TOKEN"

Configuration #

Create a Personal Access Token using Get your API key, then read it from the environment rather than writing it into your source.

shell
export NOLGIA_TOKEN=nol_...
Environment Base URL
Production https://api.nolgia.ai/v1
Staging https://api.stg.nolgia.ai/v1
Local development http://localhost:8080/v1

Use the full base URL including the version prefix shown in the table. TypeScript defaults to production; Python and Rust take the base URL explicitly. Pass the staging URL from the table when configuring a staging client.

TypeScript
import { createNolgiaClient } from "@nolgia/sdk";

const nolgia = createNolgiaClient(process.env.NOLGIA_TOKEN!, undefined, {
  headers: { "X-Nolgia-Surface": "pipeline" },
});
Python
import os
from nolgia import AuthenticatedClient

client = AuthenticatedClient(
    base_url="https://api.nolgia.ai/v1",
    token=os.environ["NOLGIA_TOKEN"],
    headers={"X-Nolgia-Surface": "pipeline"},
)
Rust
use nolgia_client::ClientBuilder;

let client = ClientBuilder::new("https://api.nolgia.ai/v1")
    .bearer_token(std::env::var("NOLGIA_TOKEN")?)
    .surface("pipeline")
    .idempotency_key("my-generation-1")
    .build()?;
Client Constructor or option Meaning
TypeScript createNolgiaClient(token, baseUrl?, options?) The third argument accepts openapi-fetch options, including headers and a custom fetch.
Python AuthenticatedClient(base_url=…, token=…, headers=…) Sets the base URL, bearer token and additional headers; generated endpoint modules accept this client.
Rust ClientBuilder::new(base_url) Set the bearer token, optional calling surface and optional idempotency key, then call build().

An idempotency key on the client is sent on every request. Reuse it for retries of one generation; choose a new key for a deliberate repeat of identical input. See Platform headers.

Making your first call #

GET /me identifies the authenticated account and reports its current generation limits. It does not submit a generation or spend credits.

shell
curl --fail-with-body -sS https://api.nolgia.ai/v1/me \
  -H "Authorization: Bearer $NOLGIA_TOKEN"
shell
nolgia account me --json
TypeScript
import { createNolgiaClient } from "@nolgia/sdk";

const nolgia = createNolgiaClient(process.env.NOLGIA_TOKEN!);
const { data, error } = await nolgia.GET("/me");
if (error) throw new Error(`${error.title}: ${error.detail ?? ""}`);
console.log(data);
Python
import os
from nolgia import AuthenticatedClient
from nolgia.api.auth import get_current_user
from nolgia.models import User

client = AuthenticatedClient(base_url="https://api.nolgia.ai/v1", token=os.environ["NOLGIA_TOKEN"])
user = get_current_user.sync(client=client)
if not isinstance(user, User):
    raise SystemExit(f"refused: {user}")
print(user.to_dict())
Rustsrc/main.rs
use nolgia_client::ClientBuilder;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = ClientBuilder::new("https://api.nolgia.ai/v1")
        .bearer_token(std::env::var("NOLGIA_TOKEN")?)
        .build()?;
    let user = client.get_current_user().send().await?.into_inner();
    println!("{user:?}");
    Ok(())
}

The captured production response below preserves the account id; only the email is replaced.

JSON200: current account
{
  "id": "dad27b53-a85b-4e3d-8fd6-b152c803a27c",
  "email": "you@example.com",
  "active_organization": null,
  "generation_limits": {
    "concurrent_active": 0,
    "concurrent_max": 8
  }
}
Field Type Required Description
id string Yes
email string Yes
active_organization UserOrganization, nullable No The organization the user is currently working in, or null in the personal space.
generation_limits GenerationLimits, nullable No Current shared generation concurrency across image, audio, and video.
Field Type Required Description
concurrent_max integer Yes Maximum generations this account may run at once on its effective plan.
concurrent_active integer Yes Generations currently running across image, audio, and video.

Parameters reference #

GET /me has no path or query parameters. Send your bearer token with the request.

Parameter In Required Description

Client methods #

Client Published interface today Submit and wait
TypeScript Typed GET, POST and other HTTP methods from openapi-fetch. The Quick Start's finish() loop calls the typed wait endpoint.
Python Typed request and response models, with synchronous and asynchronous functions in endpoint modules. Call nolgia.api.jobs.wait_for_job in the Quick Start's finish() loop.
Rust Typed request builders ending in send().await. Call wait_for_job() in the Quick Start's finish() loop.
Go Generated endpoint methods and request/response types in the private repository. Use the job and wait endpoints directly.
CLI Commands for generation, account, models and assets. nolgia gen image … --out first.png waits and downloads; nolgia wait <id> follows an existing job.
Convenience layer (0.1.2) subscribe / submit, shipping in TypeScript and Python 0.1.2; the Rust crate keeps its own helper. The synchronous guide documents the upcoming helpers and today's published-client equivalent.

Server-side or browser? #

Use these token-bearing clients in a server, worker, or a script you control. A browser or mobile application sends requests to your own authenticated backend, which adds the PAT and forwards only the routes your product needs.

Error responses #

GET /me returns 401 Unauthorized when authentication is invalid. Replace a missing, expired or revoked token; retrying it unchanged will not help. A 402 / out_of_credits response from a generation call instead concerns the wallet, not your token.

JSON401: invalid authentication
{"type":"about:blank","title":"Unauthorized","status":401,"detail":"valid authentication is required"}
Field Type Required Description
code string No Machine-readable error code.…
type string Yes A URI reference identifying the problem type.
title string Yes
status integer Yes
detail string No
instance string No
job_id string No The job this refusal points at, so a client can follow it without reading detail.…
request_id string No

Client versions #

Client Package Version
TypeScript @nolgia/sdk 0.1.4
Python nolgia on PyPI 0.1.4
Rust nolgia-client published with the CLI release; see crates.io

Next steps #