Efficient Cloud Video

Efficient Cloud Video offers cost-effective cloud-based video hosting, with powerful built-in features.

Contact

Efficient Cloud Support

API Endpoints

https://graph.efficientvideo.com/graph

Version

1.0.0

Account

An account is the top level of organization. Each account may have an infinite number of video libraries, and an infinite number of access keys.

See also:

Get account

Libraries

A library is a folder that contains one or more videos. Each library belongs to a single account, may contain an infinite number of videos, and has its own metrics and event hooks.

See also:

List libraries
Get library
Create library
Update library
Delete library

Webhooks

Each library can be configured with one or more webhook endpoints to receive updates as videos are processed.

Each hook is dispatched as a POST event with a JSON payload that has two properties:

id - the ID of the video that is being processed
status - the current status of the video being processed (see Video Processing for details)

See also:

List hooks
Create library
Delete library

Videos

A video represents a single video asset.

See also:

List videos
Get video
Import video
Delete video

Adding Videos

There are three ways to add videos to a library:

Import a video from an existing URL

You can import any compatible video format (e.g. mp4) that is publicly available on the internet using the import video mutation.

Upload a small video

To upload a small video, use the sign upload mutation to create an upload link. You should then upload the video in binary format to the response upload_url. Upon upload, the video will be immediately available at a temporary hosting URL as provided by the response download_url. Efficient Cloud video will then import the uploaded video to the relevant video library and delete it from the temporary hosting location. Use hooks to receive updates on progress.

Upload a large video

To upload a large video, use the start multipart upload and finish multipart upload mutations to upload a video in parts (example coming). Efficient Cloud video will then import the uploaded video to the relevant video library and delete it from the temporary hosting location. Use hooks to receive updates on progress.

Video Processing

Once imported or uploaded, each video goes through the following lifecycle states:

UPLOADING - the video placeholder has been created, but the video content is still uploading or being imported from source.
UPLOADED - the video has finished uploading, but has not starting processing.
PROCESSING - the video has started processing.
ENCODING - the video is being transcoded into required formats, but is not yet ready to play
PLAYABLE - the video is still being processed, but at least one bitrate is ready to play
COMPLETE - the video is fully ready to use

At any point, videos may enter the following error states:

NOT_UPLOADED - the video failed to upload
INVALID_UPLOAD - the video successfully uploaded, but is not a valid video file

Thumbnails

Once videos have reached a PLAYABLE or COMPLETE status, thumbnails will be available. Each video has the following thumbnails:

A default static thumbnail is available at /${video_id}/thumbnail.jpg
An animated thumbnail is available at /${video_id}/preview.webp
Additional thumbnails captured at 2 second intervals available at /${video_id}/thumbnail_${thumbnail_number}.jpg. You can determine the number of thumbnails that are available from the get video query.

Thumbnail Modification

You can resize and otherwise modify any thumbnail by passing the following optional query string parameters:

width=100 - resizes to width=100
height=100 - resizes to height=100
aspect_ratio=2:1 - resizes to an aspect ratio of 2:1
quality=100 - modifies the image quality (max 100)

Queries

`get_account`

Description

Get details on your account

Response

Returns an Account!

Example

Query

query get_account {
  get_account {
    id
    name
    libraries {
      ...LibraryFragment
    }
  }
}

Response

{
  "data": {
    "get_account": {
      "id": "xyz789",
      "name": "xyz789",
      "libraries": [Library]
    }
  }
}

Queries

`get_library`

Description

Get a library by ID

Response

Returns a Library!

Arguments

Name	Description
`id` - `String!`	The id of the library to fetch

Example

Query

query get_library($id: String!) {
  get_library(id: $id) {
    id
    name
    account_id
    primary_domain
    total_video_count
    total_video_minutes
    account {
      ...AccountFragment
    }
    hooks {
      ...HookFragment
    }
  }
}

Variables

{"id": "xyz789"}

Response

{
  "data": {
    "get_library": {
      "id": "xyz789",
      "name": "xyz789",
      "account_id": "xyz789",
      "primary_domain": "xyz789",
      "total_video_count": "abc123",
      "total_video_minutes": "xyz789",
      "account": Account,
      "hooks": [Hook]
    }
  }
}

Queries

`get_video`

Description

Get a video by ID

Response

Returns a Video!

Arguments

Name	Description
`id` - `String!`	The ID of the video to fetch

Example

Query

query get_video($id: String!) {
  get_video(id: $id) {
    id
    created_at
    updated_at
    library_id
    status
    duration
    framerate
    width
    height
    thumbnail_count
    max_resolution
    external_id
    external_user
    external_class
    library {
      ...LibraryFragment
    }
  }
}

Variables

{"id": "abc123"}

Response

