---
title: "file.download_ready"
method: POST
path: "file.download_ready"
tags: ["Webhook events"]
---

# file.download_ready

`POST file.download_ready` (webhook)

Delivered when a file is ready for download. Only fired for files uploaded via the API.

## Payload

- FileWebhookPayload — Delivered to your webhook endpoint during the file lifecycle (upload, analysis, playback, and download readiness). Only sent for files uploaded via the API. The payload always includes a hydrated `file` object with the latest state.
  - `event` 'file.upload.completed' | 'file.upload.failed' | 'file.playback_ready' | 'file.download_ready' | 'file.analysis_completed' | 'file.analysis_failed', required — Webhook event types for the file lifecycle (upload, analysis, playback, and download readiness). Only fired for files uploaded via the API (not the VideoGen UI).
  - `fileId` string, required — File id (e.g. `vg_file_...`).
  - `occurredAt` integer, required — Seconds since epoch (Unix timestamp) when the event occurred.
  - `file` FileInfo, required — Metadata for a generated file. Obtain ids from tool results or `GET /v1/files`.
    - `fileId` string, required — File id (e.g. `vg_file_...`).
    - `type` 'IMAGE' | 'VIDEO' | 'AUDIO' | 'PDF' | 'SLIDESHOW' | 'TEXT' | 'LOTTIE' — File type. `TEXT` covers plain-text and editor-interchange documents; `LOTTIE` is a JSON animation.
    - `scope` 'GLOBAL' | 'PROJECT' | 'EXPORT' | 'TEMPORARY' | 'ENTITY', 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.
    - `displayName` string — Display name for the file.
    - `description` string, nullable
    - `durationSeconds` number, nullable — Duration in seconds for video and audio files. Null for images.
    - `transcript` Transcript — A transcript of an audio file, as timed words in order.
      - `languageCode` string, nullable — Optional BCP-47 language code of the spoken audio (e.g. `en`, `es`). Used to tag the transcript's language; omit if unknown.
      - `words` TranscriptWord[], required — The transcript words, sorted by `startSeconds` and non-overlapping. Must contain at least one word.
        - `startSeconds` number, required — Start time of the word in seconds from the beginning of the audio.
        - `endSeconds` number, 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.
    - `transcriptText` string, nullable — Plain transcript text for video and audio files, when available. Null for images or when no transcript has been generated.
    - `downloadUrl` string, uri, 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, nullable — Seconds since epoch (Unix timestamp) when `downloadUrl` expires. `null` when `downloadUrl` is null.
    - `thumbnailUrl` string, uri, 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, nullable — Seconds since epoch (Unix timestamp) when `thumbnailUrl` expires. `null` when `thumbnailUrl` is null.
    - `thumbnailSource` FileSource — A rendition source for a file (e.g. thumbnail, preview, download). Contains a signed URL and metadata.
      - `status` 'pending' | 'ready' | 'failed' | 'skipped', 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).
      - `url` string, nullable — Signed URL. Present when status is `ready` and file has been recently hydrated. If missing, call the hydrate endpoint.
      - `expiresAt` integer, nullable — Seconds since epoch (Unix timestamp) when the signed URL expires.
      - `width` integer, nullable — Rendition width in pixels, when known.
      - `height` integer, nullable — Rendition height in pixels, when known.
      - `fileBytes` integer, nullable — File size in bytes, when known.
    - `previewSource` FileSource — A rendition source for a file (e.g. thumbnail, preview, download). Contains a signed URL and metadata.
      - `status` 'pending' | 'ready' | 'failed' | 'skipped', 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).
      - `url` string, nullable — Signed URL. Present when status is `ready` and file has been recently hydrated. If missing, call the hydrate endpoint.
      - `expiresAt` integer, nullable — Seconds since epoch (Unix timestamp) when the signed URL expires.
      - `width` integer, nullable — Rendition width in pixels, when known.
      - `height` integer, nullable — Rendition height in pixels, when known.
      - `fileBytes` integer, nullable — File size in bytes, when known.
    - `downloadSource` FileSource — A rendition source for a file (e.g. thumbnail, preview, download). Contains a signed URL and metadata.
      - `status` 'pending' | 'ready' | 'failed' | 'skipped', 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).
      - `url` string, nullable — Signed URL. Present when status is `ready` and file has been recently hydrated. If missing, call the hydrate endpoint.
      - `expiresAt` integer, nullable — Seconds since epoch (Unix timestamp) when the signed URL expires.
      - `width` integer, nullable — Rendition width in pixels, when known.
      - `height` integer, nullable — Rendition height in pixels, when known.
      - `fileBytes` integer, nullable — File size in bytes, when known.
    - `hlsSource` FileSource — A rendition source for a file (e.g. thumbnail, preview, download). Contains a signed URL and metadata.
      - `status` 'pending' | 'ready' | 'failed' | 'skipped', 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).
      - `url` string, nullable — Signed URL. Present when status is `ready` and file has been recently hydrated. If missing, call the hydrate endpoint.
      - `expiresAt` integer, nullable — Seconds since epoch (Unix timestamp) when the signed URL expires.
      - `width` integer, nullable — Rendition width in pixels, when known.
      - `height` integer, nullable — Rendition height in pixels, when known.
      - `fileBytes` integer, nullable — File size in bytes, when known.
    - `isPublicPreviewEnabled` boolean — 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 — A rendition source for a file (e.g. thumbnail, preview, download). Contains a signed URL and metadata.
      - `status` 'pending' | 'ready' | 'failed' | 'skipped', 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).
      - `url` string, nullable — Signed URL. Present when status is `ready` and file has been recently hydrated. If missing, call the hydrate endpoint.
      - `expiresAt` integer, nullable — Seconds since epoch (Unix timestamp) when the signed URL expires.
      - `width` integer, nullable — Rendition width in pixels, when known.
      - `height` integer, nullable — Rendition height in pixels, when known.
      - `fileBytes` integer, nullable — File size in bytes, when known.
    - `publicHlsUrl` string, 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, 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 — 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 — 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 — 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` 'UNATTEMPTED' | 'LOADING' | 'FULFILLED' | 'REJECTED', 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.
      - `analysisProgressPercentage` number, 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 — 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.
  - `error` ApiError — Standard error body returned with every non-2xx response (the `default` response of every operation). The HTTP status code conveys the error class; this body carries the details: - `400` invalid request, `401` missing or invalid API key, `403` not permitted (e.g. plan or add-on required, see `requirement`), `404` not found, `409` conflict, `429` rate limited or out of credits, `5xx` server error. Common `code` values include `invalid_request`, `invalid_api_key`, `not_authorized`, `not_found`, `insufficient_credits`, and `rate_limited`. Always branch on `code` (and `requirement.type` when present) rather than parsing `message`.
    - `message` string, required — Human-readable error description. For display and logging only; do not branch on its exact text.
    - `code` string, nullable — Machine-readable error code in snake_case (e.g. `invalid_api_key`, `insufficient_credits`). `null` when no specific code applies.
    - `requirement` ErrorRequirement — What is needed to resolve an error, when it can be fixed by fulfilling a specific requirement (e.g. purchasing an add-on or upgrading the plan).
      - `type` string, required — Machine-readable requirement type in snake_case (e.g. `purchase_add_on`, `upgrade_plan`).
      - `details` object — Key-value pairs with requirement-specific context (e.g. the add-on id to purchase).
    - `internalErrorCode` string, nullable — Opaque internal error code for debugging. Include this when contacting support. `null` when not applicable.

## Acknowledgement `200`

Acknowledge receipt

---

[API](https://skmtc.dev/videogen/apis/videogen-api.md) · [All operations](https://skmtc.dev/videogen/apis/videogen-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/videogen/videogen-api/revisions/33dda0455d67/schema)