AWS S3

External Storage / AWS S3

On this page:
Intro ▾
{{activeSubMenu.text}} ▾

In order to use AWS S3 as your External Storage of choice, you must set the provider attribute to aws within the store hash and, at a minimum, provide your AWS credentials (key and secret) as well as a bucket name and the AWS region where your bucket is located. The full list of store hash attibutes for AWS S3 storage can be found below.

store hash attributes for AWS S3:
AttributeTypeRequiredDescription
providerStringYesprovider must be set to aws.
keyStringYesAWS Access Key Id.
secretStringYesAWS Secret Access Key.
bucketStringYesName of a destination bucket in your Amazon S3 account.
regionStringYesName of the AWS Region in which your S3 bucket is located.
pathStringNoDestination path in your S3 bucket (without leading slash). Defaults to root.
aclStringNoThe Access Control List of the destination object. Defaults to "public-read".
metadataHashNoCustom S3 Metadata you would like to set on your object.
headersHashNoCustom HTTP headers you would like to set on your object.
tagsHashNoCustom S3 Tags you would like to set on your object.

The Pixaven API allows you to set the following custom headers on your objects: Expires, Cache-Control, Content-Type, Content-Encoding, Content-Language and Content-Disposition.

{
    "store": {
        "provider": "aws",
        "key": "your-aws-key",
        "secret": "your-aws-secret",
        "bucket": "images",
        "region": "eu-central-1",
        "path": "assets/image.jpg",
        "acl": "public-read",
        "metadata": {
            "key": "value"
        },
        "headers": {
            "Cache-Control": "max-age=2592000000"
        },
        "tags": {
            "key": "value"
        }
    }
}

An example cURL request of using AWS S3 as External Storage provider will look like the following:

curl https://api.pixaven.com/1.0/fetch -X POST -u your-api-key: \
-H "Content-Type: application/json" \
-d '{
    "url": "https://www.website.com/image.jpg",
    "resize": {
        "width": 100,
        "height": 75
    },
    "store": {
        "provider": "aws",
        "key": "your-aws-key",
        "secret": "your-aws-secret",
        "bucket": "bucket-name",
        "region": "eu-central-1",
        "path": "assets/image.jpg",
        "headers": {
            "Cache-Control": "max-age=2592000000"
        }
    }
}'

When using AWS as your External Storage, the url property within the JSON response will point to the object’s location within the S3 bucket and you can safely use that URL in production, for example:

HTTP/1.1 200 OK

Date: {{now}}
Status: 200 OK
Content-Type: application/json

{
    "success": true,
    "code": 200,
    "id": "9fccf4b5-cfab-4e92-9276-5d2028fcb6a0",
    "input": {
        "name": "image.jpg",
        ..
    },
    "output": {
        "url": "https://bucket-name.s3.eu-central-1.amazonaws.com/assets/image.jpg",
        ..
    }
}

Custom Bucket Policies

If you would like to create an AWS User dedicated only for the Pixaven API or are using a custom bucket policy, please make sure to include s3:PutObject and s3:PutObjectAcl entries in the allowed actions section in your bucket policy file (and replace bucket-name in this example):

{
    "Statement": {
        "Effect": "Allow",
        "Action": [
            "s3:PutObject",
            "s3:PutObjectAcl"
        ],
        "Resource": [
            "arn:aws:s3:::bucket-name/*"
        ]
    }
}

Code Examples for AWS S3

Below, you'll find examples of how to use AWS S3 from the Pixaven API:

<?php

/**
* Instantiate new `$pix` by calling a constructor
*/

$pix = new Pixaven\Pixaven('your-api-key');


/**
* Provide a publicly available image URL with fetch(string) method,
* resize the image to 100 x 75 and store it in your S3 bucket
*/

$pix
    ->fetch('https://www.website.com/image.jpg')
    ->resize(array(
        'width' => 100,
        'height' => 75
    ))
    ->store(array(
        'provider' => 'aws',
        'key' => 'your-aws-key',
        'secret' => 'your-aws-secret',
        'bucket' => 'bucket-name',
        'region' => 'eu-central-1',
        'path' => 'assets/image.jpg',
        'headers' => array(
            'Cache-Control' => 'max-age=2592000000'
        )
    ))
    ->toJSON(function ($error, $meta) {
        if (!empty($error)) {
            throw new Exception($error);
        }

        /**
        * You'll find the full JSON metadata array within the `$meta` variable.
        * Remember to always check if the `success` property is set to `true`.
        */

        if ($meta['success'] == true) {
            print ($meta['output']['url']);
        } else {
            print ($meta['message']);
        }
    });
/**
* Module dependencies
*/

const Pixaven = require("pixaven");


/**
* Instantiate new `pix` by calling a constructor
*/

const pix = new Pixaven("your-api-key");


/**
* Provide a publicly available image URL with fetch(string) method,
* resize the image to 100 x 75 and store it in your S3 bucket
*/

