Introduction

Base URL

https://api.crush.pics

Authentication

To use Crush.pics API, you need to sign up for Crush.pics API services and obtain your API token. Once you have setup your Account, you can start using Crush.pics API.

Supported formats

Crush.pics API support following formats:

JPEG
PNG
GIF

Supported compression types

Crush.pics API support following compression types:

lossless
lossy with ability to set up compression level
balanced

Authentication

Request

Endpoint

https://api.crush.pics/v1/compress

HTTP method

POST

Example request

curl -X "POST" "https://api.crush.pics/v1/compress" \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Bearer your-api-token' \
     -F "image_url=https://your-website.com/images/image.png" \
     -F "compression_type=lossy" \
     -F "compression_level=65"

{
  "image_url": "http://your-website.com/images/image.png",
  "compression_type": "lossy",
  "compression_level": "65"
}

Crush.pics API accepts HTTPS POST, PATCH, GET requests. Each request needs to be a valid JSON object with mandatory headers Authorization, Accept and Content-Type.

Important: Crush.pics API supports only HTTPS protocol. All HTTP requests will be rejected.

Account details

Request

Endpoint

https://api.crush.pics/v1/shop

HTTP method

GET

Response

Example response

HTTP/1.1 200 OK

{
  "shop": {
    "login": "user@example.com",
    "email": null,
    "compression_type": "lossy",
    "compression_level_jpg": 85,
    "compression_level_png": 85,
    "compression_level_gif": null,
    "charged_at": null,
    "next_charge_at": null,
    "created_at": "2018-11-12T15:04:27Z",
    "updated_at": "2018-11-12T15:04:27Z",
    "callback_urls": [
      {
        "id": 3,
        "url": "https://test.com/wh"
      },
      {
        "id": 4,
        "url": "https://example.com/webhook"
      }
    ],
    "plan_data": {
      "code": "free",
      "name": "Free",
      "price": "$0.00",
      "bytes": 25000000,
      "quota_usage": 3600688
    }
  }
}

Update account settings

Request

Endpoint

https://api.crush.pics/v1/shop

HTTP method

PATCH

Example request

curl -X "POST" "https://api.crush.pics/v1/shop" \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -d $'{
  "compression_level_png": 70,
  "compression_level_jpg": 70,
  "compression_level_gif": 70,
  "compression_type": "lossy",
}'

{
  "compression_type": "lossy",
  "compression_level_jpg": 70,
  "compression_level_png": 70,
  "compression_level_gif": 70,
}

Parameters

Parameter	Type	Required	Description
`compression_type`	string	no	`lossy` / `lossless` / `balanced` compression switch
`compression_level_jpg`	integer	no	Lossy compression level for JPEG/JPG files
`compression_level_png`	integer	no	Lossy compression level for PNG files
`compression_level_gif`	integer	no	Lossy compression level for GIF files

Response

Example response

HTTP/1.1 200 OK

{
  "shop": {
    "login": "user@example.com",
    "email": null,
    "compression_type": "lossy",
    "compression_level_jpg": 85,
    "compression_level_png": 85,
    "compression_level_gif": null,
    "charged_at": null,
    "next_charge_at": null,
    "created_at": "2018-11-12T15:04:27Z",
    "updated_at": "2018-11-12T15:04:27Z",
    "callback_urls": [
      {
        "id": 3,
        "url": "https://test.com/wh"
      },
      {
        "id": 4,
        "url": "https://example.com/webhook"
      }
    ],
    "plan_data": {
      "code": "free",
      "name": "Free",
      "price": "$0.00",
      "bytes": 25000000,
      "quota_usage": 3600688
    }
  }
}

Image compression (Synchronously)

You can send any JPEG, PNG, GIF or SVG image to the Crush.pics API and it will automatically detect the type of image and compress it. You can choose to upload a file or provide a URL to the image.

Request

Endpoint

https://api.crush.pics/v1/compress

HTTP method

POST

Image Upload

Optimise image with direct upload in POST request

Example Request

curl -X "POST" "https://api.crush.pics/v1/compress" \
     -H 'Accept: application/json' \
     -H 'Content-Type: multipart/form-data; boundary=Fu0hjwe' \
     -H 'Authorization: Bearer your-api-token' \
     -F "file=@unoptimized-image.jpg" \
     -F "compression_type=lossy" \
     -F "compression_level=65" \

