Create an asynchronous encoding job with a single request - specify an input source, storage destination, output formats (MP4, WebM, HLS, MPEG-DASH, thumbnails, GIF), and a webhook notification - then retrieve the job and its status and progress.
openapi: 3.0.1
info:
title: Coconut API
description: >-
The Coconut API v2 is a cloud video and audio encoding/transcoding service.
A single asynchronous job transcodes a source media file into multiple
output formats, packages adaptive HLS/MPEG-DASH streams, and generates
thumbnails and GIF animations, delivering results to cloud storage and
reporting progress through webhooks. Authentication is HTTP Basic with the
API key as the username and a blank password.
termsOfService: https://www.coconut.co/terms
contact:
name: Coconut Support
email: team@coconut.co
url: https://docs.coconut.co
version: '2'
servers:
- url: https://api.coconut.co/v2
description: Default region (North Virginia, us-east-1)
- url: https://api-us-west-2.coconut.co/v2
description: Oregon (us-west-2)
- url: https://api-eu-west-1.coconut.co/v2
description: Ireland (eu-west-1)
security:
- basicAuth: []
tags:
- name: Jobs
description: Create and retrieve encoding jobs.
- name: Metadata
description: Retrieve technical metadata for input and output files.
paths:
/jobs:
post:
operationId: createJob
tags:
- Jobs
summary: Create a job
description: >-
Submit a new encoding job. A single request defines the input source,
storage destination, desired outputs, optional notification webhook,
and optional settings (such as ultrafast parallel transcoding). The job
runs asynchronously and progress is reported via the notification
webhook when configured.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateJobRequest'
responses:
'201':
description: Job created.
content:
application/json:
schema:
$ref: '#/components/schemas/Job'
'401':
description: Authentication failed (invalid API key).
'422':
description: Invalid job configuration.
/jobs/{jobId}:
get:
operationId: retrieveJob
tags:
- Jobs
summary: Retrieve a job
description: >-
Retrieve a single job by its identifier, including overall status,
progress, input status, and the status and URLs of each output.
parameters:
- name: jobId
in: path
required: true
description: The identifier of the job.
schema:
type: string
responses:
'200':
description: Job retrieved.
content:
application/json:
schema:
$ref: '#/components/schemas/Job'
'401':
description: Authentication failed.
'404':
description: Job not found.
/metadata/jobs/{jobId}:
get:
operationId: retrieveJobMetadata
tags:
- Metadata
summary: Retrieve all metadata for a job
description: >-
Retrieve technical metadata (streams and format) for the input source
and all output files of a job.
parameters:
- name: jobId
in: path
required: true
description: The identifier of the job.
schema:
type: string
responses:
'200':
description: Metadata retrieved.
content:
application/json:
schema:
$ref: '#/components/schemas/MetadataResponse'
'401':
description: Authentication failed.
'404':
description: Job or metadata not found.
/metadata/jobs/{jobId}/{key}:
get:
operationId: retrieveOutputMetadata
tags:
- Metadata
summary: Retrieve metadata for a specific source or output key
description: >-
Retrieve technical metadata for a single input source or output file
identified by its key name.
parameters:
- name: jobId
in: path
required: true
description: The identifier of the job.
schema:
type: string
- name: key
in: path
required: true
description: The source or output key name (for example "source" or "mp4:720p").
schema:
type: string
responses:
'200':
description: Metadata retrieved.
content:
application/json:
schema:
$ref: '#/components/schemas/Metadata'
'401':
description: Authentication failed.
'404':
description: Key not found.
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >-
HTTP Basic authentication. Use the API key as the username and leave
the password blank.
schemas:
CreateJobRequest:
type: object
required:
- input
- storage
- outputs
properties:
input:
$ref: '#/components/schemas/Input'
storage:
$ref: '#/components/schemas/Storage'
outputs:
$ref: '#/components/schemas/Outputs'
notification:
$ref: '#/components/schemas/Notification'
settings:
$ref: '#/components/schemas/Settings'
Input:
type: object
description: The source media file to transcode.
properties:
url:
type: string
format: uri
description: Publicly reachable URL of the source media file.
service:
type: string
description: Cloud storage service when fetching the input from private storage.
bucket:
type: string
credentials:
$ref: '#/components/schemas/Credentials'
Storage:
type: object
description: Destination where output files are uploaded.
properties:
service:
type: string
description: Storage service (for example s3, gcs, dospaces, azure, backblaze, rackspace, sftp).
example: s3
region:
type: string
example: us-east-1
bucket:
type: string
path:
type: string
description: Destination path prefix within the bucket.
credentials:
$ref: '#/components/schemas/Credentials'
Credentials:
type: object
description: Access credentials for the storage service.
properties:
access_key_id:
type: string
secret_access_key:
type: string
Outputs:
type: object
description: >-
Map of output keys to output definitions. Keys identify the desired
format and variant (for example "mp4:720p", "webm:480p", "httpstream",
"jpg:300x", "gif:200x").
additionalProperties:
oneOf:
- $ref: '#/components/schemas/Output'
- type: array
items:
$ref: '#/components/schemas/Output'
example:
mp4:720p:
path: /transcoded/video_720p.mp4
jpg:300x:
path: /thumbs/thumb_#num#.jpg
number: 5
Output:
type: object
description: A single output definition.
properties:
path:
type: string
description: Destination path for this output file.
url:
type: string
format: uri
description: Direct destination URL (alternative to storage + path).
if:
type: string
description: Conditional expression controlling whether the output is produced.
number:
type: integer
description: Number of images to generate (image outputs only).
Notification:
type: object
description: Webhook configuration that receives job event callbacks.
properties:
type:
type: string
enum:
- http
description: Notification transport. Only "http" (webhook) is supported.
url:
type: string
format: uri
description: Endpoint that receives POST callbacks.
events:
type: boolean
default: false
description: >-
When true, Coconut sends a callback for each event
(input.transferred, output.completed, output.failed) in addition to
the final job.completed/job.failed event.
metadata:
type: boolean
default: false
description: When true, callbacks include codec/stream metadata.
Settings:
type: object
description: Optional job-level settings.
properties:
ultrafast:
type: boolean
default: false
description: >-
Split the input into chunks for parallel transcoding (recommended
for 1080p/4K and HEVC; applies to videos longer than one minute).
Job:
type: object
description: An encoding job.
properties:
id:
type: string
status:
type: string
description: Overall job status.
enum:
- job.starting
- job.completed
- job.failed
example: job.completed
progress:
type: string
example: 100%
created_at:
type: string
format: date-time
completed_at:
type: string
format: date-time
input:
$ref: '#/components/schemas/InputStatus'
outputs:
type: array
items:
$ref: '#/components/schemas/OutputStatus'
InputStatus:
type: object
properties:
status:
type: string
enum:
- input.starting
- input.transferring
- input.transferred
- input.failed
OutputStatus:
type: object
properties:
key:
type: string
example: mp4:720p
format:
type: string
example: mp4
type:
type: string
enum:
- video
- image
- httpstream
- audio
status:
type: string
description: Per-output status.
example: video.encoded
urls:
type: array
items:
type: string
format: uri
MetadataResponse:
type: object
description: Metadata for the input source and every output of a job.
additionalProperties:
$ref: '#/components/schemas/Metadata'
Metadata:
type: object
description: Technical metadata for a single media file.
properties:
streams:
type: array
items:
$ref: '#/components/schemas/Stream'
format:
$ref: '#/components/schemas/Format'
Stream:
type: object
properties:
codec_name:
type: string
codec_type:
type: string
enum:
- video
- audio
profile:
type: string
width:
type: integer
height:
type: integer
bit_rate:
type: string
sample_rate:
type: string
channels:
type: integer
Format:
type: object
properties:
filename:
type: string
duration:
type: string
size:
type: string
bit_rate:
type: string
tags:
type: object
additionalProperties:
type: string