{
  "data": {
    "get_video": {
      "id": "abc123",
      "created_at": "2007-12-03T10:15:30Z",
      "updated_at": "2007-12-03T10:15:30Z",
      "library_id": "abc123",
      "status": "xyz789",
      "duration": 987.65,
      "framerate": 123.45,
      "width": 987.65,
      "height": 987.65,
      "thumbnail_count": 987.65,
      "max_resolution": "xyz789",
      "external_id": "abc123",
      "external_user": "abc123",
      "external_class": "abc123",
      "library": Library
    }
  }
}

Queries

`list_hooks`

Description

List webhooks for a library

Response

Returns [Hook!]!

Arguments

Name	Description
`library_id` - `String!`	The id of the library to retrieve hooks

Example

Query

query list_hooks($library_id: String!) {
  list_hooks(library_id: $library_id) {
    id
    library_id
    url
    library {
      ...LibraryFragment
    }
  }
}

Variables

{"library_id": "xyz789"}

Response

{
  "data": {
    "list_hooks": [
      {
        "id": "xyz789",
        "library_id": "abc123",
        "url": "xyz789",
        "library": Library
      }
    ]
  }
}

Queries

`list_libraries`

Description

List all the libraries in your account

Response

Returns [Library!]!

Example

Query

query list_libraries {
  list_libraries {
    id
    name
    account_id
    primary_domain
    total_video_count
    total_video_minutes
    account {
      ...AccountFragment
    }
    hooks {
      ...HookFragment
    }
  }
}

Response

{
  "data": {
    "list_libraries": [
      {
        "id": "abc123",
        "name": "abc123",
        "account_id": "xyz789",
        "primary_domain": "abc123",
        "total_video_count": "xyz789",
        "total_video_minutes": "xyz789",
        "account": Account,
        "hooks": [Hook]
      }
    ]
  }
}

Queries

`list_videos`

Description

List the videos in a library

Response

Returns [Video!]!

Arguments

Name	Description
`limit` - `Float`	The number of videos to fetch
`offset` - `Float`	The offset number of videos to fetch
`library_id` - `String!`	The ID of the library to list videos from

Example

Query

query list_videos(
  $limit: Float,
  $offset: Float,
  $library_id: String!
) {
  list_videos(
    limit: $limit,
    offset: $offset,
    library_id: $library_id
  ) {
    id
    created_at
    updated_at
    library_id
    status
    duration
    framerate
    width
    height
    thumbnail_count
    max_resolution
    external_id
    external_user
    external_class
    library {
      ...LibraryFragment
    }
  }
}

Variables

{
  "limit": 123.45,
  "offset": 123.45,
  "library_id": "abc123"
}

Response

{
  "data": {
    "list_videos": [
      {
        "id": "xyz789",
        "created_at": "2007-12-03T10:15:30Z",
        "updated_at": "2007-12-03T10:15:30Z",
        "library_id": "abc123",
        "status": "abc123",
        "duration": 123.45,
        "framerate": 123.45,
        "width": 123.45,
        "height": 123.45,
        "thumbnail_count": 987.65,
        "max_resolution": "abc123",
        "external_id": "xyz789",
        "external_user": "xyz789",
        "external_class": "abc123",
        "library": Library
      }
    ]
  }
}

Mutations

`create_hook`

Description

Create a library hook

Response

Returns a Hook!

Arguments

Name	Description
`url` - `String!`	The url to ping with webhook events
`library_id` - `String!`	The id of the library

Example

Query

mutation create_hook(
  $url: String!,
  $library_id: String!
) {
  create_hook(
    url: $url,
    library_id: $library_id
  ) {
    id
    library_id
    url
    library {
      ...LibraryFragment
    }
  }
}

Variables

{
  "url": "abc123",
  "library_id": "xyz789"
}

Response

{
  "data": {
    "create_hook": {
      "id": "xyz789",
      "library_id": "xyz789",
      "url": "abc123",
      "library": Library
    }
  }
}

Mutations

`create_library`

Description

Create a new library

Response

Returns a Library!

Arguments

Name	Description
`name` - `String!`	A name for the new library

Example

Query

mutation create_library($name: String!) {
  create_library(name: $name) {
    id
    name
    account_id
    primary_domain
    total_video_count
    total_video_minutes
    account {
      ...AccountFragment
    }
    hooks {
      ...HookFragment
    }
  }
}

Variables

{"name": "abc123"}

Response

{
  "data": {
    "create_library": {
      "id": "xyz789",
      "name": "abc123",
      "account_id": "abc123",
      "primary_domain": "abc123",
      "total_video_count": "abc123",
      "total_video_minutes": "abc123",
      "account": Account,
      "hooks": [Hook]
    }
  }
}

Mutations

`delete_hook`

Description

