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

Requires Python 3.10 or later.

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)

Wait for completion and handle moderation

The helper retries long-poll timeouts for up to 30 minutes by default and returns the job as a JSON dict. A wait timeout leaves the job running.

from nolgia.job_wait import JobModeratedError, wait_for_job

try:
    done = wait_for_job(client, str(job.id))
    print(done["asset"]["signed_url"])
except JobModeratedError as error:
    print(error.message, error.credits_refunded)

failure.credits_refunded reports what the ledger did: true means refunded, false means charged, and absent or null means unknown. Never read an absent value as "no charge".

Submit and subscribe

subscribe submits, polls, and returns the final media URLs with the raw job.

import os; from nolgia import AuthenticatedClient, subscribe
client = AuthenticatedClient(base_url="https://api.nolgia.ai/v1", token=os.environ["NOLGIA_TOKEN"])
result = subscribe(client, "/generate/image", {"model": "flux-pro", "prompt": "a paper-cut mountain range"},
                   on_status=lambda u: print(u.status, u.progress))
print(result.url)

model is required on every generation request; GET /models is the live catalog of ids, capabilities and prices. subscribe covers the endpoints that answer 202 with a job: /generate/image, /generate/audio, /generate/video, /generate/3d and /restore/video. /generate/set is not one of them: it answers with an OutputSet polled through GET /sets/{id}.

submit accepts the same arguments and returns a handle with job_id, the raw submit job, status(), cancel(), and a memoized synchronous result(). Polling starts only when result() is first called. Status callbacks fire immediately and on changes; callback exceptions propagate. NolgiaGenerationError carries an open code, http_status, job_id, and the raw terminal job when available.

poll_interval defaults to 0.5 seconds and max_poll_time to 1800 seconds. Timing out only stops waiting; it does not cancel generation, and credits are still spent. cancel() cancels the job on the server (POST /jobs/{id}/cancel), returns the canceled job and makes result() raise code canceled. The job's cancellation says what the model provider did and whether the credits were refunded: a job that had not reached the provider is refunded in full, and a started render is refunded only when the provider stops it without billing (settlement can read pending until the provider answers). A canceled job is never added to your library. A job that already finished raises code job_not_cancellable and keeps its own result.

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

Older published Python SDK versions raise ValueError on unknown generation refusal codes. Upgrade the Python SDK to handle the specific refusal codes and guidance.