The 6px API is built on HTTP. Our API is RESTful and it:
- Has predictable, resource-oriented URLs
- Uses built-in HTTP capabilities for passing parameters
- Responds with standard HTTP response codes to indicate errors
- Sends and receives data as JSON
6px has published SDKs for various languages.
To give you an idea of how to use the API, we have annotated our documentation with code samples written in curl.
- Base URL
- Authentication
- Date Format
- Errors
- Limits
- Pagination
- Sorting
- Search
- Methods
- Input JSON
- Output JSON
- Endpoints
- Web Sockets
- SDKs
All API endpoints referenced in this documentation should start with the following base URL:
https://api.6px.io/v1/
When you sign up for an account, you are given an API key and secret. You authenticate with the 6px API by providing your API key and secret in every request. You can manage your API key and secret in the My Account
section of the dashboard.
$ curl https://api.6px.io/v1/users/:user_id/jobs?key=YOUR_KEY&secret=YOUR_SECRET
Authentication using an API secret should only be used in server to server scenarios. If you're making a request via from a browser via AJAX, please omit the secret and ensure that the requesting domain is whitelisted in the account section of your dashboard.
6px returns JSON for all API calls. Dates are passed as an ISO 8601 formatted datetime.
2014-01-23T19:40:42+17:00
Code | Error | Description |
---|---|---|
200 |
OK | Everything worked as expected |
400 |
Bad Request | Often missing a required parameter |
401 |
Unauthorized | Invalid API key or secret, or the domain is not allowed |
404 |
Not Found | The requested resource doesn’t exist |
429 |
Too Many Requests | You are sending too many requests too quickly or you have met your plans API quota |
500 |
Internal Server Error | Something went wrong on our end |
Rate limits are defined by the number of API calls allowed by your subscription. Only POST
requests to create a job are metered.
Requests that return multiple results will be paginated to 10 resources by default. You can specify further resources with the ?page
parameter.
$ curl https://api.6px.io/v1/users/:user_id/jobs?page=2
To increase the number of resources returned, simply pass the ?per_page
parameter.
$ curl https://api.6px.io/v1/users/:user_id/jobs?page=2&per_page=100
Sort by value:
$ curl https://api.6px.io/v1/users/:user_id/jobs?sort_by=created
Sort by value (descending):
$ curl https://api.6px.io/v1/users/:user_id/jobs?sort_by=created,desc
Sort by value (ascending):
$ curl https://api.6px.io/v1/users/:user_id/jobs?sort_by=created,asc
The search functionality is optimized to help you find jobs using query parameters.
For example:
- Image(s) within a specific area
- Image(s) with specific methods
?number={all}123,456
Both 123 and 456 must be present?number={nin}123,456
Neither 123 nor 456?number={in}123,456
Either 123 or 456?number={gt}123
> 123?number={gte}123
>= 123?number={lt}123
< 123?number={lte}123
<= 123?number={ne}123
Not 123?number={mod}10,2
Where (number / 10) has remainder 2
Example:
$ curl https://api.6px.io/v1/users/:user_id/jobs?processed.bytes={gt}1048576
?string={all}foo,bar
Both foo and bar must be present?string={nin}foo,bar
Neither foo nor bar?string={in}foo,bar
Either foo or bar?string={not}foo
Not foo?string={exact}fOoBaR
Case-sensitive exact match of fOoBaR
Example:
$ curl https://api.6px.io/v1/users/:user_id/jobs?status=processing
?latlon={near}40.0176,-105.2797,5
Near 40.0176,-105.2797 (with a 5 mile radius)?latlon={near}40.0176,-105.2797
Near 40.0176,-105.2797 (no radius limit, automatically sorts by distance)
Example:
$ curl https://api.6px.io/v1/users/:user_id/jobs?processed.images.latlon={near}40.0176,-105.2797,10
date={gt}1999-12-12T13:33:00.000Z
> 1999-12-12T13:33:00.000Zdate={gte}1999-12-12T13:33:00.000Z
>= 1999-12-12T13:33:00.000Zdate={lt}1999-12-12T13:33:00.000Z
< 1999-12-12T13:33:00.000Zdate={lte}1999-12-12T13:33:00.000Z
<= 1999-12-12T13:33:00.000Zdate={gt}1999-12-12T13:33:00.000Z{lt}2014-01-01T01:01:01.000Z
between 1999-12-12T13:33:00.000Z and 2014-01-01T01:01:01.000Z
Example:
$ curl https://api.6px.io/v1/users/:user_id/jobs?created={gte}1999-12-12T13:33:00.000Z
Options | Type | Required | Description |
---|---|---|---|
degrees |
Number | True | - |
Example:
{
"method": "rotate",
"options": {
"degrees": 90
}
}
Options | Type | Required | Description |
---|---|---|---|
height |
Number | False | - |
width |
Number | False | - |
Example 1:
{
"method": "resize",
"options": {
"height": 200,
"width" : 200
}
}
Example 2:
{
"method": "resize",
"options": {
"width": 400
}
}
Height and/or width are required parameters. Automatic proprotions provided if either parameter is omitted.
Options | Type | Required | Description |
---|---|---|---|
height |
Number | False | - |
width |
Number | False | - |
x |
Number | False | - |
y |
Number | False | - |
face |
Boolean | False | Crops to dominant face. Omit x and y coordinates when using this option. |
padding |
Number | False | Sets specified padding when using face parameter. |
Example 1:
{
"method": "crop",
"options": {
"height": 200,
"width": 200,
"x": 150,
"y" 300
}
}
Example 2:
{
"method": "crop",
"options": {
"height": 100,
"face": true
}
}
Example 3:
{
"method": "crop",
"options": {
"height": 100,
"width": 100,
"face": true,
"padding" 20
}
}
Options | Type | Required | Description |
---|---|---|---|
sepia |
Number | False | Expects a number between 0 to 100 . The higher the number, the more sepia that is applied. |
invert |
Number | False | Expects true or false . For best results, omit invert alltogether if you do not want the filter. |
brightness |
Number | False | Default value is 0 . If you want to white-wash the image, pass 100 as the value. Blaken the image by passing -100 |
contrast |
Number | False | Default value is 0 . If you want to double the contrast, pass 100 as the value. |
exposure |
Number | False | Adjust the exposure amount in the image. -100 to 100 are accepted values. Defaults to 0 . |
noise |
Number | False | Add noise to an image. Defaults to 0 (no noise). Maxes out at 100 (a whole lot of noise). |
saturation |
Number | False | Range of -100 to 100 (defaults at 0 ). |
vibrance |
Number | False | Boosts colors if passed a value above 0 . Will make colors more dull if passed in a value below 0 . |
hue |
Number | False | Range of 0 to 100 |
gamma |
Number | False | Range of 0 to 100 |
colorize |
String | False | Recolor an image with the passed in hex value. Make the image blue, just pass in #0000FF . |
channels |
Object | False | Pass in an object with at least one channel that you want to modify. red , blue , and green are your options and their default values are 0 . To cancel a channel out, pass -100 as the value. |
sharpen |
Number | False | Default value is 100 . If you want to double the sharpness, send the value 200 . |
stackBlur |
Number | False | Pass in the blue radius. 0 - 100 are accepted values. |
Undocumented: curves
Example 1:
{
"method": "filter",
"options": {
"sepia": 70
}
}
Example 2:
{
"method": "filter",
"options": {
"brightness": 150,
"stackBlur": 30
}
}
Example 3:
{
"method": "filter",
"options": {
"sepia": true,
"sharpness": 175,
"blur": true
}
}
Options | Type | Required | Description |
---|---|---|---|
x |
Number | False | The x position for the layered image. |
y |
Number | False | The y position for the layered image. |
opacity |
Number | False | Default value is 1 . Can be omitted if opaque is desired effect. |
ref |
String | False | Image that you would like to layer on top. This is a reference from the input array. |
Example 1:
{
"method": "layer",
"options": {
"x": 0,
"y": 0,
"opacity": 0.6,
"ref": "img1"
}
}
Example 2:
{
"method": "layer",
"options": {
"opacity": 0.6,
"ref": "img2"
}
}
The
x
andy
values can be omitted if you want to play your layered image at the top left corner (0,0)
Options | Required | Description |
---|---|---|
exif |
False | Returns the EXIF data associated with an image. |
color |
False | Analyzing the color returns the pallete or dominant colors in the image. This is specified via the context parameter. The default context is palette. |
nudity |
False | This is an experimental analysis feature. It's accuracy is approximately 60%. |
Example 1:
{
"method": "analyze",
"options": {
"type": "exif"
}
}
Example 2:
{
"method": "analyze",
"options": {
"type": "color",
"context": "palette"
}
}
Example 3:
{
"method": "analyze",
"options": {
"type": "nudity"
}
}
{
"data": {},
"callback": {
"url": "http://example.com/callback"
},
"input": {
"img": "http://example.com/path/to/image1.jpg"
},
"output": [
{
"methods": [
{
"method": "resize",
"options": {
"width": 200,
"height": 200
}
}
],
"type": "image/png",
"ref": {
"img": false
},
"url": "s3://key:secret@bucket/path"
}
]
}
An object
that allows you to store custom data such as a database id, name or email.
Example Store:
{
"data": {
"id": "1234",
"email": "foo@example.com"
}
}
You can then easily locate jobs using with a simple search:
$ curl https://api.6px.io/v1/users/:user_id/jobs?data.id=1234
When your job is complete a POST
will be sent to an optional callback URL. The POST
body will contain the full JSON payload from the processed job.
The input
array specifies the images that are to be used when processing the job. Input should be a publicly accessable URL or a valid data URI.
The following image formats are supported:
JPG
PNG
GIF
Specifies operations that are to be run against the images in the input
array. Multiple outputs can be achieved by providing additional objects.
Example:
{
"output": [
{
"methods": [
{
"method": "resize",
"options": {
"width": 200,
"height": 200
}
}
],
"type": "image/png",
"ref": {
"main": false
},
"url": "s3://key:secret@bucket/path"
},
{
"methods": [
{
"method": "filter",
"options": {
"color": 0
}
}
],
"type": "image/png",
"ref": {
"main": false
},
"url": "s3://key:secret@bucket/path"
}
]
}
Specifies what methods to run against that particular output.
Example:
{
"methods": [
{
"method": "resize",
"options": {
"height": 400,
"width": 400
}
},
{
"method": "filter",
"options": {
"color": 0
}
}
]
}
MIME type to save the image as.
The following MIME types are supported:
image/png
image/jpeg
image/gif
Specifies which input(s) to use. If we specify more than one ref in this block, it will duplicate whatever is in this block for each of the input indexes defined. If the value is set to false, a random filename will be generated.
For example, if we have the following input object containing 4 inputs:
{
"input": {
"img1": "http://example.com/path/to/image1.jpg",
"img2": "http://example.com/path/to/image2.jpg",
"img3": "http://example.com/path/to/image3.jpg",
"img4": "http://example.com/path/to/image4.jpg"
}
}
We could then specify that we want to use the 3rd input image like so:
{
"output": [
{
"methods": [
{
"method": "crop",
"options": {
"face": true,
"padding": 50
}
}
],
"ref": {
"img3": "image.png"
}
}
]
}
A full URL without the filename to which the output image(s) will be uploaded. If an output URL is not specified, your image(s) will automatically be uploaded and served from the 6px CDN.
The following output locations / connection strings are supported:
s3://key:secret@bucket/path
Amazon S3cf://username:api_key@container/path
Rackspace Cloud Files (US)cf+uk://username:api_key@container/path
Rackspace Cloud Files (UK)ftp://user:password@ftp.example.com/path
FTPsftp://user:password@sftp.example.com/path
SFTP
FTP / SFTP
If the URL contains authentication with special characters, make sure that they are properly escaped. We try to write from the root of your server, so use an absolute path for your URL to ensure that we can write to your server successfully.
Masked Connection Strings
If you're using a client side implementation or simply prefer to not expose your connection string, you can use a masked connection string. Every user document contains a
connection_string
object. This allows you to map a simple string (e.g.prod
) to your connection string (e.g.s3://key:secret@bucket/path
). Your masked connection strings can be specified in the dashboard.
{
"__v": 0,
"_id": "52e1f64007438cb08073d5e9",
"user_id": "52c747dc04f452f766000001",
"modified": "2014-04-16T21:21:36.544Z",
"created": "2014-04-16T21:20:54.403Z",
"processed": {
"duration": {
"start": "2014-04-16T21:20:54.474Z",
"upload": 19842,
"download": 8424,
"total": 41999,
"end": "2014-04-16T21:21:36.473Z"
},
"output": {
"bus": {
"info": {
"bytes": 88202,
"width": 250,
"height": 166
}
}
},
"bytes": 88202
},
"output": [
{
"methods": [
{
"method": "resize",
"options": {
"width": 250
}
},
{
"method": "filter",
"options": {
"sepia": 70,
"hue": 20
}
}
],
"url": "6px",
"type": "image/png",
"ref": {
"bus": false
}
}
],
"input": {
"bus": "http://666a658c624a3c03a6b2-25cda059d975d2f318c03e90bcf17c40.r92.cf1.rackcdn.com/unsplash_52d5c05422a47_1.JPG"
},
"status": "complete",
"data": {}
}
The output from a job contains all of the fields that were specified in the input, along with general database values and useful metrics.
Contains various information obtained while processing the image(s).
Benchmarks for various tasks for the job.
Value | Type | Description |
---|---|---|
start |
Datetime | The time shown as an ISO8601 Datetime that the job started processing. |
end |
Datetime | The time shown as an ISO8601 Datetime that the job completed processing. |
total |
Number | The total time in milliseconds taken to complete a job. The timer starts as soon as a job is received and stopps when the job is complete. If you are submitting a batch job, this will be the total time required to process all of the jobs combined. |
upload |
Number | The total time in milliseconds taken to upload all of the outputs in your job. |
download |
Number | The total time in milliseconds taken to download all of the images referenced in the inputs array. |
Outlines various useful data for each of the outputs.
Size of processed data in bytes. If you are submitting a batch job, this number will be the sum of all processed bytes.
Will be one of the following:
pending
Default status before job is picked up by workerprocessing
Worker has taken on the jobcomplete
Job is completefailed
Job has failed
Example Request:
$ curl -X POST -H "Content-Type: application/json" -d '{"output":[{"methods":[{"method": "resize","options":{"width":200,"height":200}}],"type":"image/png","ref":["main"]}],"input":{"hobbit":"http://0.tqn.com/d/scifi/1/0/n/1/1/-/HBT-008104r.jpg"}}' https://api.6px.io/v1/users/:user_id/jobs
Example Response:
{
"id": "52e1f64007438cb08073d5e8"
}
Example Request:
$ curl https://api.6px.io/v1/users/52c747dc04f452f766000001/jobs/52e1f64007438cb08073d5e8
Example Response:
{
"__v": 0,
"_id": "52e1f64007438cb08073d5e9",
"user_id": "52c747dc04f452f766000001",
"modified": "2014-04-16T21:21:36.544Z",
"created": "2014-04-16T21:20:54.403Z",
"processed": {
"duration": {
"start": "2014-04-16T21:20:54.474Z",
"upload": 19842,
"download": 8424,
"total": 41999,
"end": "2014-04-16T21:21:36.473Z"
},
"output": {
"bus": {
"info": {
"bytes": 88202,
"width": 250,
"height": 166
}
}
},
"bytes": 88202
},
"output": [
{
"methods": [
{
"method": "resize",
"options": {
"width": 250
}
},
{
"method": "filter",
"options": {
"sepia": 70,
"hue": 20
}
}
],
"url": "6px",
"type": "image/png",
"ref": {
"bus": false
}
}
],
"input": {
"bus": "http://666a658c624a3c03a6b2-25cda059d975d2f318c03e90bcf17c40.r92.cf1.rackcdn.com/unsplash_52d5c05422a47_1.JPG"
},
"status": "complete",
"data": {}
}
Example Request:
$ curl https://api.6px.io/v1/users/52c747dc04f452f766000001/jobs
Example Response:
[
{
"__v": 0,
"_id": "52e1f64007438cb08073d5e9",
"user_id": "52c747dc04f452f766000001",
"modified": "2014-04-16T21:21:36.544Z",
"created": "2014-04-16T21:20:54.403Z",
"processed": {
"duration": {
"start": "2014-04-16T21:20:54.474Z",
"upload": 19842,
"download": 8424,
"total": 41999,
"end": "2014-04-16T21:21:36.473Z"
},
"output": {
"bus": {
"info": {
"bytes": 88202,
"width": 250,
"height": 166
}
}
},
"bytes": 88202
},
"output": [
{
"methods": [
{
"method": "resize",
"options": {
"width": 250
}
},
{
"method": "filter",
"options": {
"sepia": 70,
"hue": 20
}
}
],
"url": "6px",
"type": "image/png",
"ref": {
"bus": false
}
}
],
"input": {
"bus": "http://666a658c624a3c03a6b2-25cda059d975d2f318c03e90bcf17c40.r92.cf1.rackcdn.com/unsplash_52d5c05422a47_1.JPG"
},
"status": "complete",
"data": {}
},
{
"__v": 0,
"_id": "534ef43674b502000000edd4",
"user_id": "5344f3842b89de102752424b",
"modified": "2014-04-16T21:21:36.544Z",
"created": "2014-04-16T21:20:54.403Z",
"processed": {
"duration": {
"start": "2014-04-16T21:20:54.474Z",
"upload": 19842,
"download": 8424,
"total": 41999,
"end": "2014-04-16T21:21:36.473Z"
},
"output": {
"farm": {
"info": {
"bytes": 16033211,
"width": 4608,
"height": 3456
}
},
"forest": {
"info": {
"bytes": 6814070,
"width": 2300,
"height": 1533
}
},
"bus": {
"info": {
"bytes": 88202,
"width": 250,
"height": 166
}
}
},
"bytes": 22935483
},
"output": [
{
"methods": [
{
"method": "resize",
"options": {
"width": 250
}
},
{
"method": "filter",
"options": {
"sepia": 70,
"hue": 20
}
}
],
"url": "6px",
"type": "image/png",
"ref": {
"bus": false,
"forest": false,
"farm": false
}
}
],
"input": {
"bus": "http://666a658c624a3c03a6b2-25cda059d975d2f318c03e90bcf17c40.r92.cf1.rackcdn.com/unsplash_52d5c05422a47_1.JPG",
"forest": "http://666a658c624a3c03a6b2-25cda059d975d2f318c03e90bcf17c40.r92.cf1.rackcdn.com/unsplash_52dbe5607f0db_1.JPG",
"farm": "http://666a658c624a3c03a6b2-25cda059d975d2f318c03e90bcf17c40.r92.cf1.rackcdn.com/unsplash_52d7cdd15b9a3_1.JPG"
},
"status": "complete",
"callback": {
"url": ""
},
"data": {}
}
]
Please let us how we can make this API better. If you have a specific feature request or found a bug, please drop us a line at ops@6px.io.