File uploads

Some generation tools accept an existing file as input (for example, animating an image into a video clip or transforming a video with a text prompt). To use your own files, upload them through the API first.

How it works

POST /v1/files/upload  →  { "fileId": "vg_file_...", "uploadUrl": "https://..." }
PUT  <uploadUrl>       →  (raw file bytes)
GET  /v1/files/{id}    →  poll until sources are ready

1. Create a pending file and get a presigned upload URL
2. PUT the raw file bytes to the presigned URL
3. Poll until the file is processed and ready to use

The presigned URL goes directly to the storage provider, so no additional authentication is needed for the PUT request. It expires shortly after creation, so upload promptly.

Upload with the SDK

The uploadFile helper handles all three steps in a single call:

1
import { VideoGenClient, uploadFile } from "@videogen/sdk";
2
import { readFileSync } from "node:fs";
3
4
const client = new VideoGenClient({ token: "YOUR_API_KEY" });
5
6
const file = await uploadFile(client, readFileSync("./photo.png"), {
7
  type: "IMAGE",
8
  displayName: "My photo",
9
});
10
11
console.log(file.fileId); // "vg_file_..."

Request body

Using uploaded files as tool inputs

Once the file is ready, pass its fileId to any tool that accepts a file input:

1
import { VideoGenClient, uploadFile, pollExecutedTool } from "@videogen/sdk";
2
import { readFileSync } from "node:fs";
3
4
const client = new VideoGenClient({ token: "YOUR_API_KEY" });
5
6
const uploaded = await uploadFile(client, readFileSync("./photo.png"), {
7
  type: "IMAGE",
8
  displayName: "Source image",
9
});
10
11
const { toolExecutionId } = await client.tools.generateVideoClip({
12
  fileId: uploaded.fileId,
13
});
14
15
const result = await pollExecutedTool(client, toolExecutionId);
16
console.log(result);

SDK options

The uploadFile helper accepts these options:

Using webhooks instead of polling

Instead of polling for file readiness, you can subscribe to file upload lifecycle webhooks. These are only fired for API uploads.

Register for these events when creating a webhook endpoint:

$
curl -X POST https://api.videogen.io/v1/webhooks/endpoints \
>
  -H "Authorization: Bearer $VIDEOGEN_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "url": "https://your-server.com/webhooks/videogen",
>
    "events": ["file.upload.completed", "file.download_ready", "file.analysis_completed"]
>
  }'

Each event payload includes a hydrated file object with the latest file state, so no extra API call is needed. See Webhooks guide for details on verifying webhook signatures.