--- title: Inference methods description: "The ways to run a model and follow it: a blocking helper, submit and poll, long-poll, a server-sent event stream, and provider callbacks that wake the poller." --- # Inference methods 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](./subscribe.html) | | Submit and poll | Submit returns immediately; read `GET /jobs/{id}` later. | Durable background workers and parallel jobs. | [Asynchronous: submit and poll](./jobs.html) | | Long-poll | `GET /jobs/{id}/wait` waits within one HTTP request. | A worker that can keep a connection open. | [Long-poll with wait](./jobs.html#long-poll-with-wait) | | Status stream | A single-use ticket authorizes an SSE connection. | A UI that should react as job state changes. | [Streaming](./streaming.html) | | Provider callbacks | The provider wakes the server's poller; you still read the job. | Automatic server-side completion detection. | [Callbacks and webhooks](./callbacks.html) | | Agent | A persistent conversation requests generations and retains its assets. | Multi-step work directed through conversation. | [Agent Sessions API](./agent-api.html) | 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](../api/#tag/jobs/post/jobs/cost) | `/jobs/cost` | Price a generation before submitting it. | | [GET](../api/#tag/jobs/get/jobs) | `/jobs` | List jobs for the current user. | | [GET](../api/#tag/jobs/get/jobs/{id}) | `/jobs/{id}` | Get a single job. | | [GET](../api/#tag/jobs/get/jobs/{id}/wait) | `/jobs/{id}/wait` | Block until the job reaches a terminal state (or timeout). | | [POST](../api/#tag/jobs/post/jobs/{id}/cancel) | `/jobs/{id}/cancel` | Cancel a job, and stop it at the model provider where the provider allows it. | | [POST](../api/#tag/jobs/post/jobs/{id}/sse-ticket) | `/jobs/{id}/sse-ticket` | Mint a single-use ticket for the job status stream. | | [GET](../api/#tag/jobs/get/jobs/{id}/sse) | `/jobs/{id}/sse` | Stream job status updates over Server-Sent Events. | | [POST](../api/#tag/jobs/post/callbacks/{provider}) | `/callbacks/{provider}` | Receive a render provider's completion callback (a wake-up signal). | ![A job progresses from submission to a terminal result](../assets/diagrams/job-lifecycle.svg) ## 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: ```bash $ 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//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. > [!NOTE] > A `408` means this wait window ended with the job still running. Wait again; stopping your client does not cancel the generation. :::cards - [Synchronous: subscribe](./subscribe.html): Use the complete five-language examples and helper parameter reference. ::: ## 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. ```bash $ 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. :::cards - [Asynchronous: submit and poll](./jobs.html): Submit, read every state and retrieve the final asset. ::: ## 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. ```bash $ 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](./reliability.html). :::cards - [Long-poll with wait](./jobs.html): Copy the wait loop and handle a closed window safely. ::: ## 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. ```bash $ 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=" ``` ### 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`. :::cards - [Streaming](./streaming.html): Read the real event frames and stream them in your language. ::: ## 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. ```bash $ 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. :::cards - [Callbacks and webhooks](./callbacks.html): Understand callback behavior and how to be notified today. ::: ## 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. ```bash $ 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/?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. :::cards - [Agent Sessions API](./agent-api.html): Create a session, send messages, follow replies and collect assets. ::: ## 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](./errors.html) for the complete code reference. ## Getting started :::cards - [Client setup](./client-setup.html): Install a client and configure the token and base URL. - [Proxy setup](./proxy-setup.html): Keep your token on the server when a browser calls the API. :::