#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"

#Strip EXIF Data

POST /api/{project}/{imageId}/strip-exif

Re-encodes an image to permanently remove all EXIF metadata (GPS location, camera info, etc.). Useful for privacy compliance before publishing user-uploaded photos.

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

#Response 200 OK

Returns the updated image metadata with exifData cleared.

You can also strip EXIF at upload time by passing stripExif=true as a form parameter.

#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

  1. Always set caption — Improves accessibility and SEO

  2. Use consistent keywords — Establish a keyword taxonomy for your application

  3. Leverage customId — Map Pixault images to your own database records

  4. Embed JSON-LD — Search engines index your images with rich metadata

  5. Keep names concise — Names appear in image search results and previews

  6. Organize with folders — Use virtual folders to group related images