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

Metadata API

This API is available since API Version: 2019-06-13

The metadata API will give you all the specs and info about a media file (source and output files).

Note that you can also get the metadata via webhook (option=metadata).

Get all metadata from a given job

Endpoint: GET /v1/metadata/jobs/:jobid

curl -u "your-api-key:" https://api.coconut.co/v1/metadata/jobs/18370773

Response examples

{
  "metadata": {
    "mp4:720p": {
      "streams": [
        {
          "index": 0,
          "codec_name": "h264",
          "codec_long_name": "H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10",
          "profile": "Constrained Baseline",
          "codec_type": "video",
          "codec_time_base": "1/60",
          "codec_tag_string": "avc1",
          "codec_tag": "0x31637661",
          "width": 1280,
          "height": 720,
          "coded_width": 1280,
          "coded_height": 720,
          "has_b_frames": 0,
          "sample_aspect_ratio": "1:1",
          "display_aspect_ratio": "16:9",
          "pix_fmt": "yuv420p",
          "level": 30,
          "chroma_location": "left",
          "refs": 1,
          "is_avc": "true",
          "nal_length_size": "4",
          "r_frame_rate": "30/1",
          "avg_frame_rate": "30/1",
          "time_base": "1/15360",
          "start_pts": 0,
          "start_time": "0.000000",
          "duration_ts": 9747456,
          "duration": "634.600000",
          "bit_rate": "2019563",
          "bits_per_raw_sample": "8",
          "nb_frames": "19038",
          "disposition": {
            "default": 1,
            "dub": 0,
            "original": 0,
            "comment": 0,
            "lyrics": 0,
            "karaoke": 0,
            "forced": 0,
            "hearing_impaired": 0,
            "visual_impaired": 0,
            "clean_effects": 0,
            "attached_pic": 0,
            "timed_thumbnails": 0
          },
          "tags": {
            "language": "und",
            "handler_name": "VideoHandler"
          }
        },
        {
          "index": 1,
          "codec_name": "aac",
          "codec_long_name": "AAC (Advanced Audio Coding)",
          "profile": "LC",
          "codec_type": "audio",
          "codec_time_base": "1/44100",
          "codec_tag_string": "mp4a",
          "codec_tag": "0x6134706d",
          "sample_fmt": "fltp",
          "sample_rate": "44100",
          "channels": 2,
          "channel_layout": "stereo",
          "bits_per_sample": 0,
          "r_frame_rate": "0/0",
          "avg_frame_rate": "0/0",
          "time_base": "1/44100",
          "start_pts": 0,
          "start_time": "0.000000",
          "duration_ts": 27965750,
          "duration": "634.143991",
          "bit_rate": "129582",
          "max_bit_rate": "129582",
          "nb_frames": "27312",
          "disposition": {
            "default": 1,
            "dub": 0,
            "original": 0,
            "comment": 0,
            "lyrics": 0,
            "karaoke": 0,
            "forced": 0,
            "hearing_impaired": 0,
            "visual_impaired": 0,
            "clean_effects": 0,
            "attached_pic": 0,
            "timed_thumbnails": 0
          },
          "tags": {
            "language": "und",
            "handler_name": "SoundHandler"
          }
        }
      ],
      "format": {
        "filename": "http://media.heywatch.com.s3.amazonaws.com/newapi/bbb/720p.mp4",
        "nb_streams": 2,
        "nb_programs": 0,
        "format_name": "mov,mp4,m4a,3gp,3g2,mj2",
        "format_long_name": "QuickTime / MOV",
        "start_time": "0.000000",
        "duration": "634.600000",
        "size": "171012682",
        "bit_rate": "2155848",
        "probe_score": 100,
        "tags": {
          "major_brand": "isom",
          "minor_version": "512",
          "compatible_brands": "isomiso2avc1mp41",
          "title": "Big Buck Bunny, Sunflower version",
          "artist": "Blender Foundation 2008, Janus Bager Kristensen 2013",
          "composer": "Sacha Goedegebure",
          "encoder": "Lavf57.25.100",
          "comment": "Creative Commons Attribution 3.0 - http://bbb3d.renderfarming.net",
          "genre": "Animation"
        }
      }
    },
    "source": {
      "streams": [
        {
          "index": 0,
          "codec_name": "h264",
          "codec_long_name": "H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10",
          "profile": "High",
          "codec_type": "video",
          "codec_time_base": "1/60",
          "codec_tag_string": "avc1",
          "codec_tag": "0x31637661",
          "width": 1920,
          "height": 1080,
          "coded_width": 1920,
          "coded_height": 1088,
          "has_b_frames": 2,
          "sample_aspect_ratio": "1:1",
          "display_aspect_ratio": "16:9",
          "pix_fmt": "yuv420p",
          "level": 41,
          "chroma_location": "left",
          "refs": 1,
          "is_avc": "true",
          "nal_length_size": "4",
          "r_frame_rate": "30/1",
          "avg_frame_rate": "30/1",
          "time_base": "1/30000",
          "start_pts": 2000,
          "start_time": "0.066667",
          "duration_ts": 19036000,
          "duration": "634.533333",
          "bit_rate": "2998715",
          "bits_per_raw_sample": "8",
          "nb_frames": "19036",
          "disposition": {
            "default": 1,
            "dub": 0,
            "original": 0,
            "comment": 0,
            "lyrics": 0,
            "karaoke": 0,
            "forced": 0,
            "hearing_impaired": 0,
            "visual_impaired": 0,
            "clean_effects": 0,
            "attached_pic": 0,
            "timed_thumbnails": 0
          },
          "tags": {
            "creation_time": "2013-12-16T17:44:39.000000Z",
            "language": "und",
            "handler_name": "GPAC ISO Video Handler"
          }
        },
        {
          "index": 1,
          "codec_name": "mp3",
          "codec_long_name": "MP3 (MPEG audio layer 3)",
          "codec_type": "audio",
          "codec_time_base": "1/48000",
          "codec_tag_string": "mp4a",
          "codec_tag": "0x6134706d",
          "sample_fmt": "fltp",
          "sample_rate": "48000",
          "channels": 2,
          "channel_layout": "stereo",
          "bits_per_sample": 0,
          "r_frame_rate": "0/0",
          "avg_frame_rate": "0/0",
          "time_base": "1/48000",
          "start_pts": 0,
          "start_time": "0.000000",
          "duration_ts": 30441600,
          "duration": "634.200000",
          "bit_rate": "160000",
          "max_bit_rate": "165120",
          "nb_frames": "26425",
          "disposition": {
            "default": 1,
            "dub": 0,
            "original": 0,
            "comment": 0,
            "lyrics": 0,
            "karaoke": 0,
            "forced": 0,
            "hearing_impaired": 0,
            "visual_impaired": 0,
            "clean_effects": 0,
            "attached_pic": 0,
            "timed_thumbnails": 0
          },
          "tags": {
            "creation_time": "2013-12-16T17:44:42.000000Z",
            "language": "und",
            "handler_name": "GPAC ISO Audio Handler"
          }
        },
        {
          "index": 2,
          "codec_name": "ac3",
          "codec_long_name": "ATSC A/52A (AC-3)",
          "codec_type": "audio",
          "codec_time_base": "1/48000",
          "codec_tag_string": "ac-3",
          "codec_tag": "0x332d6361",
          "sample_fmt": "fltp",
          "sample_rate": "48000",
          "channels": 6,
          "channel_layout": "5.1(side)",
          "bits_per_sample": 0,
          "dmix_mode": "-1",
          "ltrt_cmixlev": "-1.000000",
          "ltrt_surmixlev": "-1.000000",
          "loro_cmixlev": "-1.000000",
          "loro_surmixlev": "-1.000000",
          "r_frame_rate": "0/0",
          "avg_frame_rate": "0/0",
          "time_base": "1/48000",
          "start_pts": 0,
          "start_time": "0.000000",
          "duration_ts": 30438912,
          "duration": "634.144000",
          "bit_rate": "320000",
          "nb_frames": "19817",
          "disposition": {
            "default": 1,
            "dub": 0,
            "original": 0,
            "comment": 0,
            "lyrics": 0,
            "karaoke": 0,
            "forced": 0,
            "hearing_impaired": 0,
            "visual_impaired": 0,
            "clean_effects": 0,
            "attached_pic": 0,
            "timed_thumbnails": 0
          },
          "tags": {
            "creation_time": "2013-12-16T17:44:42.000000Z",
            "language": "und",
            "handler_name": "GPAC ISO Audio Handler"
          },
          "side_data_list": [
            {
              "side_data_type": "Audio Service Type"
            }
          ]
        }
      ],
      "format": {
        "filename": "http://aws-us-east-1-media.coconut.co.s3.amazonaws.com/11/12/b62ec5f4d8e7617751dd7b020ec23306/466984650",
        "nb_streams": 3,
        "nb_programs": 0,
        "format_name": "mov,mp4,m4a,3gp,3g2,mj2",
        "format_long_name": "QuickTime / MOV",
        "start_time": "0.000000",
        "duration": "634.533333",
        "size": "276134947",
        "bit_rate": "3481424",
        "probe_score": 100,
        "tags": {
          "major_brand": "isom",
          "minor_version": "1",
          "compatible_brands": "isomavc1",
          "creation_time": "2013-12-16T17:44:39.000000Z",
          "title": "Big Buck Bunny, Sunflower version",
          "artist": "Blender Foundation 2008, Janus Bager Kristensen 2013",
          "comment": "Creative Commons Attribution 3.0 - http://bbb3d.renderfarming.net",
          "genre": "Animation",
          "composer": "Sacha Goedegebure"
        }
      }
    }
  }
}