{
  "file": "@unoptimized-image.jpg",
  "compression_type": "lossy",
  "compression_level": 65
}

Parameters

Parameter	Type	Required	Default	Description
`file`	blob	yes		Provide image content in POST request
`compression_type`	string	no	Fallback to account settings	`lossy` / `lossless` / `balanced` compression switch
`compression_level`	integer	no	Fallback to account settings	Lossy compression quality settings (1-100)
`resize`	array	no	[]	An array of styles to resize image

Style object

Parameter	Type	Required	Description
`style`	string	yes	User-defined style name
`width`	integer	yes
`height`	integer	yes

Image URL

Optimise image by provide an URL to the image you want to optimise.

Request

Example request

curl -X "POST" "https://api.crush.pics/v1/compress" \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Bearer your-api-token' \
     -F "image_url=https://your-website.com/images/image.png" \
     -F "compression_type=lossy" \
     -F "compression_level=65"

{
  "image_url": "http://your-website.com/images/image.png",
  "compression_type": "lossy",
  "compression_level": 65
}

Parameters

Parameter	Type	Required	Default	Description
`image_url`	string	yes		Provide `URL` to the image you want to compress
`compression_type`	string	no	Fallback to account settings	`lossy` / `lossless` / `balanced` compression switc
`compression_level`	integer	no	Fallback to account settings	lossy compression quality settings (1-100)
`resize`	array	no	[]	An array of styles to resize image

Style object

Parameter	Type	Required	Description
`style`	string	yes	User-defined style name
`width`	integer	yes
`height`	integer	yes

Response

Example response

HTTP/1.1 200 OK

{
  "original_image": {
    "id": 5,
    "compression_type": "lossy",
    "compression_level": 65,
    "origin": "file",
    "size": 297412,
    "file_type": "image/png",
    "filename": "photo.png",
    "status": "completed",
    "created_at": "2018-07-09T13:07:42.943Z",
    "updated_at": "2018-07-09T13:07:46.074Z",
    "link": "https://api.crush.pics/v1/files/X8KxL3cD1viTBasepBwSL4Tz/photo.png",
    "optimized_images": [
      {
        "id": 4,
        "status": "enqueued",
        "compression_type": "lossless",
        "compression_level": 0,
        "style": "icon",
        "width": 150,
        "height": 150,
        "link": "https://api.crush.pics/v1/files/ZdcSBAk1m4XMeH9KNvSmWFNN/photo.png",
        "size": 465,
        "file_type": "image/png",
        "filename": "photo.png",
        "created_at": "2018-07-09T13:07:43.005Z",
        "updated_at": "2018-07-09T13:07:46.069Z"
      }
    ]
  }
}

Response body will have optimization results containing a success property, original file size, compressed file size, amount of savings, original image dimensions (in pixels) and optimized image URL.

Image compression (Asynchronously, respond with webhooks)

You can send any JPEG, PNG, GIF or SVG image to the Crush.pics API and it will automatically detect the type of image and compress it. You can choose to upload a file or provide a URL to the image.

Request

Endpoint

https://api.crush.pics/v1/original_images

HTTP method

POST

Image Upload

Optimise image with direct upload in POST request

Request

Example Request

curl -X "POST" "https://api.crush.pics/v1/original_images" \
     -H 'Accept: application/json' \
     -H 'Content-Type: multipart/form-data; boundary=Fu0hjwe' \
     -H 'Authorization: Bearer your-api-token' \
     -F "file=@unoptimized-image.jpg" \
     -F "compression_type=lossy" \
     -F "compression_level=65" \

{
  "file": "@unoptimized-image.jpg",
  "compression_type": "lossy",
  "compression_level": 65
}

Parameters

Parameter	Type	Required	Default	Description
`file`	blob	yes		Provide image content in POST request
`compression_type`	string	no	Fallback to account settings	`lossy` / `lossless` / `balanced` compression switch
`compression_level`	integer	no	Fallback to account settings	Lossy compression quality settings (1-100)
`resize`	array	no	[]	An array of styles to resize image

Style object

Parameter	Type	Required	Description
`style`	string	yes	User-defined style name
`width`	integer	yes
`height`	integer	yes

Image URL

Optimise image by provide an URL to the image you want to optimise.

