NAV
cURL Python PHP

Introduction

Welcome to the PiXhost API!

You can use this API to upload images, covers or galleries.

The following image formats are supported: image/gif, image/png, image/jpeg. Maximum image size is 10 MB.

In case you have any ideas, questions or issues, feel free to contact us at: admin@pixhost.org.

Old API users: We recently enforced https, please update your scripts.

Updates

18/11/2016 - Switched from http to https

Conventions

The API uses UTF-8 character encoding and each request should include the following headers.

Image uploads:

Content-Type: multipart/form-data; charset=utf-8
Accept: application/json

Other requests:

Content-Type: application/x-www-form-urlencoded; charset=utf-8
Accept: application/json

Images

Upload Image

HTTP Request

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

curl -X POST --include "https://api.pixhost.org/images" \
  -H 'Content-Type: multipart/form-data; charset=utf-8' \
  -H 'Accept: application/json' \
  -F 'img=@image.jpg' \
  -F 'content_type=0' \
  -F 'max_th_size=420'
import unirest
response = unirest.post("https://api.pixhost.org/images",
  headers={
    "Content-Type": "multipart/form-data; charset=utf-8",
    "Accept": "application/json"
  },
  params={
    "img": open("image.jpg", mode="r"),
   "content_type": "0",
   "max_th_size": "420"
  }
)
<?php
// require http://unirest.io/php
$response = Unirest\Request::post("https://api.pixhost.org/images",
    array(
        "Content-Type" => "multipart/form-data; charset=utf-8",
        "Accept" => "application/json"
    ),
    array(
        "img" => Unirest\Request\Body::file('image.jpg'),
        "content_type" => "0",
        "max_th_size" => "420"
    )
);

Response headers

HTTP/1.1 200 OK
Server: nginx/1.8.0
Date: Thu, 27 Oct 2016 06:35:37 GMT
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
Vary: Accept-Encoding

Response body

{  
   "name":"image.jpg",
   "show_url":"http:\/\/pixhost.org\/show\/0\/563_image.jpg",
   "th_url":"http:\/\/t1.pixhost.org\/thumbs\/0\/563_image.jpg"
}

Query Parameters

Parameter Type Optional Values Description
img image false Image to be uploaded
content_type integer false 0,1 0 for FS / 1 for NSFW
max_th_size integer true 200-500 Maximum image measurements
gallery_hash string true
gallery_upload_hash string true

Response

Parameter Optional Description
name false Image name
show_url false Show a friend URL
th_url false Thumbnail URL

Cover Upload

HTTP Request

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

curl -X POST --include "https://api.pixhost.org/covers" \
  -H 'Content-Type: multipart/form-data; charset=utf-8' \
  -H 'Accept: application/json' \
  -F 'img_left=@left.jpg' \
  -F 'img_right=@right.png' \
  -F 'content_type=0'
import unirest
response = unirest.post("https://api.pixhost.org/covers",
  headers={
    "Content-Type": "multipart/form-data; charset=utf-8",
    "Accept": "application/json"
  },
  params={
    "img_left": open("left.jpg", mode="r"),
    "img_right": open("right.png", mode="r"),
    "content_type": "0"
  }
)
<?php
// require http://unirest.io/php
$response = Unirest\Request::post("https://api.pixhost.org/covers",
    array(
        "Content-Type" => "multipart/form-data; charset=utf-8",
        "Accept" => "application/json"
    ),
    array(
        "img_left" => Unirest\Request\Body::file('left.jpg'),
        "img_right" => Unirest\Request\Body::file('right.png'),
        "content_type" => "0"
    )
);

Response headers

HTTP/1.1 200 OK
Server: nginx/1.8.0
Date: Thu, 27 Oct 2016 16:35:38 GMT
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
Vary: Accept-Encoding

Response body

{  
   "name":"left.jpg",
   "show_url":"http:\/\/pixhost.org\/show\/0\/568_left.jpg",
   "th_url":"http:\/\/t1.pixhost.org\/thumbs\/0\/568_left.jpg"
}

