Upload API

Following APIs are available for uploading assets to PixelBin:

1. Signed Multipart Upload
2. File Upload
3. Url Upload
4. Signed Url Upload

Limits

When uploading assets to Pixelbin, certain restrictions apply. Learn More

Signed Multipart Upload

Signed Multipart Upload is the recommended method to upload assets. It enables faster and reliable uploads over slow networks.

There are 3 steps involved in signed multipart upload:

1. Generate a signed multipart upload url.

To upload assets, you need a presigned upload url. You can use PixelBin's Backend SDKs or PixelBin APIs to generate a presigned upload url.

Curl

curl --request POST 'https://api.pixelbin.io/service/platform/assets/v2.0/upload/signed-url' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: <REFER-AUTH-API-TOKEN-IN-INTRODUCTION>' \
--header 'x-ebg-param: <REFER-PIXELBIN-SIGNATURE-GENERATION>' \
--header 'x-ebg-signature: <REFER-PIXELBIN-SIGNATURE-GENERATION>' \
--data-raw '{ "name": "asset", "expiry": 3000 }'

Node.js

const { PixelbinConfig, PixelbinClient } = require("@pixelbin/admin");

// Create a config with you API_TOKEN
const config = new PixelbinConfig({
    domain: "https://api.pixelbin.io",
    apiSecret: "API_TOKEN",
});

// Create a pixelbin instance
const pixelbin = new PixelbinClient(config);

const response = await pixelbin.assets.createSignedUrlV2({
    name: "filename",
    path: "folder1",
    format: "jpeg",
    tags: ["tag1", "tag2"],
    metadata: {},
    overwrite: false,
    filenameOverride: true,
    expiry: 3000,
});

Python

import asyncio
from pixelbin import PixelbinClient, PixelbinConfig

config = PixelbinConfig({
    "domain": "https://api.pixelbin.io",
    "apiSecret": "API_TOKEN",
})

pixelbin:PixelbinClient = PixelbinClient(config=config)

try:
    result = asyncio.run(pixelbin.assets.createSignedUrlV2Async(
        name="filename",
        path="folder1",
        format="jpeg",
        tags=["tag1","tag2"],
        metadata={},
        overwrite=False,
        filenameOverride=True,
        expiry=3000))
    # use result
except Exception as e:
    print(e)

Golang

import (
    "fmt"
    "os"
    "github.com/pixelbin-io/pixelbin-go/v3/sdk/platform"
)

func main() {
    // create pixelbin config object
    config := platform.NewPixelbinConfig(
        "API_TOKEN",
        "https://api.pixelbin.io",
    )
    // set oauthclient
    config.SetOAuthClient()

    // create pixelbin client object
    pixelbin := platform.NewPixelbinClient(config)

    // Parameters for FileUpload function
    params := platform.CreateSignedUrlV2XQuery{
        Name: "filename",
        Path: "folder1",
        Format: "jpeg",
        Tags: []string{"tag1","tag2"},
        Metadata: map[string]interface{}{},
        Overwrite: false,
        FilenameOverride: true,
        Expiry: 3000,
    }
    result, err := pixelbin.Assets.CreateSignedUrlV2(params)

    if err != nil {
        fmt.Println(err)
    }
    // use result
    fmt.Println(result)
}

PHP

<?php

use PixelbinPlatformPixelbinClient;
use PixelbinPlatformPixelbinConfig;

$config = new PixelbinConfig([
    "domain" => "https://api.pixelbin.io",
    "apiSecret" => "API_TOKEN",
])

$pixelbin = new PixelbinClient(config: $config)

// Async method call
try {
    $result = $pixelbin->assets->createSignedUrlV2Async(
        name: "filename",
        path: "path/to/containing/folder",
        format: "jpeg",
        access: AccessEnum::PUBLIC_READ,
        tags: ["tag1","tag2"],
        metadata: {},
        overwrite: false,
        filenameOverride: true,
        expiry: 3000
    );
    // use result
    print_r($result);
} catch (Exception $e) {
    print_r($e->getMessage());
}

Required Headers

