Pixault Documentation Help

Upload API

Upload images to Pixault via multipart form POST. All upload endpoints require API key authentication.

Authentication

Include your credentials in every request:

X-Client-Id: px_cl_your_client_id X-Client-Secret: pk_your_secret_key

Legacy single-key authentication is also supported:

X-Api-Key: pk_your_api_key

Upload an Image

POST /api/{project}/upload

Upload a single image with optional metadata.

Query Parameters

Parameter

Type

Required

Description

folder

string

No

Virtual folder path for organization (e.g. portfolio/landscapes)

Form Fields

Field

Type

Required

Description

file

File

Yes

Image file (JPEG, PNG, WebP, AVIF, GIF, SVG, EPS)

name

string

No

Image name / title

description

string

No

Image description

caption

string

No

Accessible text alternative / alt text

category

string

No

Semantic category (e.g. portfolio, headshot)

keywords

string

No

Comma-separated searchable keywords

author

string

No

Creator/author name

stripExif

boolean

No

Strip EXIF data from uploaded image

Example

curl -X POST https://img.pixault.io/api/myapp/upload?folder=portfolio/landscapes \ -H "X-Client-Id: px_cl_abc123" \ -H "X-Client-Secret: pk_secret456" \ -F "[email protected]" \ -F "caption=Team photo from company retreat" \ -F "keywords=team,retreat,2025" \ -F "category=headshot" \ -F "author=Jane Doe"

Response 201 Created

{ "imageId": "img_01JKXYZ123", "url": "/myapp/img_01JKXYZ123", "width": 4000, "height": 3000, "size": 2456789, "isVideo": false, "isEps": false, "duration": null, "thumbnailId": null, "processingJobId": null }

List Images

GET /api/{project}/images

Retrieve a paginated list of images.

Query Parameters

Parameter

Type

Default

Description

limit

int

50

Results per page

cursor

string

—

Pagination cursor from previous response

search

string

—

Search across metadata fields

category

string

—

Filter by category

keyword

string

—

Filter by keyword

author

string

—

Filter by author

folder

string

—

Filter by folder path

isVideo

bool

—

Filter to videos only (true) or images only (false)

includeDerived

bool

false

Include derived assets (EPS rasterizations, splits)

Example

curl "https://img.pixault.io/api/myapp/images?limit=10&category=nature&folder=portfolio" \ -H "X-Client-Id: px_cl_abc123" \ -H "X-Client-Secret: pk_secret456"

Response 200 OK

{ "images": [ { "imageId": "img_01JKXYZ123", "originalFileName": "sunset.jpg", "contentType": "image/jpeg", "sizeBytes": 1234567, "width": 3000, "height": 2000, "caption": "Golden sunset over the ocean", "keywords": ["nature", "sunset"], "createdAt": "2025-03-15T10:30:00Z" } ], "cursor": "eyJpZCI6Imlt...", "hasMore": true }

Get Image Metadata

GET /api/{project}/{imageId}/metadata

Returns the full metadata for a single image.

Response 200 OK

{ "imageId": "img_01JKXYZ123", "projectId": "myapp", "originalFileName": "photo.jpg", "contentType": "image/jpeg", "sizeBytes": 2456789, "width": 4000, "height": 3000, "caption": "Team photo from company retreat", "keywords": ["team", "retreat"], "name": "Company Retreat 2025", "description": "Annual team photo at mountain lodge", "category": "headshot", "folder": "portfolio/team", "author": "Jane Doe", "datePublished": "2025-03-15T10:30:00Z", "dateModified": "2025-03-15T11:00:00Z" }

Delete an Image

DELETE /api/{project}/{imageId}

Permanently delete an image and all its cached variants.

Response 204 No Content

No body returned.

Supported Formats

Format

MIME Type

Upload

Max Size

Delivery

JPEG

image/jpeg

Yes

20 MB

Yes

PNG

image/png

Yes

20 MB

Yes

WebP

image/webp

Yes

20 MB

Yes

AVIF

image/avif

Yes

20 MB

Yes

GIF

image/gif

Yes

20 MB

Yes

SVG

image/svg+xml

Yes

20 MB

Yes (sanitized)

EPS

application/postscript

Yes

50 MB

Yes (rasterized to PNG)

SVG Handling

SVGs are sanitized on upload to remove potentially dangerous elements (scripts, external references). SVGs can be served as-is or rasterized to bitmap format via transform parameters.

EPS Handling

EPS (Encapsulated PostScript) files are accepted for upload and automatically rasterized to high-resolution PNG in the background via Ghostscript. EPS support is designed for stock photo workflows — files from Shutterstock and similar services often contain multiple designs in a single EPS that are unusable without Illustrator.

Upload flow:

  1. Upload an EPS file — validated via PostScript header and BoundingBox DSC comment

  2. Background processing rasterizes the EPS to PNG at 300 DPI

  3. Multi-page files produce one derived PNG per page

  4. The upload response includes a processingJobId for tracking progress

Derived assets:

  • Rasterized PNGs are linked to the parent EPS via sourceAssetId

  • Derived assets are excluded from the main gallery listing by default (use includeDerived=true to include them)

  • The parent EPS thumbnail automatically uses the first rasterized PNG

Design splitting:

  • For single-page EPS files containing multiple designs (common in stock vector packs), use POST /api/{project}/{imageId}/split to auto-detect and extract individual designs

  • Splitting uses whitespace gap detection to partition the image into a grid of content regions

SVG extraction:

  • Use POST /api/{project}/{imageId}/extract-svg to convert the EPS to a vector SVG, preserving all paths and shapes

  • The pipeline converts EPS → PDF (via Ghostscript) → SVG (via pdftocairo), then sanitizes the output

  • If multiple designs are detected, individual SVGs are also extracted (derivation types svg-1, svg-2, etc.)

  • The full-page SVG is saved with derivation type svg

EPS API endpoints:

Method

Route

Description

GET

/api/{project}/{imageId}/derived

List derived assets for an EPS parent

GET

/api/{project}/{imageId}/processing-status

Check EPS processing job status

POST

/api/{project}/{imageId}/split

Trigger auto-split for multi-design files

POST

/api/{project}/{imageId}/extract-svg

Extract vector SVG from EPS

On-demand delivery: EPS originals can also be requested via the standard transform URL pattern (e.g., /{project}/{epsId}/w_800.webp). The delivery pipeline rasterizes the EPS on-demand and caches the result, so subsequent requests are served from cache.

Video Upload

POST /api/{project}/upload

Upload video files using the same endpoint. Pixault auto-generates thumbnail frames.

Format

Supported

MP4

Yes

WebM

Yes

MOV

Yes

Videos support range-request streaming for playback.

Rate Limits

Upload endpoints use per-API-key token bucket rate limiting:

Limit

Value

Requests per minute

100 per API key

Queue depth

10

Storage Quotas

Uploads are subject to your plan's storage limits. If you exceed your storage quota:

  • Paid plans: Overages accrue at your plan's overage rate

  • Trial/Free: Uploads are rejected with 413 Payload Too Large

Check your current usage in the billing dashboard.

12 March 2026
Image Delivery APINamed Transforms