API Documentation - v1

This is the first version of the Eroshare API and provides the most requested features. Be prepared for short release cycles. Additional features (ie. client registration) may be introduced at any time so please check back regularly.

Video uploads are limited to 50 videos within a 24 hour window. Additional limitations may be put in if necessary. Please do not abuse the service as we'd hate to ban you!

If you have any questions, feel free to ​contact us.

API Endpoint

https://api.eroshare.com/api/v1

Creating an Album

Each media item has to be part of an album. So before you can upload a media item you need to create an album.

POST https://api.eroshare.com/api/v1/albums
Don't share the key but store it safely. It can be used to make changes to an album.
curl -X POST https://api.eroshare.com/api/v1/albums -d ''

{
  "id":"g4uzgbu5",
  "title":null,
  "slug":"g4uzgbu5",
  "created_at":"2016-09-06T17:03:48.791Z",
  "views":0,
  "gender_male":0,
  "gender_female":0,
  "secret":true, // anonymous uploads are always secret by default
  "reddit_submission":null,
  "items":[],
  "url":"https://api.eroshare.com/g4uzgbu5",
  "key":"97321d75-5544-41ec-81b4-44bb03928725" // the key is required in order to make changes to an album
}

Uploading to an Album

Now you can upload media items (images, videos) to an album. Videos are automatically converted which might take some time.
POST https://api.eroshare.com/api/v1/albums/[album_id]/items

Required Parameters:
  key - album key
  file - the file
# Image example
curl -F "file=@upload.jpg" -F "key=97321d75-5544-41ec-81b4-44bb03928725" "https://api.eroshare.com/api/v1/albums/g4uzgbu5/items"

{
  "id":"z32c890y"
  "description":null,
  "slug":"z32c890y",
  "state":"ready",
  "type":"Image",
  "width":1224,
  "height":1680,
  "url_full_protocol_encoded":"http%3A%2F%2Fi.api.eroshare.com%2Fz32c890y.jpg",
  "url_full_protocol":"https://i.api.eroshare.com/z32c890y.jpg",
  "url_full":"//i.api.eroshare.com/z32c890y.jpg",
  "url_thumb":"//i.api.eroshare.com/z32c890y_thumb.jpg",
  "url_orig":"//i.api.eroshare.com/z32c890y_orig.jpg",
  "position":0,  // this indicates the position in the album starting with 0
  "is_portrait":true,
}
# Video example
curl -F "file=@upload.mp4" -F "key=97321d75-5544-41ec-81b4-44bb03928725" "https://api.eroshare.com/api/v1/albums/g4uzgbu5/items"

{
  "id":"6s5a5qsy",
  "description":null,
  "slug":"6s5a5qsy",
  "state":"created",  // conversion hasn't started (created, converting, ready)
  "conversion_progress":0,
  "type":"Video",
  "width":568,
  "height":320,
  "video_duration":120,
  "url_full_protocol_encoded":"https%3A%2F%2Fi.api.eroshare.com%2F6s5a5qsy.jpg",
  "url_full_protocol":"https://i.api.eroshare.com/6s5a5qsy.jpg",
  "url_full":"//i.api.eroshare.com/6s5a5qsy.jpg",
  "url_thumb":"//i.api.eroshare.com/6s5a5qsy_thumb_play.jpg",
  "url_orig":"//i.dev_api.eroshare.com/6s5a5qsy_orig.mp4",
  "url_mp4":"//v.api.eroshare.com/6s5a5qsy.mp4",
  "url_mp4_lowres":"//v.api.eroshare.com/6s5a5qsy_lowres.mp4",
  "position":1,
  "is_portrait":false,
  "lowres":false  // if a low resolution version of the video is available
}

Getting Album Information

GET https://api.eroshare.com/api/v1/albums/[album_id]
curl https://api.eroshare.com/api/v1/albums/g4uzgbu5

