NOLGIANOLGIADocs

Model APIs

Inference methods

On this page
  1. Synchronous helper
    1. Parameters
  2. Submit and poll
    1. Parameters
  3. Long-poll with wait
    1. Parameters
  4. Status stream
    1. Parameters
  5. Provider callbacks
    1. Parameters
  6. Agent
    1. Parameters
  7. Error responses
  8. Getting started

Submit a generation once, then choose how your application follows the job. A blocking script, background worker and live progress display can all use the same job id and finished asset.

Method How it works When to use it Page
subscribe() (TypeScript and Python 0.1.2; the Rust crate keeps its own) The helper submits and polls until it has a result. A script that needs a finished asset before continuing. Synchronous: subscribe
Submit and poll Submit returns immediately; read GET /jobs/{id} later. Durable background workers and parallel jobs. Asynchronous: submit and poll
Long-poll GET /jobs/{id}/wait waits within one HTTP request. A worker that can keep a connection open. Long-poll with wait
Status stream A single-use ticket authorizes an SSE connection. A UI that should react as job state changes. Streaming
Provider callbacks The provider wakes the server's poller; you still read the job. Automatic server-side completion detection. Callbacks and webhooks
Agent A persistent conversation requests generations and retains its assets. Multi-step work directed through conversation. Agent Sessions API

The helpers ship in TypeScript and Python 0.1.2. The published clients already expose the raw endpoints below.

Method Path What it does
POST /jobs/cost Price a generation before submitting it.
GET /jobs List jobs for the current user.
GET /jobs/{id} Get a single job.
GET /jobs/{id}/wait Block until the job reaches a terminal state (or timeout).
POST /jobs/{id}/cancel Cancel a job, and stop it at the model provider where the provider allows it.
POST /jobs/{id}/sse-ticket Mint a single-use ticket for the job status stream.
GET /jobs/{id}/sse Stream job status updates over Server-Sent Events.
POST /callbacks/{provider} Receive a render provider's completion callback (a wake-up signal).
The job lifecycle Your app submits a video generation job, the Nolgia API accepts it as queued, runs it, and it ends as succeeded or failed (or canceled, when its owner stops it), after which credits are settled. Your app long-polls the wait endpoint while the job runs. Your app Nolgia API POST /generate/video GET /jobs/{id}/wait 202 Accepted job queued running succeeded failed + failure.code settle: credits released or charged long-poll, up to 120 s per call
A job progresses from submission to a terminal result

Synchronous helper #

Use this pattern when the next step in a script depends on the finished file. Submission is still asynchronous on the server; the client supplies the blocking behavior by waiting for the job. Today, make the same calls with a published client or with curl:

shell
curl -sS https://api.nolgia.ai/v1/generate/image \
  -H "Authorization: Bearer $NOLGIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model":"flux-pro","prompt":"a paper-cut mountain range at dawn"}'
curl -sS "https://api.nolgia.ai/v1/jobs/<id from the response>/wait?timeout_seconds=120" \
  -H "Authorization: Bearer $NOLGIA_TOKEN"

Parameters #

Pass the same model-specific body you would send to the generation endpoint. The wait uses the returned job id and a timeout_seconds window; the helper's polling interval and client timeout are documented on its page.

Submit and poll #

Use this method when a request handler or worker needs to return immediately and continue elsewhere. Submit to the appropriate generation endpoint, save the response's id, and read the job whenever you need its latest state.

shell
curl --fail-with-body -sS "https://api.nolgia.ai/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $NOLGIA_TOKEN"

Parameters #

Parameter In Required Description
id path Yes Job UUID.

queued and running are non-terminal. Stop polling on succeeded, failed or canceled; read asset for success and failure for failure. A 404 means this job could not be found for your request, not that the model is still running.

Long-poll with wait #

Use long-polling when you want the server to hold a connection until the job is terminal, avoiding repeated status reads during that window. A terminal job returns immediately; a running job can outlast the window without failing.

shell
curl --fail-with-body -sS "https://api.nolgia.ai/v1/jobs/$JOB_ID/wait?timeout_seconds=120" \
  -H "Authorization: Bearer $NOLGIA_TOKEN"

Parameters #

Parameter In Required Description
id path Yes Job UUID.
timeout_seconds query No

timeout_seconds is a query parameter with a maximum of 900 seconds. A window that expires returns 408 with code timeout; call the endpoint again. The job's execution deadline is a separate server policy described in Reliability.

Status stream #

Use SSE when a progress display should update as soon as state changes arrive. Mint a ticket with your bearer token, then open the stream using only that single-use ticket; the stream reports status changes and a final complete event, not unfinished media.

shell
curl -sS -X POST "https://api.nolgia.ai/v1/jobs/$JOB_ID/sse-ticket" -H "Authorization: Bearer $NOLGIA_TOKEN"
curl -N "https://api.nolgia.ai/v1/jobs/$JOB_ID/sse?ticket=<ticket from the response>"

Parameters #

Parameter In Required Description
id path Yes Job UUID.
ticket query Yes Single-use ticket from POST /jobs/{id}/sse-ticket.

Request a fresh ticket for a new connection: reuse or expiry does not authorize another stream. Ticket issuance can return 401, 404 or 503; opening the stream can return 401, 403 or 503.

Provider callbacks #

Supported providers send a signed callback to Nolgia when there is something to read, waking the poller immediately. This is automatic and requires no endpoint in your application. It is useful regardless of which client method you chose; continue reading the same job to observe completion.

shell
curl --fail-with-body -sS "https://api.nolgia.ai/v1/jobs/$JOB_ID" \
  -H "Authorization: Bearer $NOLGIA_TOKEN"

Parameters #

There are no customer callback parameters to set. POST /callbacks/{provider} accepts signed provider traffic, not a customer webhook registration; its receipt is a wake-up signal, and the normal result read determines settlement.

Agent #

Use an agent session for a conversation that plans work, chooses tools and creates assets over multiple turns. Start by creating the session; creating it does not itself generate media. Send a message through the Agent Sessions API to ask for the work.

shell
curl --fail-with-body -sS https://api.nolgia.ai/v1/agent/sessions \
  -H "Authorization: Bearer $NOLGIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Docs quickstart"}'

Parameters #

Field Type Required Description
name string Yes
project_id string No Project (owned by the caller) to scope the session to.
preset_slug string No Preset to run the session under. Must name an existing public preset (400 otherwise); the agent receives the preset's guardrails and output context on every turn.
campaign SessionCampaign No Marketing attribution for this launch, when the session was started from a campaign link (nolgia.ai/p/<slug>?utm_source=...).…

The session response is 201 with an id. Follow subsequent turns through the session's events stream and list its assets when the agent creates media; a session id is not a generation job id.

Error responses #

Operation Status and exact code Next action
Generate 400 validation Correct the request's inputs.
Generate 402 out_of_credits Add credits or choose a request the wallet can pay for.
Generate 409, with the earlier job_id Follow the previously accepted job instead of resubmitting.
Generate with a confirmation token 422 confirmation_rejected Re-quote the final request.
Generate at a concurrency or quota ceiling 429 rate_limit Wait for capacity or the supplied quota reset time.
Authenticated call 401, no generation code required Replace the bad or expired token.
Read a job 404, no generation code required Check the job id and account context.
Long-poll 408 timeout Continue waiting; this response is not a terminal job failure.

An accepted job can fail after submission; inspect its failure.code rather than the HTTP status of a successful status read. See Errors for the complete code reference.

Getting started #