API documentation

Coconut's API is a config-based API built with simplicity and flexibility in mind.
Encode your first video in less than 5 minutes.

API Reference

Storage

This is the storage service where you want your converted files to be uploaded.

Here are the supported storage services:

Coconut Storage (TEST)

Perfect if you want to test Coconut without having a Storage provider or CDN. Note that you can't use it for production, the files are deleted within 24 hours.

{
  "storage": {
    "service": "coconut"
  }
}

AWS S3

Example for AWS S3 storage:

{
  "storage": {
    "service": "s3",
    "region": "us-east-1",
    "bucket": "mybucket",
    "credentials": {
      "access_key_id": "...",
      "secret_access_key": "..."
    }
  }
}

Options

NameTypeDefaultRequired
service
Service must be s3.
string s3 Yes
credentials
Keys to authenticate against AWS S3.
hash Yes
access_key_id
The AWS Access Key Id.
string Yes
secret_access_key
The AWS Secret Access Key.
string Yes
bucket
The bucket where you want the files to be uploaded. The bucket must exist.
string Yes
region
The bucket region. By default, we find the right region automatically.
Supported regions are: us-east-2 us-east-1 us-west-1 us-west-2 af-south-1 ap-east-1 ap-south-1 ap-northeast-3 ap-northeast-2 ap-southeast-1 ap-southeast-2 ap-northeast-1 ca-central-1 cn-north-1 cn-northwest-1 eu-central-1 eu-west-1 eu-west-2 eu-south-1 eu-west-3 eu-north-1.
string Yes
path
The absolute path where you want the files to be uploaded.
string / No
secure
Returns an HTTPS URL if true.
bool false No
acl
supported acl: private public-read public-read-write authenticated-read aws-exec-read bucket-owner-read bucket-owner-full-control
string public-read No
storage_class
supported storage class: STANDARD REDUCED_REDUNDANCY STANDARD_IA ONEZONE_IA INTELLIGENT_TIERING GLACIER DEEP_ARCHIVE
string STANDARD No
expires
string No
cache_control
string No


AWS S3 Bucket Policy

When using AWS S3, you must setup a bucket policy so that we have the permissions to upload. Here is a policy that you can use. Don't forget to replace BUCKET by your actual bucket name.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "VisualEditor0",
      "Effect": "Allow",
      "Action": ["s3:PutObject", "s3:GetObject", "s3:ListBucket", "s3:GetBucketLocation", "s3:PutObjectAcl", "s3:GetBucketAcl", "s3:GetObjectAcl"],
      "Resource": ["arn:aws:s3:::BUCKET", "arn:aws:s3:::BUCKET/*"]
    }
  ]
}

Google Cloud Storage

Example for Google Cloud Storage storage:

{
  "storage": {
    "service": "gcs",
    "bucket": "mybucket",
    "credentials": {
      "access_key_id": "...",
      "secret_access_key": "..."
    }
  }
}

To use Google Cloud Storage with Coconut, you will need to follow this simple guide here.

Note that Uniform bucket level access is not supported. You must use Fine-grained instead.

Options

NameTypeDefaultRequired
service
Service must be gcs.
string gcs Yes
credentials
Keys to authenticate.
hash Yes
access_key_id
The Access Key Id.
string Yes
secret_access_key
The Secret Access Key.
string Yes
bucket
The bucket where you want the files to be uploaded. The bucket must exist.
string Yes
path
The absolute path where you want the files to be uploaded.
string / No
acl
supported acl: private public-read public-read-write authenticated-read aws-exec-read bucket-owner-read bucket-owner-full-control
string public-read No

DO Spaces

Example for DO Spaces storage:

{
  "storage": {
    "service": "dospaces",
    "bucket": "mybucket",
    "region": "fra1",
    "credentials": {
      "access_key_id": "...",
      "secret_access_key": "..."
    }
  }
}

Options

NameTypeDefaultRequired
service
Service must be dospaces.
string dospaces Yes
credentials
Keys to authenticate.
hash Yes
access_key_id
The Access Key Id.
string Yes
secret_access_key
The Secret Access Key.
string Yes
bucket
The bucket where you want the files to be uploaded. The bucket must exist.
string Yes
path
The absolute path where you want the files to be uploaded.
string / No
region
The bucket region.
Supported regions are: nyc3 sfo2 sgp1 fra1.
string nyc3 No
acl
supported acl: private public-read
string public-read No

Linode

Example for Linode storage:

{
  "storage": {
    "service": "linode",
    "bucket": "mybucket",
    "region": "us-east-1",
    "credentials": {
      "access_key_id": "...",
      "secret_access_key": "..."
    }
  }
}

