Introduction

The PiXhost API v2 can upload images and covers and create galleries.

Supported image formats:

JPEG (image/jpeg)
PNG (image/png)
GIF (image/gif)
WebP (image/webp)
AVIF (image/avif)

The maximum file size is 10 MB per uploaded image.

For questions or issues, contact [email protected].

API Domains

The API is available on all PiXhost domains:

https://api.pixhost.to
https://api.pixhost.cc
https://api.pixho.st

Use the API hostname matching the PiXhost domain whose links you want in the response. The examples below use api.pixhost.cc.

Conventions

Requests use UTF-8 encoding. Send Accept: application/json.

Image and cover uploads use multipart/form-data. Do not set its Content-Type header manually when using cURL, Python Requests, or PHP cURL; the client must add the multipart boundary.

Gallery requests use application/x-www-form-urlencoded.

Successful upload and gallery creation responses use application/json; charset=UTF-8. API v2 does not require an API key.

Changelog

07/27/2026 - Documentation updated for current domains, HTTPS, WebP, and current client libraries
06/21/2017 - Thumbnail size range changed to 150-500 pixels

Images

Upload Image

Uploads one image.

HTTP Request

POST https://api.pixhost.cc/images

curl --include "https://api.pixhost.cc/images" \
  -H 'Accept: application/json' \
  -F '[email protected]' \
  -F 'content_type=0' \
  -F 'max_th_size=420'

from pathlib import Path

import requests

with Path("image.jpg").open("rb") as image:
    response = requests.post(
        "https://api.pixhost.cc/images",
        files={"img": ("image.jpg", image, "image/jpeg")},
        data={
            "content_type": "0",
            "max_th_size": "420",
        },
        headers={"Accept": "application/json"},
        timeout=120,
    )

response.raise_for_status()
print(response.json())

<?php
$curl = curl_init('https://api.pixhost.cc/images');
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => [
        'img' => new CURLFile(__DIR__ . '/image.jpg', 'image/jpeg', 'image.jpg'),
        'content_type' => '0',
        'max_th_size' => '420',
    ],
    CURLOPT_HTTPHEADER => ['Accept: application/json'],
    CURLOPT_RETURNTRANSFER => true,
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;

Response headers

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

Response body

{
  "name": "image.jpg",
  "show_url": "https://pixhost.cc/show/8582/563_image.jpg",
  "th_url": "https://t1.pixhost.cc/thumbs/8582/563_image.jpg"
}

Form Parameters

Parameter	Type	Required	Values	Description
img	file	yes	JPEG, PNG, GIF, WebP, AVIF	Image to upload
content_type	integer	yes	`0`, `1`	`0` for safe-for-work content, `1` for NSFW content
max_th_size	integer	no	`150`-`500`	Maximum thumbnail width or height; default is `200`
gallery_hash	string	no		Gallery identifier; supply together with `gallery_upload_hash`
gallery_upload_hash	string	no		Gallery upload token; supply together with `gallery_hash`

Response Fields

Field	Type	Description
name	string	Original image filename without the generated numeric prefix
show_url	string	Public image page URL
th_url	string	Direct thumbnail URL

Upload Cover

Uploads a cover composed of a required left image and an optional right image.

HTTP Request

POST https://api.pixhost.cc/covers

curl --include "https://api.pixhost.cc/covers" \
  -H 'Accept: application/json' \
  -F '[email protected]' \
  -F '[email protected]' \
  -F 'content_type=0'

from pathlib import Path

import requests

with Path("left.jpg").open("rb") as left, Path("right.png").open("rb") as right:
    response = requests.post(
        "https://api.pixhost.cc/covers",
        files={
            "img_left": ("left.jpg", left, "image/jpeg"),
            "img_right": ("right.png", right, "image/png"),
        },
        data={"content_type": "0"},
        headers={"Accept": "application/json"},
        timeout=120,
    )

response.raise_for_status()
print(response.json())

<?php
$curl = curl_init('https://api.pixhost.cc/covers');
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => [
        'img_left' => new CURLFile(__DIR__ . '/left.jpg', 'image/jpeg', 'left.jpg'),
        'img_right' => new CURLFile(__DIR__ . '/right.png', 'image/png', 'right.png'),
        'content_type' => '0',
    ],
    CURLOPT_HTTPHEADER => ['Accept: application/json'],
    CURLOPT_RETURNTRANSFER => true,
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;

Response headers

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

Response body

{
  "name": "left.jpg",
  "show_url": "https://pixhost.cc/show/8582/568_left.jpg",
  "th_url": "https://t1.pixhost.cc/thumbs/8582/568_left.jpg"
}

