Upload a File

POSThttps://api.perceptpixel.com/v1/media

Parameters

The parameters are sent as form data, with x-www-form-urlencoded encoding.

name	type	description
file (required)	file	The file to upload
name (required)	text	The name of the file

Response (200)

For example, if the file name is cat.jpg, and the PerceptPixel ID is demo-brjexrkh, the response will be,

{
    "uid": "aRjexrkh",
    "name": "cat.jpg",
    "path": "demo-brjexrkh/cat.jpg",

    "cdn_url": "https://img.perceptpixel.com/demo-brjexrkh/cat.jpg",
    "thumbnail_url": "https://img.perceptpixel.com/demo-brjexrkh/w_600,h_600,c_pad/cat.jpg",

    "updated_at": "2024-02-28T08:49:31.747492Z",
    "file_size": 1020789,
    "type": "jpeg",
    "width": 3374,
    "height": 4498,

    "uploaded_by": "demo@perceptpixel.com",
    "client_ip": "123.123.123.123",

    "caption": null,
    "tags": [],

    "saved_images": {}
}

The above response has been formatted, indented and re-arranged for better readability. The actual response will just be valid JSON.

Types

The corresponding type for the response is mocked in TypeScript below.

interface Media {
    // file details
    uid: string; /* unique identifier for all further references */
    name: string;
    path: string;

    // ready to use CDN URLs
    cdn_url: string;
    thumbnail_url: string;

    // file details
    updated_at: string; /* ISO 8601 date time */
    file_size: number;
    type: string;
    width: number;
    height: number;

    // user details
    uploaded_by: string;
    client_ip: string;

    // metadata
    caption: Caption | null; /* best caption */
    tags: Tag[]; /* list of tags */

    // user saved transformations
    saved_images: Record<string, Transform>;
}

/** Supporting Data Types */

interface Transform {
    parent_uid: string; /* uid of the parent image */
    uid: string; /* key in saved_images */
    url: string;

    size: number; /* resultant file size */
    type: string; /* resultant file type */
    width: string; /* resultant width */
    height: string; /* resultant height */

    created_at: number; /* epoch milliseconds */
}

interface Caption {
    text: string;
    confidence: number;
    boundingBox: BoundingBox;
}

interface Tag {
    name: string;
    confidence: number;
}

interface BoundingBox {
    x: number;
    y: number;
    width: number;
    height: number;
}

Response (4xx/5xx)

warning

The data format of the error response is not yet finalized. Please only check the status code at the moment.

{"field":["error message"]}

Example,

{"name":["duplicate file path, file with the same name already exists"]}

Example (curl)

# {API_KEY} is your API key
# /path/to/sample.jpg is the complete path to the file you want to upload.
# variable substitution may not work in your shell, so use the entire path.
curl https://api.perceptpixel.com/v1/media \
  -X POST \
  -H "Authorization: Api-Key {API_KEY}" \
  -F 'file=@/path/to/sample.jpg' \
  -F 'name=sample.jpg'

Upload into a folder : Example (curl)

# Replace {API_KEY} with your actual API key, without enclosing it in curly braces
# folder1 should exist (can be created using the dashboard as of now)
# /path/to/sample.jpg is the complete path to the file you want to upload.
# variable substitution may not work in your shell, so use the entire path.

curl https://api.perceptpixel.com/v1/media \
  -X POST \
  -H "Authorization: Api-Key {API_KEY}" \
  -F 'file=@/path/to/sample.jpg' \
  -F 'name=sample.jpg'
  -F 'folder=folder1'