Delete a library hook

Response

Returns a Boolean!

Arguments

Name	Description
`id` - `String!`	The id of the library hook to delete

Example

Query

mutation delete_hook($id: String!) {
  delete_hook(id: $id)
}

Variables

{"id": "abc123"}

Response

{"data": {"delete_hook": false}}

Mutations

`delete_library`

Description

Deletes an existing library

Response

Returns a Boolean!

Arguments

Name	Description
`id` - `String!`	The id of the library to delete

Example

Query

mutation delete_library($id: String!) {
  delete_library(id: $id)
}

Variables

{"id": "xyz789"}

Response

{"data": {"delete_library": true}}

Mutations

`delete_video`

Description

Deletes a video

Response

Returns a Boolean!

Arguments

Name	Description
`id` - `String!`	The ID of the video to delete

Example

Query

mutation delete_video($id: String!) {
  delete_video(id: $id)
}

Variables

{"id": "abc123"}

Response

{"data": {"delete_video": false}}

Mutations

`finish_multipart_upload`

Response

Returns a String!

Arguments

Name	Description
`etags` - `[String!]!`
`upload_id` - `String!`
`key` - `String!`

Example

Query

mutation finish_multipart_upload(
  $etags: [String!]!,
  $upload_id: String!,
  $key: String!
) {
  finish_multipart_upload(
    etags: $etags,
    upload_id: $upload_id,
    key: $key
  )
}

Variables

{
  "etags": ["abc123"],
  "upload_id": "abc123",
  "key": "xyz789"
}

Response

{
  "data": {
    "finish_multipart_upload": "abc123"
  }
}

Mutations

`import_video`

Description

Import a video from an external URL

Response

Returns a Video!

Arguments

Name	Description
`external_class` - `String`	An external class or category to associate with this video. Useful for data matching.
`external_user` - `String`	An external ID to associate with this video. Useful for applying per-user limits.
`external_id` - `String`	An external ID to associate with this video. Useful for data matching.
`url` - `String!`	The URL to fetch an existing video file from
`library_id` - `String!`	The ID of the library to import the video into

Example

Query

mutation import_video(
  $external_class: String,
  $external_user: String,
  $external_id: String,
  $url: String!,
  $library_id: String!
) {
  import_video(
    external_class: $external_class,
    external_user: $external_user,
    external_id: $external_id,
    url: $url,
    library_id: $library_id
  ) {
    id
    created_at
    updated_at
    library_id
    status
    duration
    framerate
    width
    height
    thumbnail_count
    max_resolution
    external_id
    external_user
    external_class
    library {
      ...LibraryFragment
    }
  }
}

Variables

{
  "external_class": "xyz789",
  "external_user": "abc123",
  "external_id": "xyz789",
  "url": "abc123",
  "library_id": "abc123"
}

Response

{
  "data": {
    "import_video": {
      "id": "xyz789",
      "created_at": "2007-12-03T10:15:30Z",
      "updated_at": "2007-12-03T10:15:30Z",
      "library_id": "abc123",
      "status": "abc123",
      "duration": 987.65,
      "framerate": 987.65,
      "width": 123.45,
      "height": 987.65,
      "thumbnail_count": 123.45,
      "max_resolution": "abc123",
      "external_id": "abc123",
      "external_user": "abc123",
      "external_class": "xyz789",
      "library": Library
    }
  }
}

Mutations

`sign_upload`

Response

Returns a SignedUpload!

Arguments

Name	Description
`content_type` - `String!`
`library_id` - `String!`

Example

Query

mutation sign_upload(
  $content_type: String!,
  $library_id: String!
) {
  sign_upload(
    content_type: $content_type,
    library_id: $library_id
  ) {
    upload_url
    download_url
  }
}

Variables

{
  "content_type": "xyz789",
  "library_id": "abc123"
}

Response

{
  "data": {
    "sign_upload": {
      "upload_url": "xyz789",
      "download_url": "xyz789"
    }
  }
}

Mutations

`start_multipart_upload`

Response

Returns a MultiPartUpload!

Arguments

Name	Description
`parts` - `Float!`
`content_type` - `String!`
`library_id` - `String!`

Example

Query

mutation start_multipart_upload(
  $parts: Float!,
  $content_type: String!,
  $library_id: String!
) {
  start_multipart_upload(
    parts: $parts,
    content_type: $content_type,
    library_id: $library_id
  ) {
    key
    bucket
    uploadId
    signedUrls
  }
}

Variables

{
  "parts": 123.45,
  "content_type": "abc123",
  "library_id": "abc123"
}

Response

{
  "data": {
    "start_multipart_upload": {
      "key": "abc123",
      "bucket": "abc123",
      "uploadId": "abc123",
      "signedUrls": ["xyz789"]
    }
  }
}

