Build a video website or catalog from your library

You keep your videos in DCAST and want your own website, gallery or catalog that shows them. Your server reads the library through the API, the page shows posters and titles from the answer, and a visitor who opens a video gets one DCAST player. Hosting, transcoding and delivery stay with DCAST, on every plan, the Free plan included.

The short version: list the library with GET /videos on your server, draw a grid of posters from thumbnails.default with the titles, and when a visitor opens a video load the code from GET /videos/:id/embed into one player slot. Public channel and playlist pages need no key. Free, subscription and paid access to a catalog is covered in Recipe: paid catalog.

Steps in order

List the library: GET /videos?status=READY&limit=50 returns the videos that are ready, newest first, with a pagination block for the next pages.
Draw the grid from the answer: id, title, description, duration and the poster thumbnails.default. Show posters, not players.
When a visitor opens a video, call GET /videos/:id/embed and put responsive, as returned, into the one player slot of the page.
If your account limits embedding to listed websites, add your domain with PATCH /me/embed-allowlist. Read the current list from GET /me first, because the call replaces the whole list.
For public pages that need no key, read GET /channel/:username/videos, GET /channel/:username/playlists and GET /playlists/:id, and show more videos of the same creator from GET /videos/:id/related.
Keep the catalog fresh: subscribe to video.processing.completed with webhooks, or read the library again at an interval and cache the answer between visits.

The calls

Call	Auth	What you get
`GET /videos?page=&limit=&status=&search=`	key	Your whole library, newest first. Each video has `id`, `title`, `description`, `visibility`, `duration`, `status`, `thumbnails.default`, `playback.embed` and `watchUrl`. `limit` is at most 100.
`GET /videos/:id`	key	One video with its full row and the `playback` block.
`GET /videos/:id/embed`	key	`responsive` and `iframe` embed code, with `width`, `height` and `aspectRatio`.
`GET /channel/:username/videos`	public	The public, fully processed videos of one channel, with `pagination`.
`GET /channel/:username/playlists`	public	The public playlists of one channel.
`GET /playlists/:id`	public	A playlist with its videos in order.
`GET /videos/:id/related`	public	Other public videos of the same creator.

Example with curl

# The ready videos of your library, 50 per page (server-side)
curl -s -H "Authorization: Bearer pk_YOUR_KEY_HERE" "https://api.dcast.pro/api/v1/videos?status=READY&limit=50"
# → data.videos[].id, .title, .thumbnails.default, .duration; data.pagination

# The player code of the video a visitor opened
curl -s -H "Authorization: Bearer pk_YOUR_KEY_HERE" "https://api.dcast.pro/api/v1/videos/VIDEO_ID/embed"
# → data.responsive, data.iframe, data.width, data.height, data.aspectRatio

# Public pages, no key
curl -s "https://api.dcast.pro/api/v1/channel/USERNAME/videos?page=1&limit=24"
curl -s "https://api.dcast.pro/api/v1/channel/USERNAME/playlists"
curl -s "https://api.dcast.pro/api/v1/playlists/PLAYLIST_ID"
curl -s "https://api.dcast.pro/api/v1/videos/VIDEO_ID/related"

Showing several videos on a page

Paste responsive exactly as returned. For a smaller player use a narrower container, never a fixed height, a border or a corner radius on the iframe.
Every embedded player starts playing by itself, muted, once it has loaded. So show posters with titles in the grid and load the player only for the video the visitor opens: one player per page, above the list or in a dialog.
Titles, descriptions and posters come from the API. Read them again from the answer instead of copying them into your own files.

Where the key lives

A server-side catalog needs a pk_ key, created in the dashboard under Settings → API Keys. Keep it on your server and out of browser code. Public pages in the browser use the embed code or the public channel calls, which need no key.

Limits

Storage and video quality follow the plan. The numbers of the Free plan are on Free live streaming and video API. Putting videos into the library is described in Upload flows and Videos.

A refused call answers with error.code and error.message. The codes are listed in Errors & limits.

For AI agents

Connect the DCAST MCP server at https://api.dcast.pro/mcp. Each tool is one API operation, and dcast_get_recipe returns the exact tool-call sequence for a job.

Recipes: website-with-my-videos for a whole site (account, list, upload, embed domains, embed code) and website-page-with-videos for one page or gallery: list_videos with status READY, get_embed_domains, then get_video_embed_code for the video the visitor opens.

Take titles, descriptions and posters from list_videos and the player code from get_video_embed_code, pasted as returned; never write an iframe by hand. Ask the person before set_embed_domains, because it replaces the whole list.

Never ask the person to create, copy or paste an API key. If the website's own server must call DCAST, call ask_site_access: the person clicks one Allow link and the key goes straight into the site's environment. You never see it.