GuidesAPI ReferenceChangelog
Guides
Start Free Trial

Splash Screen/Thumbnail

Upload a splashscreen or thumbnail for a VOD, live channel, or playlist.

How do I upload a splashscreen or thumbnail?

Dacast can auto-generate splashscreens and thumbnails for VOD. This guide is the other path: upload your own image through the API, for a VOD, live channel, or playlist that already exists.

📘

All examples use https://developer.dacast.com. Authenticate with X-Api-Key and send X-Format: default. JSON bodies must include Content-Type: application/json. Init returns 200. A successful upload to storage typically returns 201.

The two image types use the same steps. Only the path suffix and the last segment of the S3 key change: splash / splashscreen vs thumbnail / thumbnail.

ContentSplashThumbnail
VODPOST /v2/vod/{id}/splashPOST /v2/vod/{id}/thumbnail
ChannelPOST /v2/channel/{id}/splashPOST /v2/channel/{id}/thumbnail
PlaylistPOST /v2/playlist/{id}/splashPOST /v2/playlist/{id}/thumbnail

Use playlist (singular). upload_type is required: "ajax" or "curl".

The rest of this page uses VOD splash. Swap the path for thumbnail or for a channel / playlist.

Reference: Create Splash, Create Thumbnail.

Ajax: browser upload to storage

1. Request an upload signature

curl -X POST "https://developer.dacast.com/v2/vod/{vodId}/splash" \
  -H "X-Api-Key: insertYourApiKeyHere" \
  -H "X-Format: default" \
  -H "Content-Type: application/json" \
  -d "{\"upload_type\":\"ajax\"}"
fetch('https://developer.dacast.com/v2/vod/' + vodId + '/splash', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'insertYourApiKeyHere',
    'X-Format': 'default',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ upload_type: 'ajax' })
})
  .then((response) => response.json())
  .then((fields) => {
    // fields: acl, bucket, key, policy, success_action_status, x-amz-*
  });

A successful response looks like:

{
  "acl": "private",
  "bucket": "upload.dacast.com",
  "key": "vod-target-image/{vodId}/splashscreen",
  "policy": "…",
  "success_action_status": "201",
  "x-amz-algorithm": "AWS4-HMAC-SHA256",
  "x-amz-credential": "AKIA…/20211104/us-east-1/s3/aws4_request",
  "x-amz-date": "20211104T102930Z",
  "x-amz-signature": "ad538afc…"
}

For a thumbnail the key ends with /thumbnail. Channel keys use live-target-image/{id}/…. Playlist keys use playlist-target-image/{id}/….

2. POST the file to the bucket from the signature

Use bucket from the response as the host (https://{bucket}). Do not send bucket as a form field - it is not part of the signed form.

Send every other field from the signature, then file last. Include x-amz-algorithm. A successful upload typically returns 201 (success_action_status).

curl -X POST "https://{bucket}" \
  --form "key=vod-target-image/{vodId}/splashscreen" \
  --form "acl=private" \
  --form "success_action_status=201" \
  --form "policy=…" \
  --form "x-amz-algorithm=AWS4-HMAC-SHA256" \
  --form "x-amz-credential=AKIA…/20211104/us-east-1/s3/aws4_request" \
  --form "x-amz-date=20211104T102930Z" \
  --form "x-amz-signature=ad538afc…" \
  --form "[email protected]"
const formdata = new FormData();
formdata.append('key', fields.key);
formdata.append('acl', fields.acl);
formdata.append('success_action_status', fields.success_action_status);
formdata.append('policy', fields.policy);
formdata.append('x-amz-algorithm', fields['x-amz-algorithm']);
formdata.append('x-amz-credential', fields['x-amz-credential']);
formdata.append('x-amz-date', fields['x-amz-date']);
formdata.append('x-amz-signature', fields['x-amz-signature']);
formdata.append('file', fileInput.files[0]); // must be last

fetch('https://' + fields.bucket, { method: 'POST', body: formdata })
  .then((response) => {
    // expect 201
  });

cURL: server-side PUT

Init with "upload_type": "curl". The body is a signed PUT, not the ajax form. Optional source is only the filename used in the generated curl-command (-T thumb.png). If you omit it, the command uses /path/to/file.

curl -X POST "https://developer.dacast.com/v2/vod/{vodId}/splash" \
  -H "X-Api-Key: insertYourApiKeyHere" \
  -H "X-Format: default" \
  -H "Content-Type: application/json" \
  -d "{\"upload_type\":\"curl\",\"source\":\"thumb.png\"}"
{
  "curl-command": "curl -T thumb.png 'https://{bucket}/{key}?AWSAccessKeyId=…&Expires=…&Signature=…'",
  "url": "https://{bucket}/{key}?AWSAccessKeyId=…&Expires=…&Signature=…"
}

Run the curl-command (or PUT the file to url). You already have the VOD / channel / playlist id.

Delete

DELETE the same path. A successful call returns 204.

curl -X DELETE "https://developer.dacast.com/v2/vod/{vodId}/splash" \
  -H "X-Api-Key: insertYourApiKeyHere" \
  -H "X-Format: default"

Delete Splash, Delete Thumbnail.

After you have an image

Updated about 16 hours ago