All requests to PixelBin should contain the Pixelbin Signature

Request Body Schema

• Content-Type: application/json.
• Body:
  • path: Path where the uploaded asset would be stored on PixelBin Storage.
  • name: Name for the file to be uploaded
  • tags: Array<String>. Tags to be associated with the asset
  • metadata: Object. Metadata to be stored with the asset
  • overwrite: Boolean. If true, overwrites if file exists with the same name.
  • filenameOverride: Boolean. If true, appends the name if filename already exists.
  • expiry: Integer. Expiry in seconds for the generated upload url. Max 3600 seconds.

Response

200

On SUCCESS, api responds with an presignedUrl object. It has two parts, url and fields. presignedUrl object can be used for uploading directly to the Pixelbin Storage directly from the frontend using PixelBin's frontend SDKs.

JSON

{
    "presignedUrl": {
        "url": "https://api.pixelbin.io/service/public/assets/v1.0/signed-multipart?pbs=<SIGNATURE>&pbe=<EXPIRY>&pbt=<TOKEN-ACCESS-KEY>&pbo=<ORG-ID>&pbu=<UPLOAD-ID>",
        "fields": {
            "x-pixb-meta-assetdata": "{\"orgId\":3310,\"type\":\"file\",\"name\":\"filename666666.jpeg\",\"path\":\"\",\"fileId\":\"filename666666.jpeg\",\"format\":\"jpeg\",\"s3Bucket\":\"<bucket>\",\"s3Key\":\"uploads/small-queen-e8fa44/original/432758b0-0599-4442-b05f-f79217d1a1d8.jpeg\",\"access\":\"public-read\",\"tags\":[],\"metadata\":{\"source\":\"signedUrl\"},\"overwrite\":false,\"filenameOverride\":false,\"publicUploadId\":\"bc1abf17-fdbe-40a4-a63f-7c8882375afa\"}"

        }
    }
}

400

Bad Request, api responds with the reason for rejection.

2. Upload Parts using presignedUrl object

To upload, we need to split the file to be uploaded into parts(chunks).

Once the parts are generated, each part can be uploaded as follows:

info

Note:

• The presignedUrl has two fields - url and fields. Both fields are required to upload parts.
• Part numbers are 1 indexed
• Part numbers can range from 1 to 10,000 only

1. For each part, add a query parameter partNumber to the url provided in the presignedUrl object generated in step 1. For Example, to upload the first part, the partNumber is 1 and the generated url would be:

    https://api.pixelbin.io/service/public/assets/v1.0/signed-multipart?pbs=<SIGNATURE>&pbe=<EXPIRY>&pbt=<TOKEN-ACCESS-KEY>&pbo=<ORG-ID>&pbu=<UPLOAD-ID>&partNumber=1

2. Make a PUT request to the generated url.

3. Parts can be uploaded in parallel.

Request Body Schema

• Content-Type: multi-part/form-data
• Body:
  • x-pixb-meta-assetdata: String. This is received in the fields property of the presignedUrl
  • file: Binary. The file chunk to be uploaded.

Response

204

On SUCCESS, api responds with 204.

400

Bad Request, api responds with the reason for rejection.

3. Completion Request

1. After uploading all parts, make a POST request to the url provided in presignedUrl object with the following body.

Request Body Schema

• Content-Type: application/json
• Body:
  • x-pixb-meta-assetdata: String. This is received in the fields property of the presignedUrl
  • parts: Array<Number>. The list of part numbers to be merged. Part numbers should be in ascending order and should range from 1 to 10,000.

Response

200

On success, the api responds with HTTP status 200.

Response Body:

• Content-Type: application/json
• Body:
  • orgId: organization id.
  • type: Can be file or folder.
  • name: Name of the asset on PixelBin.
  • path: Path to the folder containing asset on PixelBin storage.
  • fileId: Relative path of the asset on PixelBin storage. This is path+name.
  • tags: Array of tags added to the asset.
  • format: Format of the asset.
  • size: Size of the asset in bytes
  • width: width of the asset in pixels if its an image
  • height: Height of the asset in pixels if its an image
  • context: The context for the asset.
  • _id: Id of the asset.
  • url: public PixelBin url for the asset.

