---
title: "Upload an image"
method: POST
path: "/v1/images"
tags: ["Images"]
---

# Upload an image

`POST /v1/images`

## Request

- Base URL: `https://api.pixelvault.dev`
- URL: `https://api.pixelvault.dev/v1/images`
- Auth: one of:
  - HTTP bearer
  - none

Upload an image and receive a public CDN URL (JPEG, PNG, GIF, WebP, AVIF, SVG). Works WITHOUT an API key: keyless uploads are temporary (response includes `temporary: true` and `expires_in`, ~30 days) — add a Bearer key to make uploads permanent. Send multipart/form-data (a file), or, with a key, application/json `{ url }` to import from a URL (https only).

## Request body

- object
  - `url` string, uri, required: Source image URL to import (https only). Requires an API key.
  - `folder` string: Optional folder name
  - `visibility` 'public' | 'private': 'private' stores the image behind a signed URL and the response `url` is signed; default 'public'.
  - `sign_expires_in` integer: Signature lifetime in seconds for a private upload (60–2592000, default 3600).

## Response `201`

Image uploaded

- object
  - `data` Image
    - `id` string
    - `url` string, uri: CDN URL. Supports on-the-fly transforms via query params: size (s|m|l|social), w, h (px, snapped to a discrete set), fit (scale-down|contain|cover|crop|pad), fmt (auto|webp|avif|jpg|png), q (auto|60|75|85), segment (foreground — AI background removal, transparent PNG), background (fill: hex, rgb()/rgba(), or a common CSS color name), gravity (auto|face|left|right|top|bottom|XxY, with fit=cover|crop), zoom (0.0-1.0, with gravity=face), blur (0-250), sharpen (0-10), rotate (90|180|270), flip (h|v|hv), brightness/contrast (multiplier, 1=no change), saturation (multiplier, 0=grayscale), tile (watermark: tile another of your project's images over the base). See the serve_image operation for the full parameter reference. Example: ?w=800&blur=30&saturation=0
    - `mime_type` string
    - `size` integer
    - `width` integer, nullable
    - `height` integer, nullable
    - `filename` string
    - `folder` string, nullable
    - `created_at` string, date-time

## Other responses

- `400`: Missing or invalid file
- `401`: Invalid or missing API key
- `429`: Upload or storage limit reached

---

[API](https://skmtc.dev/pixelvault/apis/pixelvault-api.md) · [All operations](https://skmtc.dev/pixelvault/apis/pixelvault-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pixelvault/apis/pixelvault-api/revisions/6332d8c3f8e0?raw)