Request

Example request

curl -X "POST" "https://api.crush.pics/v1/original_images" \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Bearer your-api-token' \
     -F "image_url=https://your-website.com/images/image.png" \
     -F "compression_type=lossy" \
     -F "compression_level=65"

{
  "image_url": "http://your-website.com/images/image.png",
  "compression_type": "lossy",
  "compression_level": 65
}

Parameters

Parameter	Type	Required	Default	Description
`image_url`	string	yes		Provide `URL` to the image you want to compress
`compression_type`	string	no	Fallback to account settings	`lossy` / `lossless` / `balanced` compression switc
`compression_level`	integer	no	Fallback to account settings	lossy compression quality settings (1-100)
`resize`	array	no	[]	An array of styles to resize image

Style object

Parameter	Type	Required	Description
`style`	string	yes	User-defined style name
`width`	integer	yes
`height`	integer	yes

If HTTP Basic Authentication is enabled on your webserver simply include the username and password as part of the image URL like so: https://username:password@my-website.com/images/image.png

Response

Example response

HTTP/1.1 200 OK

{
  "original_image": {
    "id": 5,
    "compression_type": "lossy",
    "compression_level": 65,
    "origin": "file",
    "size": 297412,
    "file_type": "image/png",
    "filename": "photo.png",
    "status": "enqueued",
    "created_at": "2018-06-29T15:52:22.589Z",
    "updated_at": "2018-06-29T15:52:22.596Z",
    "link": "https://api.crush.pics/v1/files/LX8Xhv3Z2T2dQDSRnrC3UBxg/photo.png"
  },
  "success": true
}

HTTP/1.1 422 Unprocessable Entity

{
  "message": {
    "file": [
      "can't be blank"
    ]
  },
  "formatted_message": "File can't be blank",
  "original_image": {
    "compression_type": "lossy",
    "compression_level": 65,
    "size": null,
    "file_type": null,
    "filename": null
  },
  "success": false
}

Response body will contain a set of basic image attributes e.g id, size, filename, status and etc. Using the image id you can fetch results of image optimization and get compressed/resized images.

Image Resizing

Request

Example request

curl -X "POST" "https://api.crush.pics/v1/original_images" \
     -H 'Accept: application/json' \
     -H 'Content-Type: multipart/form-data; boundary=ArRCoq7' \
     -H 'Authorization: Bearer your-api-token' \
     -d $'{
  "compression_type": "lossy",
  "resize[][width]": "100",
  "compression_level": "65",
  "image_url": "http://your-website.com/images/image.png",
  "resize[][style]": "thumb",
  "resize[][height]": "100",
  "resize[][width]": "320",
  "resize[][height]": "crop",
  "resize[][style]": "pico",
  "resize[][height]": "25",
  "resize[][width]": "80",
  "resize[][height]": "crop",
}'

{
  "image_url": "http://your-website.com/images/image.png",
  "resize": [
    {
      "width": 320,
      "height": 100,
      "style": "thumb"
    },
    {
      "width": 80,
      "height": 25,
      "style": "pico"
    }
  ]
}

You can use Crush.pics API resizing option to create thumbnails or preview images for your applications. Crush.pics will first resize the given image and then optimize it. The resize option needs a few parameters to be passed, such as the desired width and/or height, as well as a mandatory style property.

Dashboard

Request

Endpoint

https://api.crush.pics/v1/dashboard

HTTP method

GET

Response

Example response

HTTP/1.1 200 OK

{
  "stats": {
    "original_images_count": 475,
    "optimized_images_count": 475,
    "consumption": {
      "type": "six_months",
      "data": [
        {
          "origin": "file",
          "size": null,
          "period": 2
        },
        {
          "origin": "shopify_article",
          "size": null,
          "period": 2
        },
        {
          "origin": "file",
          "size": null,
          "period": 3
        },
        {
          "origin": "file",
          "size": null,
          "period": 6
        },
        {
          "origin": "shopify",
          "size": 1858202,
          "period": 7
        },
        {
          "origin": "file",
          "size": null,
          "period": 7
        }
      ]
    }
  }
}

Image details

Request

Endpoint

https://api.crush.pics/v1/original_images/:id

HTTP method

GET

Query Parameters

Parameter	Type	Required	Description
`id`	integer	yes	Image ID