Query Parameters

Parameter Type Optional Values Description
img_left image false Left image in the cover
img_right image true Right image in the cover
content_type integer false 0,1 0 for FS / 1 for NSFW
gallery_hash string true
gallery_upload_hash string true

Response

Parameter Optional Description
name false Image name
show_url false Show a friend URL
th_url false Thumbnail URL

Galleries

HTTP Request

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

curl -X POST --include "https://api.pixhost.org/galleries" \
  -H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
  -H 'Accept: application/json' \
  -d 'gallery_name=Test gallery'
import unirest
response = unirest.post("https://api.pixhost.org/galleries",
  headers={
    "Content-Type": "application/x-www-form-urlencoded; charset=utf-8",
    "Accept": "application/json"
  },
  params={
    "gallery_name": "Test gallery"
  }
)
<?php
// require http://unirest.io/php
$response = Unirest\Request::post("https://api.pixhost.org/galleries",
    array(
        "Content-Type" => "application/x-www-form-urlencoded; charset=utf-8",
        "Accept" => "application/json"
    ),
    array(
        "gallery_name" => "Test gallery"
    )
);

Response headers

HTTP/1.1 200 OK
Server: nginx/1.8.0
Date: Thu, 27 Oct 2016 19:09:39 GMT
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
Vary: Accept-Encoding

Response body

{
  "gallery_name": "Test gallery",
  "gallery_hash": "8NtKF",
  "gallery_url": "http:\/\/pixhost.org\/galleries\/8NtKF",
  "gallery_upload_hash": "yKtOl8NbHMYJ8yWj8Mh90sIlfXC7PXT6RHW8Xua7"
}

Query Parameters

Parameter Type Optional Values Description
gallery_name string false

Response

Parameter Type Values Description
gallery_name string
gallery_hash string Gallery Identificator
gallery_url string Show a friend URL
gallery_upload_hash string Context for uploading new images to created gallery. This context is valid for a 24 hours period.

Each gallery must be finalized gallery after uploading. Otherwise it is automatically finalized after a 24h period. A gallery & images are not available until the gallery is finalized.
During this process, an empty gallery will be removed.

HTTP Request

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

curl -X POST --include "https://api.pixhost.org/galleries/8NtKF/finalize" \
  -H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
  -H 'Accept: application/json' \
  -d 'gallery_upload_hash=yKtOl8NbHMYJ8yWj8Mh90sIlfXC7PXT6RHW8Xua7'
import unirest
response = unirest.post("https://api.pixhost.org/galleries/R34Hfx/finalize",
  headers={
    "Content-Type": "application/x-www-form-urlencoded; charset=utf-8",
    "Accept": "application/json"
  },
  params={
    "gallery_upload_hash": "BBN3JMd8Ce1sanzFZDxbt2dIdTo6ivLguy66PGem"
  }
)
<?php
// require http://unirest.io/php
$response = Unirest\Request::post("https://api.pixhost.org/galleries/8NtKF/finalize",
    array(
        "Content-Type" => "application/x-www-form-urlencoded; charset=utf-8",
        "Accept" => "application/json"
    ),
    array(
        "gallery_upload_hash" => "yKtOl8NbHMYJ8yWj8Mh90sIlfXC7PXT6RHW8Xua7"
    )
);

Response headers

HTTP/1.1 200 OK
Server: nginx/1.8.0
Date: Thu, 27 Oct 2016 23:19:40 GMT
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
Vary: Accept-Encoding

Query Parameters

Parameter Type Optional Values Description
gallery_upload_hash string false

Errors

The PiXhost API uses the following error codes:

Error Code Meaning
400 Bad Request
413 File Size Exceeds Limits
414 Unexpected File Format
415 Gallery Not Exist
416 Gallery Incorrect Upload Hash
417 Gallery Unable To Finalize
500 Internal Server Error – We had a problem with our server. Try again later.