Model APIs

Find the answer you need, then follow the linked guide for the commands and API details.

Which languages have a client? #

TypeScript, Python and Rust have published clients; the Go client requires access to its private repository. See Libraries, APIs and community.

Do I need a subscription to use the API? #

You can use eligible models with prepaid top-up credits without a subscription; models with a higher plan requirement still require that plan. See Billing.

How do I know the price before I submit? #

POST /jobs/cost quotes the exact credits your request will hold without reserving or charging anything. See Billing.

What happens when a generation fails? #

Read failure.code and failure.credits_refunded: true means refunded, false means charged, and an absent value does not confirm either outcome. A provider-billed content-filter refusal can be charged; see Errors.

How long does a signed URL last? #

An asset's signed_url stays stable for about an hour and has at least an hour of validity left when issued; expires_at gives its exact expiry. Read the asset again for a fresh signature. Store its id rather than the temporary URL. A public share resolver instead redirects to a URL lasting about 15 minutes. See Storage and data retention.

Can I stop the API from storing my prompt? #

No. The asset stores its prompt and, when an image prompt was changed before rendering, enhanced_prompt. There is no switch to stop storing them and no per-request expiry header. See Storage and data retention.

Can I share a file with someone who has no account? #

Yes. Create a share link with POST /assets/{id}/share or POST /renders/{id}/share; its public URL works without a Nolgia account until it expires or is revoked. Save the returned URL when you create it: the full URL and token are returned only once. Links default to 30 days, with expires_in_days from 1 to 365. See File access controls.

How is video billed? #

Video costs ceil(credits × duration_seconds / baseline_seconds). Read the model's current cost and selected quality tier; the baseline is published with the price, commonly five seconds. For a model with an audio surcharge, generate_audio=false deducts it before duration scaling. POST /jobs/cost quotes the exact request without charging. See Pricing and credits.

What refunds? #

An operationally failed generation or terminal generation timeout refunds its credit hold. A content-policy refusal is refunded unless the provider billed the refused attempt, in which case it can be charged. Check failure.credits_refunded: true means refunded, false means charged, and absent or null is not proof of either. A quote, duplicate 409, or wait 408 costs nothing itself, so there is no new charge to refund; an already accepted job can still finish and bill normally after a wait timeout. See Model errors and Pricing and credits.

Why did I get 409 on a retry? #

Submitting the same request twice within five minutes returns 409 naming the earlier job so the retry cannot bill twice. Send a fresh Idempotency-Key to run it again on purpose; see Quick Start.

Can I cancel a job? #

Yes: POST /jobs/{id}/cancel. A job that has not reached the model provider yet is refunded in full. For a render already at the provider, Nolgia asks the provider to stop it where the provider allows it and settles on what the provider actually billed; the job's cancellation says which. A canceled job is never added to your library. Interrupting an agent turn with POST /agent/sessions/{id}/interrupt is separate and does not cancel a generation the turn already submitted. See Asynchronous: submit and poll.

How many jobs can I run at once? #

Your plan sets the concurrent generation limit. Read generation_limits on GET /me for your current maximum and active count; Concurrency limits lists the plans and explains a 429 refusal.

Is there a webhook? #

There is no customer webhook today. Provider callbacks wake Nolgia's poller; use long-poll or SSE to receive your result. See Callbacks and webhooks for the distinction and working examples.

How do I use my own images? #

Upload an image, then pass its id in a supported *_asset_id or *_asset_ids field. The server re-signs asset references at execution so a queued job does not inherit an expired URL. Your own HTTPS URLs also work in supported *_url fields. See Uploads and files for the upload flows and accepted formats.

Can my team share credits? #

Inside an organization, your requests use its shared credit pool and respect member budgets. See Teams and organizations.

How do I connect Claude Code or Cursor? #

Connect to the MCP server with a Personal Access Token. Follow the client configuration in Run MCP.