GUgumnut-ai
assets

Get an asset

Changed on

Fetches one asset and its associated metadata by ID. Use this when you already have a specific asset ID (e.g., from list_assets, search_assets, or list_album_assets) and need its full details. For bulk fetch of multiple known IDs, prefer list_assets with the ids parameter to avoid N round trips. asset_urls are signed URLs for client rendering only; to visually inspect the image pixels, call view_asset instead.

get/api/assets/{asset_id}

Request

Path parameters

asset_idstring required

Asset ID (with asset_ prefix) to fetch.

Query parameters

includestring[] nullable

Opt-in expansion fields. Supported values: metadata (camera/EXIF/GPS and location names), faces, people, file_data (a group token populating the nested file_data object with the file/provenance scalars device_asset_id, device_id, file_created_at, file_modified_at, checksum, checksum_sha1, file_size_bytes), and variants (every asset_urls rung beyond the lean one. Without it asset_urls carries only its lean rung — thumbnail for an image, or thumbnail_image for a video — so callers that render non-thumbnail variants or download the current rendering must pass it). Accepts multiple include= query params or a single comma-delimited value (e.g. include=faces,people). Unknown values return 422. When omitted, only the lean core is returned (id, mime_type, local_datetime, dimensions, file_size_bytes, description, quality_score, thumbhash, asset_urls, kind, current_version_id) and each data field above is null/absent until you request it.

Response

Successful Response

idstring required

Unique asset identifier with 'asset_' prefix

mime_typestring required

MIME type of the current rendering (e.g., 'image/jpeg', 'video/mp4').

original_file_namestring required

Filename the asset was uploaded under.

local_datetimestring date-time required

When the photo/video was taken, in the device's local timezone

created_atstring date-time required

When this asset record was created in the database

updated_atstring date-time required

When this asset record was last updated

asset_urlsobject nullable

Named asset variants. Images: 'original', 'thumbnail', 'small', 'preview', 'large', 'fullsize'. Videos: 'original', plus 'thumbnail_image', 'small_image', 'preview_image', 'large_image', 'fullsize_image' pointing at the extracted still. 'original' is served with a Content-Disposition attachment header (signed 'dl' filename param) so a top-level navigation saves it to disk, while inline subresource loads (<video>, fetch) still render it. Variant URLs are stable: a derived variant may briefly 404 until its artifact is generated, then serve from the same URL.

descriptionstring nullable

AI-generated description of the asset's content, quality, and composition. null means description generation has not yet run; empty string means the model refused to describe the asset. Distinct from metadata.description (camera-embedded EXIF metadata).

quality_scorenumber nullable

Photographic quality judged from the image alone (focus, exposure, noise, composition, capture flaws), from 0 (worst) to 1 (best) on a fixed scale that is comparable across photos and libraries. Scores take a few distinct values, so photos of similar quality tie. It does not reflect who is pictured. null means the asset has no score.

thumbhashstring nullable

Base64-encoded ThumbHash placeholder (~28 chars). Clients decode with the thumbhash library (JS / Swift / Kotlin) to render an instant blurred preview before the CDN thumbnail arrives. null while generation is pending.

kindstring required

What produced the current rendering: original (the upload), edit (an edit rendered by the client), or external:<service>. The namespace is open — derive edited-ness as kind != "original".

current_version_idstring required

ID (asset_version_ prefix) of the current version, which the top-level rendering fields describe. For a current derived version, this ID supplies the path target for replacement or deletion.

widthinteger

Width of the current rendering in pixels.

heightinteger

Height of the current rendering in pixels.

file_size_bytesinteger required

Size of the current rendering in bytes: the exact byte count the asset_urls.original download serves. For an unedited asset this equals the upload's file_data.file_size_bytes; for an edited asset it is the derived rendering's size.

durationnumber nullable

Video length in seconds. null for images and for videos whose duration has not been extracted yet.

trashed_atstring date-time nullable

When this asset was moved to trash (ISO 8601, UTC). null for live assets. Trashed assets are excluded from default list/search results and are purged after the configured retention window.

stack_idstring nullable

ID of the stack this asset belongs to (asset_stack_ prefix), or null when the asset is not part of a stack. Group assets by this value to collapse a stack into a single tile; the stack's own cover and member count are not carried on the asset. Distinct from metadata.auto_stack_id, which is the camera's in-EXIF MakerNotes:AutoStackID string — this is the server-assigned foreign key to the asset's stack.

Changes

  • 780282ba2b76Revision changes
    • info

      added the optional property /// to the response with the status

  • 7c2860d9eb88Revision changes
    • warning

      removed the optional property from the response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the optional property to the response with the status

    • info

      added the required property to the response with the status