Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Build Status Coverage Status

An Elixir library for interacting with the Zencoder API.

Requires Elixir ~> 1.0.0


Install the package

  1. Add zencoder and ibrowse to your mix.exs dependencies:

    def deps do
        {:zencoder, "~> 1.0.1"},
        {:ibrowse, github: "cmullaparthi/ibrowse", tag: "v4.1.0"},
  2. Add :zencoder to your application dependencies:

    def application do
      [applications: [:zencoder]]


To communicate with the Zencoder API you'll need to provide your API key, you can find your API key by logging into your Zencoder account and visiting

There are three ways to provide your API key to the Elixir library:

  1. Set it from within your application

    Zencoder.api_key "your-api-key"
  2. Set it as the environment variable ZENCODER_API_KEY

    ZENCODER_API_KEY=your-api-key iex -S mix
  3. Every request takes a map as its final argument, you may provide your API key there

    Zencoder.Job.progress(12345, %{api_key: "your-api-key"})

Base URL

By default the integration library will send all requests to version 2 of our API: "". If, for whatever reason, you want to send requests to a different url you may configure your base URL in two ways:

  1. Set it from within your application

    Zencoder.base_url ""
  2. Set it as the environment variable ZENCODER_BASE_URL

    ZENCODER_BASE_URL= iex -S mix


We recommend wrapping your requests to Zencoder in a 30 second timeout. Zencoder usually responds in less than a second, so 30 seconds should give it plenty of time to respond. If the timeout is exceeded your request will return a %Zencoder.Error{} struct. If you wish to customize the length of the timeout you can do so by setting the timeout (in milliseconds) in three ways:

  1. Setting it from within your application

    Zencoder.timeout 60000
  2. Set it as the environment variable ZENCODER_TIMEOUT

    ZENCODER_TIMEOUT=60000 iex -S mix
  3. Every request takes a map as its final argument, you may provide your custom timeout there

    Zencoder.Job.progress(12345, %{timeout: 60000})


All API request functions will return either a %Zencoder.Response{} struct (which may or may not be successful) or a %Zencoder.Error{} struct if an exception occurred.


A Zencoder response has the following fields:

  1. body: A Map containing the parsed body of the response, or an empty map if the response body could not be parsed
  2. success?: true or false depending on if the request was successful
  3. code: The HTTP status code of the response
  4. headers: The response headers
  5. raw_body: The raw string of the response body. (Likely JSON or an empty string)
  6. errors: An List of errors, or an empty List. This is a shortcut for response.body[:errors]


A Zencoder error has the following fields:

  1. stacktrace: The formatted exception
  2. kind: The type of error
  3. error: The exception

Stacktrace is the formatted exception (via Exception.format/2). The kind and error are provided if you wish to do your own formatting.

Pattern Matching

You can pattern match to determine how to handle the response:

case Zencoder.Job.create %{test: true, input: ""} do
  %Zencoder.Response{success?: true} = response ->
    # some happy path stuff here
  %Zencoder.Response{success?: false} = response ->
    # uh oh, maybe something is wrong with your request?
    # better check the docs at
  %Zencoder.Error{} = response ->
    # timed out? Zencoder broken? Computers are hard! Perhaps some nice retry logic.
    # Check out our integration reliability guide:


Create a new job.

# Basic job
Zencoder.Job.create(%{input: ""})

# More extensive job, see for more encoding settings
  input: "s3://zencodertesting/",
  outputs: [
      label: "mp4 high",
      url: "s3://your-bucket/output-file-name.mp4",
      h264_profile: "high"
      url: "s3://your-bucket/output-file-name.webm",
      label: "webm",
      format: "webm"
      url: "s3://your-bucket/output-file-name.ogg",
      label: "ogg",
      format: "ogg"
      url: "s3://your-bucket/output-file-name-mobile.mp4",
      label: "mp4 low",
      size: "640x480"

Get details about a job.


Get progress on a job.


List jobs. By default this returns the last 50 jobs, but this can be altered in an optional Map.

Zencoder.Job.list(%{page: 1, per_page: 5, state: "finished"})

Cancel a job


Resubmit a job



Get details about an input.


Get progress for an input.



Get details about an output.


Get progress for an output.



Reports are great for getting usage data for your account. All default to 30 days from yesterday with no grouping, but this can be altered in the optional Map. These will return 422 Unprocessable Entity if the date format is incorrect or the range is greater than 2 months. Correct date format is YYYY-MM-DD.

Get all usage (Live + VOD).


# For a specific date range
Zencoder.Report.all %{from: "2013-05-01", to: "2013-06-01"}

# For a specific grouping
Zencoder.Report.all %{grouping: "aperture-testing"}

Get VOD usage.


# For a specific date range
Zencoder.Report.vod %{from: "2013-05-01", to: "2013-06-01"}

# For a specific grouping
Zencoder.Report.vod %{grouping: "aperture-testing"}

Get Live usage.

# For a specific date range %{from: "2013-05-01", to: "2013-06-01"}

# For a specific grouping %{grouping: "aperture-testing"}


Create a new account. A unique email address and terms of service are required, but you can also specify a password (and confirmation) along with whether or not you want to subscribe to the Zencoder newsletter. New accounts will be created under the Test (Free) plan.

Zencoder.Account.create %{email: "", terms_of_service: 1}

# Create an account with all possible options
Zencoder.Account.create %{
  email: "",
  terms_of_service: 1,
  password: "sureamgladforssl",
  password_confirmation: "sureamgladforssl",
  newsletter: 0

Get details about the current account.


Turn integration mode on (all jobs are test jobs).


Turn off integration mode, which means your account is live (and you'll be billed for jobs).


Elixir integration library for Zencoder




No packages published

Contributors 4