File Upload API

caution

Deprecated! Signed Multipart Upload is the recommended method for uploading assets to PixelBin.

The following endpoint provides file upload functionality.

Curl

curl --request POST "https://api.pixelbin.io/service/platform/assets/v1.0/upload/direct" \
--header 'Content-Type: multipart/form-data' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer BASE_64_ENCODED_API_TOKEN' \
--header 'x-ebg-param: <REFER-PIXELBIN-SIGNATURE-GENERATION>' \
--header 'x-ebg-signature: <REFER-PIXELBIN-SIGNATURE-GENERATION>' \
--form 'file=@"/Path/to/file.jpeg"'

Required Headers

All requests should contain the Authentication Signature

Request Body Schema

The body should be of type multipart/form-data.

1. file: FileReadStream
2. path: Path to upload folder on Pixelbin
3. name: Name for the file to be uploaded
4. tags: Array. Tags to be associated with the asset
5. metadata: Object. Metadata to be stored with the asset
6. overwrite: Boolean. If true, overwrites if file exists with the same name.
7. filenameOverride: Boolean. If true, appends the name if filename already exists.

Response

200

On SUCCESS, api responds with details of the created file.

400

Bad Request, api responds with the reason for rejection.

Url Upload API

The following endpoint provides file upload functionality.

Curl

curl --request POST 'https://api.pixelbin.io/service/platform/assets/v1.0/upload/url' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: <REFER-AUTH-API-TOKEN-IN-INTRODUCTION>' \
--header 'x-ebg-param: <REFER-PIXELBIN-SIGNATURE-GENERATION>' \
--header 'x-ebg-signature: <REFER-PIXELBIN-SIGNATURE-GENERATION>' \
--data-raw '{ "url": "https://cdn.pixelbin.io/v2/old-scene-ccdc01/original/2-Figure2-1-(1)-transformed.webp", "filenameOverride": true}'

Required Headers

All requests to Pixelbin should contain the Pixelbin Signature

Request Body Schema

The body should be of type application/json.

1. url: String. url of the asset to be uploaded.
2. path: Path to upload folder on Pixelbin
3. name: Name for the file to be uploaded
4. tags: Array. Tags to be associated with the asset
5. metadata: Object. Metadata to be stored with the asset
6. overwrite: Boolean. If true, overwrites if file exists with the same name.
7. filenameOverride: Boolean. If true, appends the name if filename already exists.

Response

200

On SUCCESS, api responds with details of the created file.

400

Bad Request, api responds with the reason for rejection.

Signed Url Upload API

caution

Deprecated! Signed Multipart Upload is the recommended method for uploading assets to PixelBin.

The following endpoint provides file upload functionality.

Curl

curl --request POST 'https://api.pixelbin.io/service/platform/assets/v1.0/upload/signed-url' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: <REFER-AUTH-API-TOKEN-IN-INTRODUCTION>' \
--header 'x-ebg-param: <REFER-PIXELBIN-SIGNATURE-GENERATION>' \
--header 'x-ebg-signature: <REFER-PIXELBIN-SIGNATURE-GENERATION>' \
--data-raw '{ "name": "asset"}'

Required Headers

All requests to Pixelbin should contain the Pixelbin Signature

Request Body Schema

The body should be of type application/json.

1. path: Path to upload folder on Pixelbin
2. name: Name for the file to be uploaded
3. tags: Array. Tags to be associated with the asset
4. metadata: Object. Metadata to be stored with the asset
5. overwrite: Boolean. If true, overwrites if file exists with the same name.
6. filenameOverride: Boolean. If true, appends the name if filename already exists.

Response

200

On SUCCESS, api responds with an s3PresignedUrl object. It has two parts, url and fields. s3PresignedUrl object can be used for uploading directly to the Pixelbin Storage directly from the frontend.

A POST request can be used with this url with a FormData Body. The first field has to be the File Object to be uploaded. Add the entries in the fields object in the same order to the Body.

400

Bad Request, api responds with the reason for rejection.