Form Parameters

Parameter	Type	Required	Values	Description
img_left	file	yes	JPEG, PNG, GIF, WebP, AVIF	Left cover image
img_right	file	no	JPEG, PNG, GIF, WebP, AVIF	Right cover image
content_type	integer	yes	`0`, `1`	`0` for safe-for-work content, `1` for NSFW content
gallery_hash	string	no		Gallery identifier; supply together with `gallery_upload_hash`
gallery_upload_hash	string	no		Gallery upload token; supply together with `gallery_hash`

Response Fields

Field	Type	Description
name	string	Left image filename without the generated numeric prefix
show_url	string	Public cover page URL
th_url	string	Direct thumbnail URL

Galleries

Gallery creation is a three-step process:

Create a gallery and retain both returned hashes.
Upload images or covers with gallery_hash and gallery_upload_hash.
Finalize the gallery.

Create Gallery

HTTP Request

POST https://api.pixhost.cc/galleries

curl --include "https://api.pixhost.cc/galleries" \
  -H 'Accept: application/json' \
  --data-urlencode 'gallery_name=Test gallery'

import requests

response = requests.post(
    "https://api.pixhost.cc/galleries",
    data={"gallery_name": "Test gallery"},
    headers={"Accept": "application/json"},
    timeout=30,
)

response.raise_for_status()
print(response.json())

<?php
$curl = curl_init('https://api.pixhost.cc/galleries');
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => http_build_query([
        'gallery_name' => 'Test gallery',
    ]),
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'Content-Type: application/x-www-form-urlencoded; charset=utf-8',
    ],
    CURLOPT_RETURNTRANSFER => true,
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

echo $response;

Response headers

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

Response body

{
  "gallery_name": "Test gallery",
  "gallery_hash": "8NtKF",
  "gallery_url": "https://pixhost.cc/gallery/8NtKF",
  "gallery_upload_hash": "yKtOl8NbHMYJ8yWj8Mh90sIlfXC7PXT6RHW8Xua7"
}

Form Parameters

Parameter	Type	Required	Description
gallery_name	string	yes	Gallery name

Response Fields

Field	Type	Description
gallery_name	string	Gallery name
gallery_hash	string	Public gallery identifier
gallery_url	string	Public gallery URL
gallery_upload_hash	string	Private upload token valid for 24 hours

Finalize Gallery

Finalize the gallery after all uploads finish. Until it is finalized, the gallery and its images are not publicly available. Empty galleries are removed during finalization.

If this endpoint is not called, the current maintenance process finalizes the gallery after approximately 24 hours.

HTTP Request

POST https://api.pixhost.cc/galleries/{gallery_hash}/finalize

curl --include "https://api.pixhost.cc/galleries/8NtKF/finalize" \
  -H 'Accept: application/json' \
  --data-urlencode 'gallery_upload_hash=yKtOl8NbHMYJ8yWj8Mh90sIlfXC7PXT6RHW8Xua7'

import requests

response = requests.post(
    "https://api.pixhost.cc/galleries/8NtKF/finalize",
    data={
        "gallery_upload_hash": "yKtOl8NbHMYJ8yWj8Mh90sIlfXC7PXT6RHW8Xua7",
    },
    headers={"Accept": "application/json"},
    timeout=30,
)

response.raise_for_status()

<?php
$curl = curl_init('https://api.pixhost.cc/galleries/8NtKF/finalize');
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => http_build_query([
        'gallery_upload_hash' => 'yKtOl8NbHMYJ8yWj8Mh90sIlfXC7PXT6RHW8Xua7',
    ]),
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'Content-Type: application/x-www-form-urlencoded; charset=utf-8',
    ],
    CURLOPT_RETURNTRANSFER => true,
]);

$response = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

Successful response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

The successful API v2 response has an empty body.

Form Parameters

Parameter	Type	Required	Description
gallery_upload_hash	string	yes	Private upload token returned when the gallery was created

Errors

API v2 reports failures primarily through the HTTP status code. Error responses can have an empty body, so clients must always check the status code before decoding JSON.

The 414-417 responses below are legacy API-specific codes. Their meanings differ from the standard HTTP status descriptions and are preserved for compatibility with existing API v2 clients.

Status	API v2 meaning
400	Invalid request, missing parameter, missing file, or unsupported endpoint
413	Uploaded file exceeds the configured size limit
414	Uploaded file has an unsupported image format
415	Gallery does not exist
416	Gallery upload token is incorrect
417	Gallery could not be finalized
500	Internal server error

Requests rejected by upload security controls can return a plain-text message instead of JSON.