Options

NameTypeDefaultRequired
service
Service must be linode.
string linode Yes
credentials
Keys to authenticate.
hash Yes
access_key_id
The Access Key Id.
string Yes
secret_access_key
The Secret Access Key.
string Yes
bucket
The bucket where you want the files to be uploaded. The bucket must exist.
string Yes
region
The bucket region.
Supported regions are: us-east-1 us-east-2 eu-central-1
string Yes
path
The absolute path where you want the files to be uploaded.
string / No
acl
supported acl: private public-read
string public-read No

Wasabi

Example for Wasabi storage:

{
  "storage": {
    "service": "wasabi",
    "bucket": "mybucket",
    "region": "us-east-1",
    "credentials": {
      "access_key_id": "...",
      "secret_access_key": "..."
    }
  }
}

Options

NameTypeDefaultRequired
service
Service must be wasabi.
string wasabi Yes
credentials
Keys to authenticate.
hash Yes
access_key_id
The Access Key Id.
string Yes
secret_access_key
The Secret Access Key.
string Yes
bucket
The bucket where you want the files to be uploaded. The bucket must exist.
string Yes
region
The bucket region.
Supported regions are: us-east-1 us-east-2 us-west-1 eu-central-1
string Yes
path
The absolute path where you want the files to be uploaded.
string / No
acl
supported acl: private public-read
string public-read No

Any S3 compatible services

Example for an S3 compatible service storage:

{
  "storage": {
    "service": "s3other",
    "bucket": "mybucket",
    "credentials": {
      "access_key_id": "...",
      "secret_access_key": "..."
    },
    "endpoint": "https://compatibles3service.com/api/"
  }
}

Options

NameTypeDefaultRequired
service
Service must be s3other.
string s3other Yes
credentials
Keys to authenticate.
hash Yes
access_key_id
The Access Key Id.
string Yes
secret_access_key
The Secret Access Key.
string Yes
bucket
The bucket where you want the files to be uploaded. The bucket must exist.
string Yes
path
The absolute path where you want the files to be uploaded.
string / No
endpoint
The API endpoint (full URL) pointing to the S3 compatible service API.
string Yes
force_path_style
Some service requires Force Path Style to be true.
boolean false No

Backblaze

Example for backblaze storage:

{
  "storage": {
    "service": "backblaze",
    "bucket_id": "mybucketId",
    "credentials": {
      "app_key_id": "...",
      "app_key": "..."
    }
  }
}

Options

NameTypeDefaultRequired
service
Service must be backblaze.
string backblaze Yes
credentials
Keys to authenticate.
hash Yes
account_id
The Account Id.
If you have generated a specific key for an App, you should use app_key_id to authenticate instead.
string Yes
app_key_id
The App Key Id.
string Yes
app_key
The App Key.
string Yes
bucket_id
The bucket Id where you want the files to be uploaded. The bucket must exist.
string Yes
path
The absolute path where you want the files to be uploaded.
string / No

Rackspace

Example for Rackspace storage:

{
  "storage": {
    "service": "rackspace",
    "container": "mycontainer",
    "credentials": {
      "username": "...",
      "api_key": "..."
    }
  }
}

Options

NameTypeDefaultRequired
service
Service must be rackspace.
string rackspace Yes
credentials
Keys to authenticate.
hash Yes
username
The Username.
string Yes
api_key
The API Key.
string Yes
container
The Container where you want the files to be uploaded. The container must exist.
string Yes
path
The absolute path where you want the files to be uploaded.
string / No
region
The container region.
Supported regions are: ORD DFW HKG LON IAD SYD
string No

Microsoft Azure

Example for Azure storage:

{
  "storage": {
    "service": "azure",
    "container": "mycontainer",
    "credentials": {
      "account": "...",
      "access_key": "..."
    }
  }
}

Options

NameTypeDefaultRequired
service
Service must be azure.
string azure Yes
credentials
Keys to authenticate.
hash Yes
account
The Account.
string Yes
api_key
The Access Key.
string Yes
container
The Container where you want the files to be uploaded. The container must exist.
string Yes
path
The absolute path where you want the files to be uploaded.
string / No

FTP, SFTP and HTTP protocols

We support FTP, SFTP and HTTP servers if you want to use your own server to receive the files.

Example for HTTP:

{
  "storage": {
    "url": "https://myserver.com/api/coconut"
  }
}

Another example for FTP server:

{
  "storage": {
    "url": "ftp://username:passwd@myserver.com/path/"
  }
}