Metadata-Version: 2.5
Name: nolgia
Version: 0.1.1
Summary: Official Python client for the Nolgia API (generative media: image, audio, video)
Project-URL: Homepage, https://nolgia.ai
Project-URL: Documentation, https://nolgiainc.github.io/nolgia-api/api/
Author-email: Nolgia Engineering <contact@nolgia.ai>
License: Proprietary
Requires-Python: >=3.9
Requires-Dist: attrs>=22.2.0
Requires-Dist: httpx<0.29,>=0.23.0
Requires-Dist: python-dateutil<3,>=2.8.0
Description-Content-Type: text/markdown

# nolgia (Python SDK)

Official Python client for the [Nolgia API](https://docs.nolgia.ai), generated
from [`api/openapi.yaml`](../../api/openapi.yaml) with
[openapi-python-client](https://github.com/openapi-generators/openapi-python-client)
(httpx-based). Published on PyPI as [`nolgia`](https://pypi.org/project/nolgia/).

Every endpoint module exposes `sync`, `sync_detailed`, `asyncio` and
`asyncio_detailed` variants. Each `sync` call returns the typed success model,
or an `Error` (an RFC 7807 problem object) when the API refused the request.

## Install

```bash
pip install nolgia
```

## Authenticate

Requests carry a Personal Access Token (`nol_...`) as a bearer token. Create
one in the app at [nolgia.com/settings/api-tokens](https://nolgia.com/settings/api-tokens)
(or `POST /pat` with a signed-in session). The plaintext token is shown once.

```python
from nolgia import AuthenticatedClient

client = AuthenticatedClient(base_url="https://api.nolgia.ai/v1", token="nol_...")
```

## First image

`POST /generate/image` is asynchronous: it answers `202` with a job. Long-poll
`GET /jobs/{id}/wait` for the finished asset (images usually land in seconds).

```python
from nolgia.api.generate import generate_image
from nolgia.api.jobs import wait_for_job
from nolgia.models import GenerateImageRequest, ImageModel, Job

job = generate_image.sync(
    client=client,
    body=GenerateImageRequest(model=ImageModel.GPT_IMAGE_2, prompt="a red fox in the snow"),
)
if not isinstance(job, Job):
    raise SystemExit(f"refused: {job}")

done = wait_for_job.sync(job.id, client=client, timeout_seconds=120)
if isinstance(done, Job) and done.status == "succeeded":
    print(done.asset.signed_url)
```

## First video

Video is the same job model with a longer wait (`timeout_seconds` up to 900).
A `408` from `wait` means the job is still running: call it again.

```python
from nolgia.api.generate import generate_video
from nolgia.models import GenerateVideoRequest, VideoModel

job = generate_video.sync(
    client=client,
    body=GenerateVideoRequest(
        model=VideoModel.SEEDANCE_2_5,
        prompt="a red fox trots through fresh snow at dawn, slow dolly in",
        duration_seconds=5,
    ),
)
if not isinstance(job, Job):
    raise SystemExit(f"refused: {job}")

done = wait_for_job.sync(job.id, client=client, timeout_seconds=600)
if isinstance(done, Job) and done.status == "succeeded":
    print(done.asset.signed_url)
```

## List assets

```python
from nolgia.api.assets import list_assets
from nolgia.models import AssetPage

page = list_assets.sync(client=client, limit=10)
if isinstance(page, AssetPage):
    for asset in page.items:
        print(asset.id, asset.modality, asset.signed_url)
```

## Staging

Point the client at staging with
`AuthenticatedClient(base_url="https://api.stg.nolgia.ai/v1", token="nol_...")`.
Staging tokens are minted on [stg.nolgia.ai](https://stg.nolgia.ai) and do not
work against production.

## Docs

- Getting started: <https://docs.nolgia.ai/guides/getting-started.html>
- API reference: <https://docs.nolgia.ai/api/>
- Developer portal: <https://nolgia.com/developers>

## Layout

- `nolgia/`: **generated**, do not edit; regenerate with `make sdk-python` from the repo root
- `pyproject.toml`, `README.md`, `config.yaml`: hand-written
