Upload and process video

Send a video to Fileboy from your server or the dashboard, find out when it is ready, and add a poster image and captions. For playing it, see Play a video.

The shared demo key cannot upload video, poster images or captions. Use a free app of your own.

From the dashboard

Open your app's Videos page and drop in a file. Each video shows its processing state, a preview, its id and the embed code.

Upload a video

Send the original file as multipart form data. The file's content type must be video/*. The response comes back as soon as the file is stored. Encoding then runs in the background.

POST

1
https://api.fileboy.io/videos/upload

Body

file binary

The video. Its content type must start with video/.

data string, optional

JSON with the video name and, optionally, its description, tags and metadata, for example {"name":"Launch day","tags":["launch"],"metadata":{"orderId":"42"}}. A bad value is refused (400) before anything is stored. See the limits in Manage files and videos. Whoever uploads chooses these, so when uploads come from browsers with your public key, set ids you rely on from your server with PATCH /videos/:id instead.

Response

id string

The video id. Use it for everything else.

name string

The video name.

description string

Plain text shown on the watch page. Empty when none was sent.

tags / metadata string[] / object

Private, for your own records. Also in every video.* webhook.

rawFileId string

The stored original, as a file id.

Example

REQUEST

1
curl https://api.fileboy.io/videos/upload -H "Authorization: public YOUR_PUBLIC_KEY" -F "file=@./clips/launch.mp4;type=video/mp4" -F 'data={"name":"Launch day","description":"Our launch, in two minutes.","tags":["launch"],"metadata":{"orderId":"42"}}'

RESPONSE

1
2
3
4
5
6
7
8
{
  "id": "4a7b8f2e-6c1d-4f3a-9b0e-2d5c7e9a1b34",
  "name": "Launch day",
  "description": "Our launch, in two minutes.",
  "tags": ["launch"],
  "metadata": { "orderId": "42" },
  "rawFileId": "0c5d1f3a-8e2b-4c7a-a1d9-5b6e7f8a9c01"
}

Upload with a library

The Ruby, Python and PHP libraries wrap the upload and the calls that follow. The Node and browser libraries do not have a video upload method yet, so use the HTTP call or the dashboard from JavaScript.

// Video upload is part of the HTTP API. The SDKs for Ruby, Python and PHP wrap it:
// see the Ruby, Python or PHP tab, or upload from the dashboard.

video = fileboy.upload_video("./clips/launch.mp4", name: "Launch day")

# encoding runs in the background: poll until it is ready
data = fileboy.fetch_video_data(video.id)
data["extractionStatus"]

fileboy.build_video_manifest_url(video.id, type: :hls)
fileboy.build_video_poster_url(video.id)

video = client.upload_video("./clips/launch.mp4", name="Launch day")

# encoding runs in the background: poll until it is ready
data = client.fetch_video_data(video.id)
data["extractionStatus"]

client.build_video_manifest_url(video.id, type="hls")
client.build_video_poster_url(video.id)

$video = $fileboy->uploadVideo('./clips/launch.mp4', name: 'Launch day');

// encoding runs in the background: poll until it is ready
$data = $fileboy->fetchVideoData($video->id);
$data['extractionStatus'];

$fileboy->buildVideoManifestUrl($video->id, type: 'hls');
$fileboy->buildVideoPosterUrl($video->id);

curl https://api.fileboy.io/videos/upload \
  -H "Authorization: public YOUR_PUBLIC_KEY" \
  -F "file=@./clips/launch.mp4;type=video/mp4" \
  -F 'data={"name":"Launch day"}'

Find out when it is ready

The best way is a

video.ready

webhook: Fileboy calls your server when the video can be played, and

video.failed

if encoding did not work. See the webhooks guide.

Otherwise poll the video's data. Reading needs no key unless the app requires signed URLs.

extractionStatus

moves from

pending

processing

done

, or to

error

with a

statusMessage

GET

1
https://api.fileboy.io/videos/VIDEO_ID/data

RESPONSE

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "data": {
    "id": "4a7b8f2e-6c1d-4f3a-9b0e-2d5c7e9a1b34",
    "name": "Launch day",
    "description": "Our launch, in two minutes.",
    "duration": 12.5,
    "playCount": 0,
    "extractionStatus": "done",
    "statusMessage": "",
    "videoFiles": [
      { "id": "...", "type": "audio", "processingStatus": "done" },
      { "id": "...", "type": "video", "width": 426, "height": 240, "processingStatus": "done" },
      { "id": "...", "type": "video", "width": 1280, "height": 720, "processingStatus": "done" }
    ],
    "generatedPosterFile": { "id": "..." },
    "transcripts": [{ "id": "...", "language": "English" }]
  }
}

Polling

1
2
3
4
5
6
7
8
9
10
11
12
async function waitForVideo(videoId) {
  for (let attempt = 0; attempt < 120; attempt++) {
    const res = await fetch(`https://api.fileboy.io/videos/${videoId}/data`)
    const { data } = await res.json()

    if (data.extractionStatus === "done") return data
    if (data.extractionStatus === "error") throw new Error(data.statusMessage)

    await new Promise(resolve => setTimeout(resolve, 5000))
  }
  throw new Error("Timed out waiting for the video")
}

Add your own poster image

Fileboy picks a frame from the video as the poster. To use your own image instead, upload one. The content type must be image/*.

POST

1
https://api.fileboy.io/videos/{id}/poster/upload

URL Params

id string

The video id.

Body

file binary

The image, as multipart form data.

Response

data.id string

The stored image file id.

Example

REQUEST

1
curl https://api.fileboy.io/videos/VIDEO_ID/poster/upload -H "Authorization: public YOUR_PUBLIC_KEY" -F "file=@./poster.jpg;type=image/jpeg"

RESPONSE

1
{ "data": { "id": "6d2f0a9e-1b3c-4d5e-8f70-9a1b2c3d4e5f" } }

Add captions and transcripts

Upload a WebVTT file (or a plain text file) for each language, with a language name of your choosing. The player lists them in its captions menu. The language string is what you pass to the player's

defaultCaption

option, so keep it consistent. For a walkthrough, see the captions guide.

id = fileboy.upload_video_transcript(video.id, "./clips/launch.vtt", language: "English")
text = fileboy.fetch_video_transcript(video.id, id)

transcript_id = client.upload_video_transcript(video.id, "./clips/launch.vtt", language="English")
text = client.fetch_video_transcript(video.id, transcript_id)

$id = $fileboy->uploadVideoTranscript($video->id, './clips/launch.vtt', language: 'English');
$text = $fileboy->fetchVideoTranscript($video->id, $id);

curl https://api.fileboy.io/videos/VIDEO_ID/transcripts/upload \
  -H "Authorization: public YOUR_PUBLIC_KEY" \
  -F "file=@./launch.vtt;type=text/vtt" \
  -F 'data={"language":"English"}'

You can read a transcript back with

GET /videos/:id/transcripts/:transcriptId

Delete a video

Use the dashboard or the management API, which needs your private key. Deleting a video removes the original, every rendition, the posters and the transcripts, and sends

video.deleted