Getting Started

The bitcodin API

The bitocdin REST API enables you to interact directly with the bitcodin cloud-transcoding platform from anywhere where you can send an HTTP request. This comes along with the possibility to integrate bitcodin directly into your application, web portal, media workflows, etc. and fully automate your transcoding process.

bitcodin also provides a wide range of API clients for the most common programming languages and platforms. These clients are a wrapper on top of our REST API to ease development and help out customers to integrate bitcodin with lowest efforts.

Request Format

Requests to the bitcodin API have to be send to the following endpoint: http://api.bitcodin.com

GET requests have their parameter in the URL. For POST and PUT requests, the request body must be JSON, with the Content-Type header set to application/json.

Authentication is done via HTTP headers. The bitcodin-api-key header authenticates the endpoint, you just have to use your bitcodin API key. You can find your API key in the bitcodin portal at http://portal.bitcodin.com in your account settings as shown in the figure:

Secure communication using HTTPs is possible. API requests can also select a specific API version using the bitcodin-api-version header. Here you can see a header example:

Content-Type: application/json
bitcodin-api-version: v1
bitcodin-api-key: yoursuperfancyencryptedapikey

For Javascript usage, bitcodin supports cross-origin resource sharing (CORS), so that users can use these headers in conjunction with XMLHttpRequest.

Response Header

The response format for all requests is a JSON object.

Whether a request succeeded is indicated by the HTTP status code. A 2xx status code indicates success, whereas a 4xx status code indicates failure. When a request fails, the response body is still JSON, but always contains information which you can use for debugging.

Basic API Example

In the following you can see an sample request to add an new input file to bitcodin. This is a POST request, containing the JSON with the URL to the input video:

Header

Content-Type: application/json
bitcodin-api-version: v1
bitcodin-api-key: yoursuperfancyencryptedapikey

Body

{ 
    "type": "url",
    "url": "http://www.example.com/yourfolder/yourmovie.mp4"
}

Once this request is send, bitcodin will add this input video to your account, and you can also see it in the web interface at http://portal.bitcodin.com. bitcodin will respond to the API request with the details on the newly created input, e.g.:

Header

Content-Type: application/json

Body

{
    "inputId": 3,
    "filename": "yourmovie.mp4",
    "createdAt": {
        "date": "11.03.2015 16:41:00",
        "timezone": {
            "timezone_type": 3,
            "timezone": "Europe/Berlin"
        }
    },
    "updatedAt": {
        "date": "11.03.2015 16:41:00",
        "timezone": {
            "timezone_type": 3,
            "timezone": "Europe/Berlin"
        }
    },
    "thumbnailUrl": "http://www.example.com/yourfolder/yourmovie_thumb.png",
    "inputType": "url",
    "url": "http://www.example.com/yourfolder/yourmovie.mp4",
    "basicAuthUser": "",
    "basicAuthPassword": "",
    "mediaConfigurations": [
        {
            "streamId": 0,
            "duration": 0,
            "rate": 24,
            "codec": "h264",
            "type": "video",
            "bitrate": 0,
            "width": 1280,
            "height": 544,
            "pixelFormat": "yuv420p"
        },
        {
            "streamId": 1,
            "duration": 0,
            "rate": 48000,
            "codec": "ac3",
            "type": "audio",
            "bitrate": 640000,
            "sampleFormat": 6,
            "channelFormat": 5.1
        }
    ]
}