REST API ReferenceEndpointsFiles

Enable public preview

Enable public preview for a file. Works for any file type. Copies the file to a permanent public URL (`staticPublicPreviewSource`) and, for video and audio, registers a public embed playback id (`publicPlaybackId`) for use with `@videogen/player`. If streaming playback is still processing, the endpoint polls briefly and background processing finishes creating the embed playback id. Returns the updated file.

Authentication

AuthorizationBearer
API key from [app.videogen.io/api](https://app.videogen.io/api). The full key is only shown once when you create it.

Path parameters

fileIdstringRequired

The file id (e.g. vg_file_...).

Response

File with public preview enabled
fileIdstring

File id (e.g. vg_file_...).

scopeenum

File scope.

  • GLOBAL: user-uploaded or standalone generated files that persist indefinitely.
  • PROJECT: project-specific files (e.g. text-to-speech clips in a generated project).
  • EXPORT: project exports.
  • TEMPORARY: short-lived files guaranteed to be available for 24 hours, after which they may be archived at any time. Not analyzed (no description, transcript, or embedding).
  • ENTITY: files attached to a reusable entity (e.g. a voice sample for an actor), shared across your team.
typeenum or nullOptional
File type. Null when the file is still being processed and the type has not yet been determined.
displayNamestringOptional
Display name for the file.
descriptionstring or nullOptional
durationSecondsdouble or nullOptional
Duration in seconds for video and audio files. Null for images.
transcriptobject or nullOptional

Timed transcript for video and audio files, when available, as a Transcript object with timed words. Null for images or when no transcript has been generated. For plain transcript text, use transcriptText.

transcriptTextstring or nullOptional
Plain transcript text for video and audio files, when available. Null for images or when no transcript has been generated.
downloadUrlstring or nullOptionalformat: "uri"

Private signed URL for the highest-quality downloadable rendition, provided at the top level for convenience. Valid for 7 days from when it was signed. null when the rendition is still processing or the URL has not been signed yet. See downloadUrlExpiresAt for the exact expiry and downloadSource for the full rendition metadata; call POST /v1/files/{fileId}/hydrate to refresh it.

downloadUrlExpiresAtinteger or nullOptional

Seconds since epoch (Unix timestamp) when downloadUrl expires. null when downloadUrl is null.

thumbnailUrlstring or nullOptionalformat: "uri"

Private signed URL for the thumbnail rendition, provided at the top level for convenience. Valid for 7 days from when it was signed. null for file types that have no thumbnail (e.g. audio) or when it has not been signed yet. See thumbnailSource for the full rendition metadata.

thumbnailUrlExpiresAtinteger or nullOptional

Seconds since epoch (Unix timestamp) when thumbnailUrl expires. null when thumbnailUrl is null.

thumbnailSourceobject or nullOptional
Thumbnail image source. Populated after hydration.
previewSourceobject or nullOptional

Preview rendition source (720p for video, resized for images). Populated after hydration.

downloadSourceobject or nullOptional

Highest-quality downloadable rendition. Populated after hydration.

hlsSourceobject or nullOptional

Private HLS streaming source. Populated for video and audio files once streaming renditions are ready. Uses a signed token; treat like other signed sources.

isPublicPreviewEnabledbooleanOptional

Whether public preview is enabled for this file. When true, staticPublicPreviewSource is populated for all file types. For video and audio, publicHlsUrl and publicPlaybackId are also populated once embed streaming is ready.

staticPublicPreviewSourceobject or nullOptional

Permanent public URL for the file’s highest-quality rendition. Populated when isPublicPreviewEnabled is true. Does not expire (expiresAt is null). Use for direct links to images, downloads, or any file type. For embedded video or audio players, prefer publicPlaybackId.

publicHlsUrlstring or nullOptional

Public HLS streaming URL for video and audio. Only present when isPublicPreviewEnabled is true and embed streaming is ready. Prefer publicPlaybackId with @videogen/player for embeds.

publicPlaybackIdstring or nullOptional

Encoded public playback id (e.g. vg_play_...) for video and audio embeds. Pass this to @videogen/player or @videogen/player-react. Only present when isPublicPreviewEnabled is true and embed streaming is ready. For a permanent direct file URL (any type), use staticPublicPreviewSource instead.

sourceToolTypestringOptional

Tool type that generated this file (e.g. GENERATE_IMAGE, TEXT_TO_SPEECH). Only present when the file was created by a tool execution.

sourceToolExecutionIdstringOptional

Execution id of the tool call that generated this file (e.g. vg_tool_...). Only present when the file was created by a tool execution.

fileAnalysisMetadataobjectOptional

Background analysis state for the file (used to populate description, transcript, durationSeconds, and the search embedding). Omitted when the file was returned via a path that does not check analysis progress (e.g. tool-result inline files and webhook payloads).