File hydration

Files returned by the VideoGen API include signed URLs for downloading thumbnails, previews, and the full-resolution asset. These URLs expire after a period of time. Hydration generates fresh URLs so you can access the file again.

When to hydrate

File source URLs are time-limited. You need to hydrate a file when:

• The downloadSource, previewSource, or thumbnailSource is null
• A source has status: "pending" (still processing)
• A source URL has passed its expiresAt timestamp
• You stored a fileId and need to access the file later

Webhook payloads and freshly completed tool executions include hydrated URLs already, so you typically only need to hydrate when accessing files some time after they were created.

Hydrate with the SDK

The getHydratedFile helper checks whether URLs are still valid and only calls the hydrate endpoint when necessary:

1
import { VideoGenClient, getHydratedFile } from "@videogen/sdk";
2
3
const client = new VideoGenClient({ token: "YOUR_API_KEY" });
4
5
const file = await getHydratedFile(client, "vg_file_...");
6
7
console.log(file.downloadSource?.url);   // fresh signed URL
8
console.log(file.thumbnailSource?.url);  // fresh signed URL
9
console.log(file.previewSource?.url);    // fresh signed URL

Response

The hydrate endpoint returns the full StorageFile object with populated source URLs:

1
{
2
  "fileId": "vg_file_...",
3
  "type": "IMAGE",
4
  "scope": "GLOBAL",
5
  "displayName": "A mountain at sunrise",
6
  "thumbnailSource": {
7
    "status": "ready",
8
    "url": "https://...",
9
    "expiresAt": 1745413200,
10
    "width": 256,
11
    "height": 256
12
  },
13
  "previewSource": {
14
    "status": "ready",
15
    "url": "https://...",
16
    "expiresAt": 1745413200,
17
    "width": 720,
18
    "height": 720
19
  },
20
  "downloadSource": {
21
    "status": "ready",
22
    "url": "https://...",
23
    "expiresAt": 1745413200,
24
    "width": 1024,
25
    "height": 1024
26
  }
27
}

Each source includes:

Downloading files

The downloadFile helper combines hydration and download into a single call:

1
import { VideoGenClient, downloadFile } from "@videogen/sdk";
2
3
const client = new VideoGenClient({ token: "YOUR_API_KEY" });
4
5
// Stream to disk
6
await downloadFile(client, "vg_file_...", {
7
  outputPath: "./mountain.png",
8
});
9
10
// Or get the raw response
11
const response = await downloadFile(client, "vg_file_...");
12
const bytes = await response?.arrayBuffer();

Source statuses