Model APIs
Client setup
On this page
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.
npm install @nolgia/sdk
yarn add @nolgia/sdk
pnpm add @nolgia/sdk
bun add @nolgia/sdk
pip install nolgia
uv add nolgia
cargo add nolgia-client
brew install nolgiainc/nolgia/nolgia
curl -fsSL https://raw.githubusercontent.com/nolgiainc/nolgia-cli/main/install.sh | bash
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.
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.
import { createNolgiaClient } from "@nolgia/sdk";
const nolgia = createNolgiaClient(process.env.NOLGIA_TOKEN!, undefined, {
headers: { "X-Nolgia-Surface": "pipeline" },
});
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"},
)
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.
curl --fail-with-body -sS https://api.nolgia.ai/v1/me \
-H "Authorization: Bearer $NOLGIA_TOKEN"
nolgia account me --json
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);
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())
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.
{
"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.
{"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 |

