Genie Player SDKDocs
Node.js SDK

Server SDK reference

Typed video processing, caption retrieval, and signed webhook verification with @genie-player/node.

Published npm package · Open Genie Dashboard

Client configuration

import { GeniePlayer } from "@genie-player/node";
const genie = new GeniePlayer({ apiKey: process.env.GENIE_PLAYER_API_KEY! });

The client defaults to https://api.genieplayer.com. Options include baseUrl, timeoutMs, maxRetries, and a custom fetch implementation. HTTP redirects are rejected to protect credentials. Node.js 20 or later is required; ESM and CommonJS are supported.

Media and jobs

  • media.createAndTranslate(input): upload a file and return the media and queued job.
  • media.processAndDownload(input): upload, wait, and return the completed job, WebVTT text by language, and signed caption URLs.
  • media.delete(mediaId): delete media and associated data.
  • translationJobs.retrieve(jobId): read a status snapshot.
  • translationJobs.wait(jobId, options?): wait for completion with optional polling interval, timeout, and abort signal.
  • translationJobs.events(jobId, options?): asynchronously iterate over job status snapshots.

Upload inputs accept a local file path, Blob, Uint8Array, or ArrayBuffer. For bytes or a Blob, provide filename. Optional inputs include targetLanguages, videoType, contentType, webhookUrl, and webhookType.

Captions and usage

  • captions.list(mediaId): list caption tracks and available signed download URLs.
  • captions.retrieve(mediaId, language): retrieve structured caption cues.
  • captions.downloadVtt(mediaId, language): download WebVTT text using the API key.
  • usage.retrieve(): read processing usage.
  • clientTokens.create(input): mint a short-lived browser token. Supply endUserId; the default scope is media:read.

Signed caption download URLs expire after one hour. Use the SDK to retrieve fresh URLs or download captions through authenticated endpoints.

Webhook verification

verifyGenieWebhook(rawBody, headers, secret) verifies the signature and timestamp and returns a typed event. It throws WebhookSignatureError for invalid input. Preserve the original request bytes.

Events are translation_job.completed, translation_job.failed, translation_job.canceled, and webhook.test. Test events contain an ID and type with no media or caption data.

For project defaults, copy the signing secret from Dashboard → Webhooks. For explicit per-job URLs, use webhooks.retrieveSigningSecret() during backend setup. Never interchange these secrets. A per-job URL overrides the project endpoint.

Acknowledge promptly with 2xx and deduplicate event IDs. After rotating a dashboard endpoint secret, update your receiver within the 24-hour transition period. The verifier accepts either valid signature during that window.

Delivery behavior

Project defaults apply only to SDK jobs. Dashboard and anonymous jobs do not inherit them. Only one destination receives a job event: an explicit URL takes precedence. Choose completed, failed, and canceled events in the dashboard.

Project readers can view configuration metadata and delivery history. Admin access is required to configure the endpoint, reveal or rotate secrets, send tests, or retry failures. Outbound actions require an active project and paid-plan or active-trial access. After access expires, configuration and history remain available, and the endpoint can still be disabled.

Disabling the endpoint or replacing its URL stops pending deliveries to the previous destination; an HTTP request already running cannot be recalled. Manual retry preserves the event ID and is available only for failed deliveries whose destination is still current. Caption links are refreshed for delivery attempts.

Completed delivery history is retained for 30 days. It shows attempt counts, timestamps, HTTP status, and sanitized failure reasons without storing receiver response bodies. Tests and manual retries share a limit of five actions per minute per project.

Errors and cancellation

API errors extend GenieError and expose status, code, and an optional requestId. Subclasses include AuthenticationError, AuthorizationError, ValidationError, NotFoundError, RateLimitError, UsageLimitError, and APIError.

Processing can throw translation_failed, translation_canceled, or wait_timeout. The processAndDownload polling timeout excludes upload and caption download time. Abort signals stop local requests and polling; they do not cancel a server job.

Follow the Node.js quickstart →