@zvid/sdk

@zvid/sdk — official TypeScript SDK

Typed TypeScript/JavaScript client for the Zvid JSON-to-video/image rendering API. Fetch-based with zero runtime dependencies, ESM + CJS, strict types derived from the maintained API contract, automatic transient-failure retries, polling helpers, media uploads, and timing-safe webhook signature verification.

npm install @zvid/sdk

Requires Node 18+ (native fetch). The API client itself is runtime-agnostic; the webhook helpers use node:crypto.

Quickstart

import { ZvidClient, outputUrl } from "@zvid/sdk";

const zvid = new ZvidClient(); // reads ZVID_API_KEY; create one at https://app.zvid.io/api-keys

const job = await zvid.renders.createImage({
  payload: {
    type: "image",
    width: 1200,
    height: 630,
    visuals: [{ type: "TEXT", text: "Hello Zvid", position: "center-center" }],
  },
});
const done = await zvid.waitForRender(job.jobId, { timeoutMs: 120_000 });
console.log(outputUrl(done)); // https://cdn.zvid.io/...

Configuration

Option	Env var	Default
apiKey	ZVID_API_KEY	— (required)
baseUrl	ZVID_BASE_URL	https://api.zvid.io
fetch	—	global fetch
maxRetries	—	3
retryBaseDelayMs	—	1000
retryMaxDelayMs	—	30000

Network failures and HTTP 429, 502, 503, and 504 responses are retried with exponential backoff and jitter. Retry-After is honored up to retryMaxDelayMs. Set maxRetries: 0 when the caller must never repeat a request. onRetry can feed application logs or metrics without replacing the retry implementation.

Surface

Namespace	Methods
zvid.account	profile
zvid.apiKeys	list, create, update, stats, revoke / delete
zvid.authoring	getSchema, listElements, getElementDocs, getExamples, creativePlan, repair, validate (plan-aware; no render credits)
zvid.renders	create, createImage, createBulk, createImageBulk, listBulk, getBulk
zvid.jobs	get, list, wait
zvid.templates	list, get, create, update, duplicate, preview, archive / delete
zvid.projects	list, get, create, update, delete
zvid.uploads	list, create, delete
zvid.webhooks	list, get, create, update, delete, test, deliveries
zvid.credits	balance, transactions, usageStats

Renders are asynchronous: every renders.create* call returns { jobId }. Poll zvid.jobs.get(jobId) yourself, or block with zvid.waitForRender(jobId, { timeoutMs, pollIntervalMs, signal }) — it resolves with the terminal JobStatus (use the outputUrl() / thumbnailUrl() helpers on it), rejects with RenderFailedError on failure and WaitTimeoutError on timeout, and supports AbortSignal.

Every render call takes exactly one of payload (inline project JSON, typed as RenderPayload) or template (stored tpl_… id), plus optional variables, overrides, and a one-off webhookUrl. The authoritative payload schema is published at docs.zvid.io (render-payload.schema.json).

zvid.authoring.validate() always resolves for schema validation: check its valid field. Invalid payloads return { valid: false, errors, warnings }; authentication, network, and other API failures still throw.

Uploads

Upload a browser File or a Blob created in Node.js. The returned CDN URL can be used directly as an image, video, GIF, or audio element source.

import { readFile } from "node:fs/promises";

const bytes = await readFile("./poster.png");
const poster = await zvid.uploads.create(
  new Blob([bytes], { type: "image/png" }),
  { fileName: "poster.png", width: 1200, height: 630 },
);
console.log(poster.url);

Errors

For AI generation, read zvid.authoring.getSchema() and the relevant element docs, start from a validated example, then repair and validate before calling zvid.renders.create*.

All API errors extend ZvidAPIError (with .status, .error, .details, .body):

Class	When
AuthenticationError	401
InsufficientCreditsError	402 — has .creditsRequired / .creditsAvailable
NotFoundError	404
RateLimitError	429 — has .retryAfter (seconds)
RenderFailedError	thrown by waitForRender when the job fails (.job)
WaitTimeoutError	thrown by waitForRender on timeout

Webhooks

Deliveries to registered endpoints are signed: X-Zvid-Signature: sha256=hex(HMAC_SHA256(secret, "<X-Zvid-Timestamp>.<raw body>")).

import { verifyWebhookSignature } from "@zvid/sdk";

// Express example — use the RAW body (express.raw / rawBody), not re-serialized JSON
app.post("/hooks/zvid", express.raw({ type: "application/json" }), (req, res) => {
  if (!verifyWebhookSignature(req.body, req.headers, process.env.ZVID_WEBHOOK_SECRET!)) {
    return res.status(400).end();
  }
  const event = JSON.parse(req.body.toString());
  // event.event === "render.completed" | "render.failed", event.data.url, …
  res.status(200).end();
});

verifyWebhookSignature uses crypto.timingSafeEqual and rejects deliveries older than 5 minutes ({ toleranceSeconds: null } disables the freshness check). It accepts fetch Headers, Node request headers, or plain objects. Per-request webhookUrl deliveries are not signed — only account endpoints are.

Development

npm install
npm run typecheck && npm test && npm run build

Live smoke test against a running orchestrator (spends ~1 credit):

ZVID_API_KEY=zvid_… ZVID_BASE_URL=http://localhost:4000 node examples/e2e.mjs

Publishing (manual)

Not published yet. To release version 0.2.0:

npm run prepublishOnly   # typecheck + tests + build
npm publish              # publish the public `@zvid/sdk` package to npm