{
  "id":"g4uzgbu5",
  "title":null,
  "slug":"g4uzgbu5",
  "created_at":"2016-09-07T10:01:38.549Z",
  "views":5,
  "gender_male":-1,
  "gender_female":-1,
  "secret":true,
  "reddit_submission":null,
  "url":"https://api.eroshare.com/g4uzgbu5",
  "items":[
    {
      "type":"Image",
      "id":"z32c890y",
      "description":null,
      "slug":"z32c890y",
      "state":"ready",
      "width":1224,
      "height":1680,
      "url_full_protocol_encoded":"http%3A%2F%2Fi.api.eroshare.com%2Fz32c890y.jpg",
      "url_full_protocol":"https://i.api.eroshare.com/z32c890y.jpg",
      "url_full":"//i.api.eroshare.com/z32c890y.jpg",
      "url_thumb":"//i.api.eroshare.com/z32c890y_thumb.jpg",
      "url_orig":"//i.api.eroshare.com/z32c890y_orig.jpg",
      "position":0,"is_portrait":true
    },
    {
      "type":"Video",
      "id":"6s5a5qsy",
      "description":null,
      "slug":"6s5a5qsy",
      "state":"ready",
      "conversion_progress":100,
      "width":568,
      "height":320,
      "url_full_protocol_encoded":"https%3A%2F%2Fi.api.eroshare.com%2F6s5a5qsy.jpg",
      "url_full_protocol":"https://i.api.eroshare.com/6s5a5qsy.jpg",
      "url_full":"//i.api.eroshare.com/6s5a5qsy.jpg",
      "url_thumb":"//i.api.eroshare.com/6s5a5qsy_thumb_play.jpg",
      "url_orig":"//i.dev_api.eroshare.com/6s5a5qsy_orig.mp4",
      "url_mp4":"//v.api.eroshare.com/6s5a5qsy.mp4",
      "url_mp4_lowres":"//v.api.eroshare.com/6s5a5qsy_lowres.mp4",
      "position":1,
      "is_portrait":false,
      "lowres":true
    }
  ]
}

Getting Item Information

Sometimes you'd want to get a single media item's information - e.g. to see if the conversion of a video has finished.
GET https://api.eroshare.com/api/v1/albums/[album_id]/items/[item_id]
curl https://api.eroshare.com/api/v1/albums/g4uzgbu5/items/6s5a5qsy

{
  "type":"Video",
  "id":"6s5a5qsy",
  "description":null,
  "slug":"6s5a5qsy",
  "state":"ready", // this video is ready to play
  "conversion_progress":100,
  "width":568,
  "height":320,
  "video_duration":120,
  "url_full_protocol_encoded":"https%3A%2F%2Fi.api.eroshare.com%2F6s5a5qsy.jpg",
  "url_full_protocol":"https://i.api.eroshare.com/6s5a5qsy.jpg",
  "url_full":"//i.api.eroshare.com/6s5a5qsy.jpg",
  "url_thumb":"//i.api.eroshare.com/6s5a5qsy_thumb_play.jpg",
  "url_orig":"//i.dev_api.eroshare.com/6s5a5qsy_orig.mp4",
  "url_mp4":"//v.api.eroshare.com/6s5a5qsy.mp4",
  "url_mp4_lowres":"//v.api.eroshare.com/6s5a5qsy_lowres.mp4",
  "position":3,
  "is_portrait":false,
  "lowres":true // a low resolution version has been created
}

Updating Album and Item Information

PUT https://api.eroshare.com/api/v1/albums/[album_id]

Required Parameters:
  id - album id
  key - album key
Here is an exmple payload. The album title, the item descriptions and the item positions can be changed. Add the required parameters
curl -X PUT https://api.eroshare.com/api/v1/albums/g4uzgbu5 \
  -H "Content-Type: application/json" \
  -d '{
       "id":"g4uzgbu5",
       "key":"97321d75-5544-41ec-81b4-44bb03928725",
       "title":"New Album Title",
       "items":[
         {
           "id":"z32c890y",
           "description":"Updated description for the image",
           "position": "1"
         },
         {
           "id":"6s5a5qsy",
           "description":"Updated description for the video",
           "position": "0"
         }
       ]
     }'


# Same thing, no JSON
curl -X PUT https://api.eroshare.com/api/v1/albums/g4uzgbu5 \
  -F "id=g4uzgbu5" \
  -F "key=97321d75-5544-41ec-81b4-44bb03928725" \
  -F "title=No JSON please" \
  -F "items[][id]=z32c890y" \
  -F "items[][description]=Why no JSON?" \
  -F "items[][position]=0" \
  -F "items[][id]=6s5a5qsy" \
  -F "items[][description]=Really.. why no JSON?" \
  -F "items[][position]=1"

Deleting an Item

Sometimes you only want to delete a single item from an album.
DELETE https://api.eroshare.com/api/v1/albums/[album_id]/items/[item_id]

Required Parameters:
  key - album key
curl -X DELETE https://api.eroshare.com/api/v1/albums/g4uzgbu5/items/fdczyvxa -d "key=97321d75-5544-41ec-81b4-44bb03928725"

{
  "code":"ok",
  "message":"Deleted"
}

Deleting an Album

Remember, deleting an album is permanent.
DELETE https://api.eroshare.com/api/v1/albums/[album_id]

Required Parameters:
  key - album key
curl -X DELETE https://api.eroshare.com/api/v1/albums/g4uzgbu5 -d "key=97321d75-5544-41ec-81b4-44bb03928725"

{
  "code":"ok",
  "message":"Deleted"
}