Image Metadata

Every image in Pixault carries structured metadata aligned with Schema.org ImageObject. This enables rich search engine indexing, accessibility, and programmatic image management.

Metadata Fields

Field	Type	Description
`imageId`	string	Unique image identifier (ULID format, e.g., `img_01JKXYZ`)
`projectId`	string	Project this image belongs to
`originalFileName`	string	Original filename
`contentType`	string	MIME type (e.g., `image/jpeg`)
`sizeBytes`	long	File size in bytes
`width`	int	Image width in pixels
`height`	int	Image height in pixels
`name`	string	Image name / title
`description`	string	Longer description
`caption`	string	Accessible text alternative / alt text
`category`	string	Semantic category (e.g. portfolio, headshot)
`folder`	string	Virtual folder path (e.g. `portfolio/landscapes`)
`keywords`	string[]	Searchable keywords
`author`	string	Creator/author name
`copyrightHolder`	string	Name of the copyright holder
`copyrightYear`	int	Year of copyright
`license`	string	License identifier or URL
`dateCreated`	datetime	Original creation date (e.g. from EXIF)
`datePublished`	datetime	Upload / publish timestamp (UTC)
`dateModified`	datetime	Last modification timestamp (UTC)
`representativeOfPage`	bool	Whether this image is representative of the page
`exifData`	map<string,string>	Extracted EXIF key-value pairs
`locationLatitude`	double	GPS latitude (from EXIF or manual)
`locationLongitude`	double	GPS longitude (from EXIF or manual)
`locationName`	string	Human-readable location name
`tags`	map<string,string>	Custom key-value tags
`customId`	string	Your own external identifier
`isVideo`	bool	Whether the asset is a video
`duration`	double	Video duration in seconds
`hasAudio`	bool	Whether a video has an audio track
`thumbnailId`	string	Auto-generated thumbnail ID (videos only)

JSON-LD Output

Pixault can return metadata as JSON-LD for embedding in HTML pages:

curl https://img.pixault.io/api/myapp/img_01JKXYZ/metadata/jsonld \
  -H "X-Client-Id: px_cl_abc123" \
  -H "X-Client-Secret: pk_secret456"

{
  "@context": "https://schema.org",
  "@type": "ImageObject",
  "contentUrl": "https://img.pixault.io/myapp/img_01JKXYZ/original.webp",
  "thumbnailUrl": "https://img.pixault.io/myapp/img_01JKXYZ/w_200,h_200,fit_cover.webp",
  "name": "Team Photo 2025",
  "description": "Annual team photo at the mountain lodge",
  "width": { "@type": "QuantitativeValue", "value": 4000, "unitCode": "E37" },
  "height": { "@type": "QuantitativeValue", "value": 3000, "unitCode": "E37" },
  "encodingFormat": "image/jpeg",
  "contentSize": "2.3 MB",
  "uploadDate": "2025-03-15T10:30:00Z"
}

Embed this in your HTML <head>:

<script type="application/ld+json">
  <!-- paste JSON-LD here -->
</script>

Updating Metadata

PATCH /api/{project}/{imageId}/metadata

Use PATCH to update metadata fields without re-uploading. Only provided fields are updated; omitted fields remain unchanged.

Updatable Fields

Field	Type	Description
`name`	string	Image name / title
`description`	string	Longer description
`caption`	string	Accessible text alternative / alt text
`category`	string	Semantic category (e.g. portfolio, headshot)
`folder`	string	Virtual folder path (e.g. `portfolio/landscapes`). Set to empty string to move to root.
`keywords`	string[]	Searchable keywords
`author`	string	Creator/author name
`copyrightHolder`	string	Name of the copyright holder
`copyrightYear`	int	Year of copyright
`license`	string	License identifier or URL
`dateCreated`	datetime	Original creation date
`datePublished`	datetime	Publish timestamp (UTC)
`representativeOfPage`	bool	Whether this image is representative of the page
`exifData`	map<string,string>	EXIF key-value pairs (replaces existing)
`locationLatitude`	double	GPS latitude
`locationLongitude`	double	GPS longitude
`locationName`	string	Human-readable location name
`tags`	map<string,string>	Custom key-value tags (replaces existing)

Example

curl -X PATCH https://img.pixault.io/api/myapp/img_01JKXYZ/metadata \
  -H "X-Client-Id: px_cl_abc123" \
  -H "X-Client-Secret: pk_secret456" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "Updated alt text for better accessibility",
    "keywords": ["team", "retreat", "mountain"],
    "folder": "portfolio/team",
    "author": "Jane Doe",
    "copyrightHolder": "Acme Corp",
    "copyrightYear": 2025,
    "license": "CC-BY-4.0"
  }'

Response `200 OK`

Returns the full updated image metadata object.

Folder Endpoints

Folders provide virtual organization for images. An image's folder field determines which folder it belongs to.

List Folders

GET /api/{project}/folders

Returns the list of folder paths for a project.

curl https://img.pixault.io/api/myapp/folders \
  -H "X-Client-Id: px_cl_abc123" \
  -H "X-Client-Secret: pk_secret456"

Response `200 OK`

[
  "portfolio",
  "portfolio/landscapes",
  "portfolio/team",
  "headshots"
]

Create a Folder

POST /api/{project}/folders

Create an explicit folder.

curl -X POST https://img.pixault.io/api/myapp/folders \
  -H "X-Client-Id: px_cl_abc123" \
  -H "X-Client-Secret: pk_secret456" \
  -H "Content-Type: application/json" \
  -d '{ "path": "portfolio/landscapes" }'

Response `201 Created`

Returns the created folder path.

Delete a Folder

DELETE /api/{project}/folders/{folderPath}

Deletes a folder from the manifest. Does not delete images within the folder.

curl -X DELETE https://img.pixault.io/api/myapp/folders/portfolio/landscapes \
  -H "X-Client-Id: px_cl_abc123" \
  -H "X-Client-Secret: pk_secret456"

Response `204 No Content`

No body returned.

Searching by Metadata

Use query parameters on the list endpoint to search:

# Search by keyword
curl "https://img.pixault.io/api/myapp/images?keyword=nature"

# Search across metadata fields
curl "https://img.pixault.io/api/myapp/images?search=sunset"

# Filter by folder
curl "https://img.pixault.io/api/myapp/images?folder=portfolio/landscapes"

# Filter by category
curl "https://img.pixault.io/api/myapp/images?category=headshot"

Video Metadata

Video files include additional metadata:

Field	Type	Description
`duration`	double	Duration in seconds
`hasAudio`	bool	Whether the video has an audio track
`thumbnailId`	string	Auto-generated thumbnail image ID

Best Practices

Always set caption — Improves accessibility and SEO
Use consistent keywords — Establish a keyword taxonomy for your application
Leverage customId — Map Pixault images to your own database records
Embed JSON-LD — Search engines index your images with rich metadata
Keep names concise — Names appear in image search results and previews
Organize with folders — Use virtual folders to group related images

10 March 2026

Image Metadata

Metadata Fields

JSON-LD Output

Updating Metadata

Updatable Fields

Example

Response 200 OK

Folder Endpoints

List Folders

Response 200 OK

Create a Folder

Response 201 Created

Delete a Folder

Response 204 No Content

Searching by Metadata

Video Metadata

Best Practices

Response `200 OK`

Response `200 OK`

Response `201 Created`

Response `204 No Content`