> 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.

# Enable public preview

POST https://api.videogen.io/v1/files/{fileId}/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.

Reference: https://docs.videogen.io/rest-api-reference/files/enable-public-preview

## Authentication

- `Authorization` header (bearer token, required) — API key from [app.videogen.io/api](https://app.videogen.io/api). The full key is only shown once when you create it.

## Request

### Path parameters

- `fileId` (string, required) — The file id (e.g. `vg_file_...`).

## Response

### 200

File with public preview enabled

- `fileId` (string, required) — File id (e.g. `vg_file_...`).
- `scope` (enum, required) — 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.
  - Allowed values: `GLOBAL`, `PROJECT`, `EXPORT`, `TEMPORARY`, `ENTITY`
- `type` (enum, optional, nullable) — File type. Null when the file is still being processed and the type has not yet been determined.
  - Allowed values: `IMAGE`, `VIDEO`, `AUDIO`, `PDF`, `SLIDESHOW`, `TEXT`, `LOTTIE`
- `displayName` (string, optional) — Display name for the file.
- `description` (string, optional, nullable)
- `durationSeconds` (double, optional, nullable) — Duration in seconds for video and audio files. Null for images.
- `transcript` (Transcript, optional, nullable) — 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`.
- `transcriptText` (string, optional, nullable) — Plain transcript text for video and audio files, when available. Null for images or when no transcript has been generated.
- `downloadUrl` (string, optional, nullable) — 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.
- `downloadUrlExpiresAt` (integer, optional, nullable) — Seconds since epoch (Unix timestamp) when `downloadUrl` expires. `null` when `downloadUrl` is null.
- `thumbnailUrl` (string, optional, nullable) — 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.
- `thumbnailUrlExpiresAt` (integer, optional, nullable) — Seconds since epoch (Unix timestamp) when `thumbnailUrl` expires. `null` when `thumbnailUrl` is null.
- `thumbnailSource` (FileSource, optional, nullable) — Thumbnail image source. Populated after hydration.
- `previewSource` (FileSource, optional, nullable) — Preview rendition source (720p for video, resized for images). Populated after hydration.
- `downloadSource` (FileSource, optional, nullable) — Highest-quality downloadable rendition. Populated after hydration.
- `hlsSource` (FileSource, optional, nullable) — Private HLS streaming source. Populated for video and audio files once streaming renditions are ready. Uses a signed token; treat like other signed sources.
- `isPublicPreviewEnabled` (boolean, optional) — 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.
- `staticPublicPreviewSource` (FileSource, optional, nullable) — 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`.
- `publicHlsUrl` (string, optional, nullable) — 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.
- `publicPlaybackId` (string, optional, nullable) — 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.
- `sourceToolType` (string, optional) — Tool type that generated this file (e.g. `GENERATE_IMAGE`, `TEXT_TO_SPEECH`). Only present when the file was created by a tool execution.
- `sourceToolExecutionId` (string, optional) — 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.
- `fileAnalysisMetadata` (FileAnalysisMetadata, optional) — 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).

## Types

### Transcript

A transcript of an audio file, as timed words in order.

- `words` (list of TranscriptWord, required) — The transcript words, sorted by `startSeconds` and non-overlapping. Must contain at least one word.
- `languageCode` (string, optional, nullable) — Optional BCP-47 language code of the spoken audio (e.g. `en`, `es`). Used to tag the transcript's language; omit if unknown.

### FileSource

A rendition source for a file (e.g. thumbnail, preview, download). Contains a signed URL and metadata.

- `status` (enum, required) — `pending`: asset is still processing or has not been hydrated yet. `ready`: signed URL is available. `failed`: rendition generation failed. `skipped`: rendition does not apply to this file type (e.g. thumbnail for audio).
  - Allowed values: `pending`, `ready`, `failed`, `skipped`
- `url` (string, optional, nullable) — Signed URL. Present when status is `ready` and file has been recently hydrated. If missing, call the hydrate endpoint.
- `expiresAt` (integer, optional, nullable) — Seconds since epoch (Unix timestamp) when the signed URL expires.
- `width` (integer, optional, nullable) — Rendition width in pixels, when known.
- `height` (integer, optional, nullable) — Rendition height in pixels, when known.
- `fileBytes` (integer, optional, nullable) — File size in bytes, when known.

### FileAnalysisMetadata

Background analysis state for a file. Background analysis populates `description`, `transcript`, `durationSeconds`, and the search embedding after a file is uploaded or generated; this object lets you render a progress indicator while it runs (and skip rendering once it's done).

- `analysisLoadingState` (enum, required) — Coarse-grained analysis state. - `UNATTEMPTED`: analysis has not started yet. - `LOADING`: analysis is in progress. - `FULFILLED`: analysis completed successfully. `description`, `transcript`, and `durationSeconds` are now populated where applicable for the file's type. - `REJECTED`: analysis failed permanently and will not be retried.
  - Allowed values: `UNATTEMPTED`, `LOADING`, `FULFILLED`, `REJECTED`
- `analysisProgressPercentage` (double, required) — Progress in `[0, 100]`. Always `100` when `analysisLoadingState` is `FULFILLED`. Otherwise the most recent in-flight progress reported by the analysis task (or `0` if no progress has been reported yet).
- `analysisAttemptIndex` (integer, optional) — Zero-based index of the current analysis task attempt. Only present while analysis is still loading (`UNATTEMPTED` or `LOADING`); omitted once analysis reaches a terminal state.

### TranscriptWord

A single timed word of a transcript.

- `startSeconds` (double, required) — Start time of the word in seconds from the beginning of the audio.
- `endSeconds` (double, required) — End time of the word in seconds from the beginning of the audio. Must be greater than `startSeconds`.
- `word` (string, required) — The spoken word, used verbatim for narration timing and captions.

## Examples

**Response**

```json
{
  "fileId": "vg_file_obLD1OX2eJCrEs0071Z4kA",
  "scope": "GLOBAL",
  "type": "VIDEO",
  "displayName": "My Campaign Video",
  "durationSeconds": 12.5,
  "isPublicPreviewEnabled": true,
  "staticPublicPreviewSource": {
    "status": "ready",
    "url": "https://public-previews.videogen.io/vg_file_obLD1OX2eJCrEs0071Z4kA.mp4",
    "expiresAt": null,
    "width": 1280,
    "height": 720,
    "fileBytes": 2500000
  },
  "publicHlsUrl": "https://stream.media.videogen.io/abc123def.m3u8",
  "publicPlaybackId": "vg_play_abc123def"
}
```

**SDK Code**

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

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

await client.files.enablePublicPreview({
  fileId: "vg_file_obLD1OX2eJCrEs0071Z4kA",
});
```

```python
from videogen import VideoGen

client = VideoGen(api_key="sk_videogen_live_...")

client.files.enable_public_preview(
    file_id="vg_file_obLD1OX2eJCrEs0071Z4kA",
)
```