pix
    .fetch("https://www.website.com/image.jpg")
    .resize({
        width: 100,
        height: 75
    })
    .store({
        provider: "aws",
        key: "your-aws-key",
        secret: "your-aws-secret",
        bucket: "bucket-name",
        region: "eu-central-1",
        path: "assets/image.jpg",
        headers: {
            "Cache-Control": "max-age=2592000000"
        }
    })
    .toJSON((err, meta) => {
        if (err) {
            return console.log(err);
        }

        /**
        * You'll find the full JSON metadata hash within the `meta` variable.
        * Remember to always check if the `success` property is set to `true`.
        */

        if (meta.success) {
            console.log(meta.output.url);
        } else {
            console.log(meta.message);
        }
    });
##
# Require dependencies

require "pixaven"


##
# Instantiate new `pix` by calling a constructor

pix = Pixaven.new("your-api-key")


##
# Provide a publicly available image URL with fetch(string) method,
# resize the image to 100 x 75 and store it in your S3 bucket

err, meta = pix
    .fetch("https://www.website.com/image.jpg")
    .resize(
        width: 100,
        height: 75
    )
    .store(
        provider: "aws",
        key: "your-aws-key",
        secret: "your-aws-secret",
        bucket: "bucket-name",
        region: "eu-central-1",
        path: "assets/image.jpg",
        headers: (
            "Cache-Control": "max-age=2592000000"
        )
    )
    .to_json

abort(err) if err


##
# You'll find the full JSON metadata hash within the `meta` variable.
# Remember to always check if the `success` property is set to `true`.

if meta["success"]
    puts meta["output"]["url"]
else
    puts meta["message"]
end
package main

import (
    "fmt"
    "github.com/pixaven/pixaven-go"
)

func main() {

    /**
    * Instantiate new `pix` by calling a constructor
    */

    pix, err := pixaven.NewClient("your-api-key")

    if err != nil {
        panic(err)
    }


    /**
    * Provide a publicly available image URL with Fetch(string) method,
    * resize the image to 100 x 75 and store it in your S3 bucket
    */

    meta, err := pix.
        Fetch("https://www.website.com/image.jpg").
        Resize(pixaven.P{
            "width": 100,
            "height": 75
        }).
        Store(pixaven.P{
            "provider": "aws",
            "key": "your-aws-key",
            "secret": "your-aws-secret",
            "bucket": "bucket-name",
            "region": "eu-central-1",
            "path": "assets/image.jpg",
            "headers": pixaven.P{
                "Cache-Control": "max-age=2592000000"
            }
        }).
        ToJSON()

    if err != nil {
        panic(err)
    }


    /**
    * You'll find the full JSON metadata hash within the `meta` variable.
    * Remember to always check if the `success` property is set to `true`.
    */

    if meta["success"].(map[string]interface{})["success"].(bool) {
        fmt.Println(meta["output"].(map[string]interface{})["url"])
    } else {
        fmt.Println(meta["message"])
    }
}
##
# Import dependencies

from pixaven import pixaven


##
# Instantiate new `client` by calling a constructor

client = pixaven('your-api-key')


##
# Provide a publicly available image URL with fetch(string) method,
# resize the image to 100 x 75 and store it in your S3 bucket

err, meta = (
    client
        .fetch('https://www.website.com/image.jpg')
        .resize({
            'width': 100,
            'height': 75
        })
        .store({
            'provider': 'aws',
            'key': 'your-aws-key',
            'secret': 'your-aws-secret',
            'bucket': 'bucket-name',
            'region': 'eu-central-1',
            'path': 'assets/image.jpg',
            'headers': {
                'Cache-Control': 'max-age=2592000000'
            }
        })
        .toJSON()
)

if err is not None:
    raise StandardError(err)


##
# You'll find the full JSON metadata hash within the `meta` variable.
# Remember to always check if the `success` property is set to `true`.

if meta['success'] is True:
    print (meta['output']['url'])
else:
    print (meta['message'])
package com.pixaven.examples;

/**
* Import dependencies
*/

import static com.pixaven.OperationConfiguration.settings;
import com.pixaven.Pixaven;
import com.pixaven.Fetch;
import com.pixaven.Response;

public class StorageS3 {
    public static void main(String[] args) {

        /**
        * Instantiate new `pix` by calling a constructor
        */

        Pixaven pix = new Pixaven("your-api-key");

        /**
        * Provide a publicly available image URL with fetch(string) method,
        * resize the image to 100 x 75 and store it in your S3 bucket
        */

        final Fetch fetch = pix.fetch("https://www.website.com/image.jpg");

        fetch.resize(
            settings()
                .set("width", 100)
                .set("height", 75)
        );

        fetch.store(
            settings()
                .set("provider", "aws")
                .set("key", "your-aws-key")
                .set("secret", "your-aws-secret")
                .set("bucket", "bucket-name")
                .set("region", "eu-central-1")
                .set("path", "assets/image.jpg")
                .set("headers", settings()
                    .set("Cache-Control", "max-age=2592000000")
                    .set("Expire", "2026-04-04T12:06:11+00:00")
                )
        );

        final Response response = fetch.toJson();

        /**
        * You'll find the full JSON metadata hash within the `Response#getMetadata()` variable.
        * Remember to always check if the `Response#successful` property is set to `true`.
        */

        if (response.isSuccessful()) {
            System.out.println(response.getMetadata().getOutput().get("url"));
        } else {
            System.out.println(response.getMessage());
        }
    }
}

We use both proprietary and third-party cookies to improve your browsing experience and to provide you with a better service. By continuing to use this site you consent our use of cookies as described in our Cookie Policy×