nolgia (Python SDK)

Official Python client for the Nolgia API, generated from api/openapi.yaml with openapi-python-client (httpx-based). Published on PyPI as 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

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 (or POST /pat with a signed-in session). The plaintext token is shown once.

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

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.

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

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