#Upload API

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

#Authentication

Include your API key in every request:

X-Api-Key: pk_your_api_key
                              

This is the only supported scheme. Requests without this header are rejected with 401 Unauthorized.

#Upload an Image

POST /api/{project}/upload

Upload a single image with optional metadata.

#Query Parameters

#Form Fields

#Example

curl -X POST https://img.pixault.io/api/myapp/upload?folder=portfolio/landscapes \
  -H "X-Api-Key: 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

#Example

curl "https://img.pixault.io/api/myapp/images?limit=10&category=nature&folder=portfolio" \
  -H "X-Api-Key: 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

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

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.

Videos support range-request streaming for playback.

#Rate Limits

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

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