--- title: "Search files" method: POST path: "/v1/files/search" tags: ["Files"] --- # Search files `POST /v1/files/search` Semantic vector search over your files. Embeds the query text and returns the closest matching files ranked by cosine similarity. Only files with indexed descriptions are searchable. ## Request body - SearchFilesRequest - `query` string, required — Natural-language search query. The text is embedded and compared against file description vectors using cosine similarity. - `numResults` integer — Number of results to return (1-100). Defaults to 10. - `selfOnly` boolean — When true, only files created by the calling API key's user are returned. When false (default), all files accessible to the team are included. ## Response `200` Search results ordered by descending similarity - SearchFilesResponse - `results` SearchFilesResult[], required - `similarity` number, required — Cosine similarity between the query embedding and the file description embedding. Ranges from 0 (no match) to 1 (identical). Values above 0.7 typically indicate strong relevance. - `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. ## Other responses - `default` — Error --- [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)