Response

Example response

HTTP/1.1 200 OK

{
  "original_image": {
    "id": 5,
    "compression_type": "lossy",
    "compression_level": 65,
    "origin": "file",
    "size": 297412,
    "file_type": "image/png",
    "filename": "photo.png",
    "status": "completed",
    "created_at": "2018-07-09T13:07:42.943Z",
    "updated_at": "2018-07-09T13:07:46.074Z",
    "link": "https://api.crush.pics/v1/files/X8KxL3cD1viTBasepBwSL4Tz/photo.png",
    "optimized_images": [
      {
        "id": 4,
        "status": "enqueued",
        "compression_type": "lossless",
        "compression_level": 0,
        "style": "icon",
        "width": 150,
        "height": 150,
        "link": "https://api.crush.pics/v1/files/ZdcSBAk1m4XMeH9KNvSmWFNN/photo.png",
        "size": 465,
        "file_type": "image/png",
        "filename": "photo.png",
        "created_at": "2018-07-09T13:07:43.005Z",
        "updated_at": "2018-07-09T13:07:46.069Z"
      }
    ]
  }
}

List images

Request

Endpoint

https://api.crush.pics/v1/original_images?page=1

HTTP method

GET

Query Parameters

Parameter	Type	Required	Default	Description
`page`	integer	no	1	Page number

Response

Example response

HTTP/1.1 200 OK

{
  "original_images": [
    {
      "id": 4523,
      "compression_type": "lossy",
      "compression_level": 85,
      "origin": "file",
      "status": "completed",
      "created_at": "2019-07-25T15:47:07.836Z",
      "updated_at": "2019-07-26T03:48:00.201Z"
    },
    {
      "id": 4514,
      "compression_type": "lossy",
      "compression_level": 85,
      "origin": "file",
      "status": "completed",
      "created_at": "2019-07-24T09:47:54.942Z",
      "updated_at": "2019-07-24T21:48:00.541Z"
    },
    {
      "id": 4488,
      "compression_type": "balanced",
      "compression_level": 85,
      "origin": "shopify",
      "status": "completed",
      "created_at": "2019-07-19T14:22:07.610Z",
      "updated_at": "2019-07-20T02:23:00.149Z"
    },
    {
      "id": 4487,
      "compression_type": "balanced",
      "compression_level": 85,
      "origin": "shopify",
      "status": "completed",
      "created_at": "2019-07-19T14:21:50.287Z",
      "updated_at": "2019-07-20T02:22:00.478Z"
    },
    {
      "id": 4486,
      "compression_type": "balanced",
      "compression_level": 85,
      "origin": "shopify",
      "status": "completed",
      "created_at": "2019-07-19T14:21:13.540Z",
      "updated_at": "2019-07-20T02:22:00.515Z"
    },
    {
      "id": 4485,
      "compression_type": "balanced",
      "compression_level": 85,
      "origin": "shopify",
      "status": "completed",
      "created_at": "2019-07-19T14:21:11.969Z",
      "updated_at": "2019-07-20T02:22:00.483Z"
    },
    {
      "id": 4484,
      "compression_type": "balanced",
      "compression_level": 85,
      "origin": "shopify",
      "status": "completed",
      "created_at": "2019-07-19T14:21:09.659Z",
      "updated_at": "2019-07-20T02:22:00.495Z"
    },
    {
      "id": 4483,
      "compression_type": "balanced",
      "compression_level": 85,
      "origin": "shopify",
      "status": "completed",
      "created_at": "2019-07-19T14:20:54.646Z",
      "updated_at": "2019-07-20T02:21:00.402Z"
    },
    {
      "id": 4160,
      "compression_type": "balanced",
      "compression_level": 85,
      "origin": "shopify",
      "status": "enqueued",
      "created_at": "2019-07-17T12:17:44.097Z",
      "updated_at": "2019-07-18T00:18:00.273Z"
    },
    {
      "id": 4016,
      "compression_type": null,
      "compression_level": null,
      "origin": "file",
      "status": "completed",
      "created_at": "2019-06-27T19:57:33.628Z",
      "updated_at": "2019-06-28T07:58:00.206Z"
    }
  ],
  "pagination": {
    "current": 1,
    "total_pages": 13,
    "total_count": 124,
    "per_page": 10,
    "count": 10
  }
}

