> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.videogen.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.videogen.io/_mcp/server.

# TypeScript

> Install and configure the @videogen/sdk TypeScript package. Covers client setup, video workflows, tool execution polling, file uploads/downloads, and webhook verification.

## Install

```bash
npm install @videogen/sdk
```

## Create a client

```typescript
import { VideoGen } from "@videogen/sdk";

const vg = new VideoGen({ apiKey: "sk_videogen_live_..." });
```

The client reads from the `VIDEOGEN_API_KEY` environment variable when no `apiKey` is provided.

## Generate a video from a script

Workflows turn a script into a finished video asynchronously. Prefer `scriptToVideoAndWait` when you can block:

```typescript
import { VideoGen } from "@videogen/sdk";

const vg = new VideoGen({ apiKey: "sk_videogen_live_..." });

const run = await vg.workflows.scriptToVideoAndWait({
  script:
    "Staying hydrated keeps your body and mind running at their best. Drinking enough water boosts your energy, focus, and mood. Keep a water bottle nearby and sip throughout the day.",
  visualStyle: {
    type: "AI_IMAGE",
    aiStyle: "Loose watercolor illustration, visible brushstrokes, soft color bleeds, paper texture, muted palette. A clear uncluttered subject centered in the frame, occupying only the middle half of the image, with generous empty margins on all four sides, no background clutter.",
  },
  quality: "HIGH",
  autoExport: true,
  remixActions: [
    { type: "ENABLE_CAPTIONS" },
    {
      type: "CONVERT_IMAGES_TO_VIDEOS",
      motionPrompt: "slow cinematic push-in",
      muteOutputVideos: true,
      quality: "HIGH",
    },
  ],
});

console.log(run.downloadUrl);
```

Use `projectId` for export, remix, and other API calls. `projectUrl` (also on the response) is optional: a link to open the project in the VideoGen editor for manual review (team members and project collaborators only).

For start-then-poll yourself, call `scriptToVideo` then `pollWorkflowRun({ client: vg, workflowRunId })`.

Responses are plain JSON objects (camelCase keys as returned by the API).

### Options

`pollWorkflowRun` and `*AndWait` accept optional polling options:

| Option           | Type          | Default   | Description                        |
| ---------------- | ------------- | --------- | ---------------------------------- |
| `pollIntervalMs` | `number`      | `1500`    | Milliseconds between polls.        |
| `timeoutMs`      | `number`      | `3600000` | Maximum wait time before throwing. |
| `signal`         | `AbortSignal` | (none)    | Cancel polling early.              |

## Run a standalone tool

All tool endpoints are asynchronous. Prefer `generateImageAndWait` (and the other tool `*AndWait` methods). Use `createPublicPreview` when you need a shareable preview URL:

```typescript
import { VideoGen, createPublicPreview } from "@videogen/sdk";

const vg = new VideoGen({ apiKey: "sk_videogen_live_..." });

const execution = await vg.tools.generateImageAndWait({
  prompt: "A sunset over a calm ocean, cinematic lighting",
});

console.log(execution.status); // "succeeded"
const fileId = execution.results?.[0]?.fileId;
const preview = await createPublicPreview({ client: vg, fileId });
```

For start-then-poll yourself, call `generateImage` then `pollExecutedTool({ client: vg, toolExecutionId })`. Poll helpers accept the same options as above (`pollIntervalMs`, `timeoutMs`, `signal`).

## Upload a file

```typescript
import { VideoGen, uploadFile } from "@videogen/sdk";
import { readFileSync } from "node:fs";

const vg = new VideoGen({ apiKey: "sk_videogen_live_..." });

const file = await uploadFile({
  client: vg,
  data: readFileSync("input.mp4"),
  displayName: "input.mp4",
  type: "VIDEO",
});

console.log(file.fileId); // "vg_file_..."
```

## Download a file

```typescript
import { VideoGen, downloadFile } from "@videogen/sdk";

const vg = new VideoGen({ apiKey: "sk_videogen_live_..." });

// Stream to disk
await downloadFile({ client: vg, fileId: "vg_file_...", outputPath: "output.mp4" });

// Or get the raw Response
const response = await downloadFile({ client: vg, fileId: "vg_file_..." });
const bytes = await response.arrayBuffer();
```

## Verify a webhook

```typescript
import { verifyWebhookSignature } from "@videogen/sdk";

const event = verifyWebhookSignature({
  rawBody,
  headers,
  secret: signingSecret,
});

if (event.event === "tool_execution.succeeded") {
  console.log(event.results);
}
```

## Links

* [npm: @videogen/sdk](https://www.npmjs.com/package/@videogen/sdk)
* [GitHub: videogen-typescript-sdk](https://github.com/video-gen/videogen-typescript-sdk)
* [REST API Reference](/rest-api-reference)