Mutations

`update_library`

Description

Update an existing

Response

Returns a Library!

Arguments

Name	Description
`name` - `String!`	A new name for the library
`id` - `String!`	The id of the library to update

Example

Query

mutation update_library(
  $name: String!,
  $id: String!
) {
  update_library(
    name: $name,
    id: $id
  ) {
    id
    name
    account_id
    primary_domain
    total_video_count
    total_video_minutes
    account {
      ...AccountFragment
    }
    hooks {
      ...HookFragment
    }
  }
}

Variables

{
  "name": "xyz789",
  "id": "xyz789"
}

Response

{
  "data": {
    "update_library": {
      "id": "xyz789",
      "name": "abc123",
      "account_id": "abc123",
      "primary_domain": "abc123",
      "total_video_count": "xyz789",
      "total_video_minutes": "xyz789",
      "account": Account,
      "hooks": [Hook]
    }
  }
}

Types

Account

Fields

Field Name	Description
`id` - `String!`	The ID of the account
`name` - `String!`	The name of the account
`libraries` - `[Library!]!`	List the libraries belonging to your account

Example

{
  "id": "abc123",
  "name": "abc123",
  "libraries": [Library]
}

Types

Boolean

Description

The Boolean scalar type represents true or false.

Example

true

Types

DateTime

Description

The javascript Date as string. Type represents date and time as the ISO Date string.

Example

"2007-12-03T10:15:30Z"

Types

Float

Description

The Float scalar type represents signed double-precision fractional values as specified by IEEE 754.

Example

123.45

Types

Hook

Fields

Field Name	Description
`id` - `String!`	The ID of the webhook
`library_id` - `String!`	The ID of the library that owns this webhook
`url` - `String!`	The URL to receive this webhook
`library` - `Library!`	The library this hook belongs to

Example

{
  "id": "xyz789",
  "library_id": "abc123",
  "url": "xyz789",
  "library": Library
}

Types

Library

Fields

Field Name	Description
`id` - `String!`	The ID for this video library
`name` - `String!`	The user-provided name for this video library
`account_id` - `String!`	The ID of the account that owns this video library
`primary_domain` - `String!`	The primary domain associated with this video library
`total_video_count` - `String!`	The number of videos in this library (cached)
`total_video_minutes` - `String!`	The number of minutes stored in this library (cached)
`account` - `Account!`	The account this library belongs to
`hooks` - `[Hook!]!`	The list of webhooks this library owns

Example

{
  "id": "abc123",
  "name": "xyz789",
  "account_id": "xyz789",
  "primary_domain": "abc123",
  "total_video_count": "xyz789",
  "total_video_minutes": "abc123",
  "account": Account,
  "hooks": [Hook]
}

Types

MultiPartUpload

Fields

Field Name	Description
`key` - `String!`
`bucket` - `String!`
`uploadId` - `String!`
`signedUrls` - `[String!]!`

Example

{
  "key": "abc123",
  "bucket": "abc123",
  "uploadId": "xyz789",
  "signedUrls": ["xyz789"]
}

Types

SignedUpload

Fields

Field Name	Description
`upload_url` - `String!`
`download_url` - `String!`

Example

{
  "upload_url": "xyz789",
  "download_url": "abc123"
}

Types

String

Description

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Example

"xyz789"

Types

Video

Fields

Field Name	Description
`id` - `String!`	The identifier for this video
`created_at` - `DateTime!`	The date this video was first uploaded
`updated_at` - `DateTime!`	The date this video was last modified
`library_id` - `String!`	The ID of the library that owns this video
`status` - `String!`	The transcoding status for this video
`duration` - `Float`	The duration of this video (seconds)
`framerate` - `Float`	The framerate for this video (frames per second)
`width` - `Float`	The width of this video (pixels)
`height` - `Float`	The height of this video (pixels)
`thumbnail_count` - `Float`	The number of thumbnails for this video
`max_resolution` - `String`	The maximum resolution available for this video
`external_id` - `String`	A user provided ID for this video
`external_user` - `String`	A user provided owner for this video
`external_class` - `String`	A user provided class or category for this video
`library` - `Library!`	The library this video belongs to

Example

{
  "id": "xyz789",
  "created_at": "2007-12-03T10:15:30Z",
  "updated_at": "2007-12-03T10:15:30Z",
  "library_id": "xyz789",
  "status": "xyz789",
  "duration": 123.45,
  "framerate": 123.45,
  "width": 123.45,
  "height": 987.65,
  "thumbnail_count": 987.65,
  "max_resolution": "xyz789",
  "external_id": "abc123",
  "external_user": "xyz789",
  "external_class": "abc123",
  "library": Library
}

Documentation by Anvil SpectaQL