SWD BOOSTER Gemini Omni 1.2 Flash
API Reference

REST API documentation

Everything you need to integrate Gemini Omni 1.2 Flash. Code samples use this deployment's base URL.

Quickstart #

Get an API key swd_live_… from the SWD BOOSTER admin, then create your first job and poll for the result. Three steps:

  1. Store the key in an environment variable (SWD_API_KEY), never in public client code.
  2. POST /api/v1/generate → receive job.id (HTTP 202).
  3. Poll GET /api/v1/jobs/{id} until succeeded, then read result.url.
Need the model list and valid parameters? See Models & capabilities. Results are TTL-backed — download or save them before they expire.

Authentication #

Every request to /api/v1/* endpoints (except models/stats/health/meta) uses an API key. Three equivalent ways:

MethodExample
AuthorizationAuthorization: Bearer nxa_live_…
Headerx-api-key: nxa_live_…
Query?api_key=nxa_live_… (avoid in public logs)

Revoked or invalid keys return 401 invalid_api_key. For the web dashboard, sign in with the same key via POST /api/auth/login. The session is kept in an HttpOnly cookie for 30 days on that browser. The raw key is never stored in localStorage or rendered in the page.

Models & capabilities #

GET /api/v1/models

Returns the model catalog with valid parameters and default values. No auth required.

ParameterValid valuesDefault
duration15 (seconds)15
resolution1080p1080p
ratio16:9, 9:1616:9
ttl1d, 7d, 30d30d
image_urls0–3 images for image-to-video—
video_url1 video + exactly 1 image for reference-to-video—

How capacity works #

SWD BOOSTER runs three fixed session slots: A1, A2, and A3. Each slot processes exactly one job at a time. You always submit to one endpoint; the scheduler assigns work to the first free slot.

LayerLimitWhat it means
Concurrency1 job per slotAt most 3 jobs run at the same time (one per active slot).
Queue100 jobs totalOne global FIFO queue. Beyond 100 waiting jobs, 429 queue_full.
Per API key1 active jobA key cannot occupy more than one slot while it already has a running job.
Per API key100 active + queuedPer-key cap; 429 key_queue_full when reached.

Fair dispatch. When a slot frees up, the drain worker claims the oldest queued job whose key has no active job. A heavy reseller therefore cannot block A1–A3 with its own backlog. Only active slots receive work; a slot with an expired session stays idle until the admin refreshes its cookie.

Queue and drain worker. Every job starts as queued. The drain worker fills each free slot, polls upstream every 5 seconds, retries transient generator errors up to 3 attempts, and automatically moves to the next queued job when a slot finishes.

Job lifecycle. queued → dispatching → processing → succeeded or failed. A queued job can be cancelled; a processing job cannot. Jobs that do not finish within 120 minutes are marked failed.

Planning tips. Use idempotencyKey for safe retries, prefer webhooks for high volume, poll every 4–10 seconds, and keep queuePosition as an estimate rather than a guarantee. Results are stored for 30 days and every video is watermark-cleaned before delivery.

Create job #

POST /api/v1/generate

Creates a single generation job. Returns 202 before the result is ready; fetch the result via polling or webhook. Idempotent replays return 200.

FieldTypeDescription
modelstringRequired. gemini-omni-1.2-flash (aliases accepted).
promptstringRequired, ≤15,000 characters.
parameters.durationstring/int15 (seconds); a trailing s is accepted.
parameters.resolutionstring1080p (or 1080).
parameters.ratiostring16:9 or 9:16. Alias: aspect_ratio.
ttlstring1d/7d/30d; alias storage_ttl.
image_urlsstring[]Optional. 1–3 images = image-to-video (I2V).
video_urlstringOptional. With exactly 1 image = reference-to-video (R2V).
webhook_urlstringOptional. Result notification target.
idempotencyKeystringOptional, ≥8 characters; prevents duplicate jobs.
Reference modes. 0 references = text-to-video (T2V). 1–3 image URLs = image-to-video (I2V). 1 video URL + exactly 1 image URL = reference-to-video (R2V). Video-only requests are rejected. Images depicting real people may be rejected by content moderation; stylized characters and animals are supported.
Limit of 100 active+queued jobs per API key (429 key_queue_full) and 60 generate requests/minute/IP. Global queue full → 429 queue_full; no ready slots → 503 no_slot.

Job status #

GET /api/v1/jobs/{id}

Returns the latest job state. Polling this endpoint also triggers a background check, so polling is the only signal you need. Only the owner can read a job (403 for other keys).

FieldDescription
statusqueued · dispatching · processing · succeeded · failed · cancelled
modet2v · i2v · r2v
queuePositionQueue position; only while queued, otherwise null.
progress0–100.
durationSecondsTotal seconds from creation to finish; null while the job is not finished.
referenceCountNumber of reference images (0–3).
referenceVideoCount0 or 1.
resultnull until success; then {url, expiresAt, ttl, width, height, watermarkRemoved}.
errorMessageFailure description (sanitized); null unless failed.

List & cancel jobs #

GET /api/v1/jobs DELETE /api/v1/jobs/{id}

Lists jobs owned by your key, newest first. Query: status, limit (≤50), offset. You can only cancel a job while it is queued; jobs already processing return 409 not_cancellable, finished jobs return 409 already_finished.

Profile & usage #

GET /api/v1/me

API key profile (masked), 24-hour / 7-day / 30-day usage, and active limits. Useful for reseller dashboards.

Webhooks #

When a job has a webhook_url, we send a POST on video.succeeded or video.failed. The payload contains event, job (public shape), and sentAt.

HeaderValue
X-Nexa-Eventvideo.succeeded / video.failed
X-Nexa-Signaturesha256=<HMAC-SHA256(secret, body)>
User-AgentNexaWebhook/1.0

Verify the signature before processing. We retry twice with a delay; webhook failures do not cancel the job.

Storage & TTL #

Before upload, every video is processed to remove the bottom-right watermark. The cleaned file is stored with a 1/7/30-day TTL and exposed as a direct URL. result.expiresAt gives the exact expiry time in ISO format and result.watermarkRemoved confirms the cleanup.

After expiresAt, the link is no longer valid. Download or move the video to your own storage before it expires. If primary storage fails, we use a temporary 24-hour TTL fallback.

Idempotency #

Send an idempotencyKey (≥8 characters) to make retries safe. The same key returns the existing job with 200 and idempotent: true — no new job. Values under 8 characters are ignored.

Errors & rate limits #

All errors have the shape { success:false, error, code, … }. Messages are sanitized and written in neutral English.

HTTPcodeSituation
400invalid_parameterInvalid model/prompt/duration/resolution/ratio/ttl/URL/reference combination.
401invalid_api_keyKey is invalid or revoked.
403forbiddenJob belongs to another key.
404not_foundJob/endpoint does not exist.
409not_cancellable / already_finishedCancel a job that is processing/finished.
413payload_too_largeRequest body exceeds the 1 MB limit.
429key_queue_full / queue_fullPer-key job limit / global queue is full.
429(rate limit)Generate 60/minute/IP; login 20/10 minutes/IP.
503no_slotNo slot is ready yet.

Stats & health #

GET /api/v1/stats GET /api/v1/live GET /api/v1/health

stats = capacity and success snapshot; live = Server-Sent Events (event stats) for real-time dashboards; health = operational status for uptime monitors. All public.

Integration examples #

Common pattern: create a job → poll or receive a webhook → deliver the result to the user. Below: a Telegram bot (Node) and a call from a SaaS web app.

Production ready? Keep the key on your server, use an idempotency key for retries, and verify webhooks. Need a key? Sign in or contact the SWD BOOSTER admin.