Get metadata of specific source / output

Endpoint: GET /v1/metadata/jobs/:jobid/:source_or_outputname

curl -u "your-api-key:" https://api.coconut.co/v1/metadata/jobs/18370773/mp4:720p

Response examples

{
  "metadata": {
    "mp4:720p": {
      "streams": [
        {
          "index": 0,
          "codec_name": "h264",
          "codec_long_name": "H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10",
          "profile": "Constrained Baseline",
          "codec_type": "video",
          "codec_time_base": "1/60",
          "codec_tag_string": "avc1",
          "codec_tag": "0x31637661",
          "width": 1280,
          "height": 720,
          "coded_width": 1280,
          "coded_height": 720,
          "has_b_frames": 0,
          "sample_aspect_ratio": "1:1",
          "display_aspect_ratio": "16:9",
          "pix_fmt": "yuv420p",
          "level": 30,
          "chroma_location": "left",
          "refs": 1,
          "is_avc": "true",
          "nal_length_size": "4",
          "r_frame_rate": "30/1",
          "avg_frame_rate": "30/1",
          "time_base": "1/15360",
          "start_pts": 0,
          "start_time": "0.000000",
          "duration_ts": 9747456,
          "duration": "634.600000",
          "bit_rate": "2019563",
          "bits_per_raw_sample": "8",
          "nb_frames": "19038",
          "disposition": {
            "default": 1,
            "dub": 0,
            "original": 0,
            "comment": 0,
            "lyrics": 0,
            "karaoke": 0,
            "forced": 0,
            "hearing_impaired": 0,
            "visual_impaired": 0,
            "clean_effects": 0,
            "attached_pic": 0,
            "timed_thumbnails": 0
          },
          "tags": {
            "language": "und",
            "handler_name": "VideoHandler"
          }
        },
        {
          "index": 1,
          "codec_name": "aac",
          "codec_long_name": "AAC (Advanced Audio Coding)",
          "profile": "LC",
          "codec_type": "audio",
          "codec_time_base": "1/44100",
          "codec_tag_string": "mp4a",
          "codec_tag": "0x6134706d",
          "sample_fmt": "fltp",
          "sample_rate": "44100",
          "channels": 2,
          "channel_layout": "stereo",
          "bits_per_sample": 0,
          "r_frame_rate": "0/0",
          "avg_frame_rate": "0/0",
          "time_base": "1/44100",
          "start_pts": 0,
          "start_time": "0.000000",
          "duration_ts": 27965750,
          "duration": "634.143991",
          "bit_rate": "129582",
          "max_bit_rate": "129582",
          "nb_frames": "27312",
          "disposition": {
            "default": 1,
            "dub": 0,
            "original": 0,
            "comment": 0,
            "lyrics": 0,
            "karaoke": 0,
            "forced": 0,
            "hearing_impaired": 0,
            "visual_impaired": 0,
            "clean_effects": 0,
            "attached_pic": 0,
            "timed_thumbnails": 0
          },
          "tags": {
            "language": "und",
            "handler_name": "SoundHandler"
          }
        }
      ],
      "format": {
        "filename": "http://media.heywatch.com.s3.amazonaws.com/newapi/bbb/720p.mp4",
        "nb_streams": 2,
        "nb_programs": 0,
        "format_name": "mov,mp4,m4a,3gp,3g2,mj2",
        "format_long_name": "QuickTime / MOV",
        "start_time": "0.000000",
        "duration": "634.600000",
        "size": "171012682",
        "bit_rate": "2155848",
        "probe_score": 100,
        "tags": {
          "major_brand": "isom",
          "minor_version": "512",
          "compatible_brands": "isomiso2avc1mp41",
          "title": "Big Buck Bunny, Sunflower version",
          "artist": "Blender Foundation 2008, Janus Bager Kristensen 2013",
          "composer": "Sacha Goedegebure",
          "encoder": "Lavf57.25.100",
          "comment": "Creative Commons Attribution 3.0 - http://bbb3d.renderfarming.net",
          "genre": "Animation"
        }
      }
    }
  }
}