List callback urls

Request

Endpoint

https://api.crush.pics/v1/callback_urls

HTTP method

GET

Example Request

curl -X "GET" "https://api.crush.pics/v1/callback_urls/1" \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Bearer your-api-token'

Response

Example response

HTTP/1.1 200 OK

{
  "callback_urls": [
    {
      "id": 4,
      "url": "https://test.com/wh"
    }
  ]
}

Add callback url

Request

Endpoint

https://api.crush.pics/v1/callback_urls

HTTP method

POST

Example Request

curl -X "POST" "https://api.crush.pics/v1/callback_urls" \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Bearer your-api-token' \
     -d '{"url": "https://example.com/webhook"}'

{
  "url": "https://example.com/webhook"
}

Parameters

Parameter	Type	Required	Default	Description
`url`	string	yes		URL (HTTPS only)

Response

Example response

HTTP/1.1 200 OK

{
  "callback_url": {
    "id": 7,
    "url": "https://example.com/webhook"
  }
}

HTTP/1.1 422 Unprocessable Entity

{
  "message": {
    "url": [
      "has already been taken"
    ]
  },
  "formatted_message": "Url has already been taken"
}

HTTP/1.1 422 Unprocessable Entity

{
  "message": {
    "url": [
      "is invalid"
    ]
  },
  "formatted_message": "Url is invalid"
}

Remove callback url

Request

Endpoint

https://api.crush.pics/v1/callback_urls/:id

HTTP method

DELETE

Example Request

curl -X "DELETE" "https://api.crush.pics/v1/callback_urls/1" \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Bearer your-api-token'

Query Parameters

Parameter	Type	Required	Description
`id`	integer	yes	Custom callback ID

Response

Example response

HTTP/1.1 200 OK

Example response

HTTP/1.1 404 OK

{
  "status": 404,
  "error": "Not Found"
}

Webhooks

Crush API support following types of webhooks:

image#processing
image#error
image#optimized
shop#subscription_updated

Crush API use POST requests to send webhooks and treat webhook as successfully delivered if the webserver responds with status code 201 Created.

If the webserver responds with any other HTTP status code - Crush API marks webhook as failed and try to redeliver it later. Max number of retries to deliver webhook - 5.

Crush API does not try to read response body.

`image#processing`

Example payload

{
  "object_type": "image",
  "shop_identifier": "user@example.com",
  "compression_type": "balanced",
  "compression_level": null,
  "image_id": 111,
  "event": "processing",
  "link": "https://url.to.download/image"
}

`image#error`

Example payload

{
  "object_type": "image",
  "shop_identifier": "user@example.com",
  "compression_type": "balanced",
  "compression_level": null,
  "image_id": 111,
  "event": "error",
  "error": "cant_compress",
  "quota_usage:": 1212121
}

`image#optimized`

Example payload

{
  "object_type": "image",
  "shop_identifier": "user@example.com",
  "compression_type": "lossy",
  "compression_level": 65,
  "image_id": 111,
  "event": "optimized",
  "optimized_images": [
    {
      "style": "original",
      "size": 154356,
      "link": "https://url.to.download/image",
      "id": 112,
      "expire_at": "2019-07-30T11:22:56Z"
    }
  ],
  "quota_usage:": 1212121
}

`shop#subscription_updated`

Example payload

{
  "object_type": "shop",
  "shop_identifier": "user@example.com",
  "event": "subscription_updated",
  "charged_at": "2019-07-30T11:22:56Z",
  "next_charge_at": "2019-08-30T11:22:56Z",
  "subscription_id": "JN677WHBDWH8762",
  "subscription_status": "active",
  "customer_id": "JN677WHBDWH8762",
  "plan_data": {
    "code": "free",
    "name": "Free",
    "price": "$0.00",
    "bytes": 25000000,
    "quota_usage": 16388889
  }
}

Errors

The Crush.pics API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid (Usually invalid JSON).
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- When your account is suspended.
413	Request Entity Too Large -- Sending a file larger than your plan allows.
415	Unsupported Media Type -- Sending an unsupported image type
422	Unprocessable Entity -- Sending invalid JSON properties
429	Too Many Requests -- You're sending too many requests at the same time.
500	Internal Server Error -- We had a problem with our server or any other unexpected server error. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.