---
title: Client setup
description: Install and configure a client for TypeScript, Python, Rust or Go, point it at production or staging, and keep the token out of your code.
---

# Client setup

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](../api/) and [OpenAPI spec](../api/openapi.yaml).

## Installation

Choose one client. These are the installation commands used by the [Quick Start](./getting-started.html).

```bash tab="npm"
$ npm install @nolgia/sdk
```

```bash tab="yarn"
$ yarn add @nolgia/sdk
```

```bash tab="pnpm"
$ pnpm add @nolgia/sdk
```

```bash tab="bun"
$ bun add @nolgia/sdk
```

```bash tab="pip"
$ pip install nolgia
```

```bash tab="uv"
$ uv add nolgia
```

```bash tab="cargo"
$ cargo add nolgia-client
```

```bash tab="Homebrew"
$ brew install nolgiainc/nolgia/nolgia
```

```bash tab="curl installer"
$ curl -fsSL https://raw.githubusercontent.com/nolgiainc/nolgia-cli/main/install.sh | bash
```

```bash tab="curl"
$ curl https://api.nolgia.ai/v1/me -H "Authorization: Bearer $NOLGIA_TOKEN"
```

## Configuration

Create a Personal Access Token using [Get your API key](./authentication.html), then read it from the environment rather than writing it into your source.

```bash
$ export NOLGIA_TOKEN=nol_...
```

<!-- gen:spec-servers -->
| Environment | Base URL |
| --- | --- |
| Production | `https://api.nolgia.ai/v1` |
| Staging | `https://api.stg.nolgia.ai/v1` |
| Local development | `http://localhost:8080/v1` |
<!-- /gen -->

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.

```ts tab="TypeScript"
import { createNolgiaClient } from "@nolgia/sdk";

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

```python tab="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 tab="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](./headers.html).

## 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.

```bash tab="curl"
$ curl --fail-with-body -sS https://api.nolgia.ai/v1/me \
  -H "Authorization: Bearer $NOLGIA_TOKEN"
```

```bash tab="CLI"
$ nolgia account me --json
```

```ts tab="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 tab="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())
```

```rust tab="Rust" title="src/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.

```json title="200: current account"
{
  "id": "dad27b53-a85b-4e3d-8fd6-b152c803a27c",
  "email": "you@example.com",
  "active_organization": null,
  "generation_limits": {
    "concurrent_active": 0,
    "concurrent_max": 8
  }
}
```

<!-- gen:fields schema=User only=id,email,active_organization,generation_limits -->
| 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. |
<!-- /gen -->

<!-- gen:fields schema=GenerationLimits -->
| 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. |
<!-- /gen -->

### Parameters reference

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

<!-- gen:params op=getCurrentUser -->
| Parameter | In | Required | Description |
| --- | --- | --- | --- |
<!-- /gen -->

## 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](./subscribe.html) 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.

> [!WARNING]
> Never ship a PAT to a browser or mobile app. Client source, bundled configuration and network requests are visible to the person running the app.

:::cards
- [Proxy setup](./proxy-setup.html): Keep the PAT on your server with a small allow-list of API routes.
:::

## 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.

```json title="401: invalid authentication"
{"type":"about:blank","title":"Unauthorized","status":401,"detail":"valid authentication is required"}
```

<!-- gen:fields schema=Error -->
| 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 |  |
<!-- /gen -->

## Client versions

<!-- gen:sdk-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 |
<!-- /gen -->

## Next steps

:::cards
- [Quick Start](./getting-started.html): Generate an image and a video with the published clients.
- [Proxy setup](./proxy-setup.html): Call Nolgia from your browser through your own server.
- [Synchronous: subscribe](./subscribe.html): Submit and wait with the endpoint interfaces, and meet the 0.1.2 helpers.
- [Libraries, APIs and community](./client-libraries.html): Find packages, interfaces and support.
:::