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:
- Store the key in an environment variable (
SWD_API_KEY), never in public client code. POST /api/v1/generate→ receivejob.id(HTTP 202).- Poll
GET /api/v1/jobs/{id}untilsucceeded, then readresult.url.
Authentication #
Every request to /api/v1/* endpoints (except models/stats/health/meta) uses an API key. Three equivalent ways:
| Method | Example |
|---|---|
| Authorization | Authorization: Bearer nxa_live_… |
| Header | x-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/modelsReturns the model catalog with valid parameters and default values. No auth required.
| Parameter | Valid values | Default |
|---|---|---|
| duration | 15 (seconds) | 15 |
| resolution | 1080p | 1080p |
| ratio | 16:9, 9:16 | 16:9 |
| ttl | 1d, 7d, 30d | 30d |
| image_urls | 0–3 images for image-to-video | — |
| video_url | 1 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.
| Layer | Limit | What it means |
|---|---|---|
| Concurrency | 1 job per slot | At most 3 jobs run at the same time (one per active slot). |
| Queue | 100 jobs total | One global FIFO queue. Beyond 100 waiting jobs, 429 queue_full. |
| Per API key | 1 active job | A key cannot occupy more than one slot while it already has a running job. |
| Per API key | 100 active + queued | Per-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.
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/generateCreates a single generation job. Returns 202 before the result is ready; fetch the result via polling or webhook. Idempotent replays return 200.
| Field | Type | Description |
|---|---|---|
| model | string | Required. gemini-omni-1.2-flash (aliases accepted). |
| prompt | string | Required, ≤15,000 characters. |
| parameters.duration | string/int | 15 (seconds); a trailing s is accepted. |
| parameters.resolution | string | 1080p (or 1080). |
| parameters.ratio | string | 16:9 or 9:16. Alias: aspect_ratio. |
| ttl | string | 1d/7d/30d; alias storage_ttl. |
| image_urls | string[] | Optional. 1–3 images = image-to-video (I2V). |
| video_url | string | Optional. With exactly 1 image = reference-to-video (R2V). |
| webhook_url | string | Optional. Result notification target. |
| idempotencyKey | string | Optional, ≥8 characters; prevents duplicate jobs. |
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).
| Field | Description |
|---|---|
| status | queued · dispatching · processing · succeeded · failed · cancelled |
| mode | t2v · i2v · r2v |
| queuePosition | Queue position; only while queued, otherwise null. |
| progress | 0–100. |
| durationSeconds | Total seconds from creation to finish; null while the job is not finished. |
| referenceCount | Number of reference images (0–3). |
| referenceVideoCount | 0 or 1. |
| result | null until success; then {url, expiresAt, ttl, width, height, watermarkRemoved}. |
| errorMessage | Failure 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/meAPI 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.
| Header | Value |
|---|---|
| X-Nexa-Event | video.succeeded / video.failed |
| X-Nexa-Signature | sha256=<HMAC-SHA256(secret, body)> |
| User-Agent | NexaWebhook/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.
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.
| HTTP | code | Situation |
|---|---|---|
| 400 | invalid_parameter | Invalid model/prompt/duration/resolution/ratio/ttl/URL/reference combination. |
| 401 | invalid_api_key | Key is invalid or revoked. |
| 403 | forbidden | Job belongs to another key. |
| 404 | not_found | Job/endpoint does not exist. |
| 409 | not_cancellable / already_finished | Cancel a job that is processing/finished. |
| 413 | payload_too_large | Request body exceeds the 1 MB limit. |
| 429 | key_queue_full / queue_full | Per-key job limit / global queue is full. |
| 429 | (rate limit) | Generate 60/minute/IP; login 20/10 minutes/IP. |
| 503 | no_slot | No slot is ready yet. |
Stats & health #
GET /api/v1/stats GET /api/v1/live GET /api/v1/healthstats = 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.