Recipe: a catalog site with free, subscription and paid access

How to put a creator's videos on your own site — free titles, members-only titles and pay-per-view titles — with what the platform does today. Every behaviour below is read from the running code; where something you would expect is missing, this page says so.

1. The access model of a video

Four fields on every video decide who can play it. You set them with PATCH /videos/:id and read them from GET /videos and GET /videos/:id.

The checks stack: visibility is applied first, then the membership gate, then the purchase gate. A PUBLIC video with isPaid: true is listed publicly but still needs a purchase to play. When a video is both paid and tier-gated, a completed purchase (or an access-key grant) by a signed-in viewer opens it without the subscription.

# Free title
curl -s -X PATCH "https://api.dcast.pro/api/v1/videos/VIDEO_ID" -H "Authorization: Bearer pk_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" -d '{"visibility":"PUBLIC","isPaid":false,"requiredTierId":null}'

# Pay-per-view title, listed on the channel
curl -s -X PATCH "https://api.dcast.pro/api/v1/videos/VIDEO_ID" -H "Authorization: Bearer pk_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" -d '{"visibility":"PUBLIC","isPaid":true,"price":4.99}'

# Members-only title (tier id from GET /tiers)
curl -s -X PATCH "https://api.dcast.pro/api/v1/videos/VIDEO_ID" -H "Authorization: Bearer pk_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" -d '{"visibility":"TIER_EXCLUSIVE","requiredTierId":"TIER_ID"}'

Tiers are created with POST /tiers (needs a FULL_ACCESS key or finance:write) — see Monetization.

2. Build the catalog

Call these from your server. The pk_ key is a secret: never ship it to the browser.

# Your whole library, 50 per page (server-side)
curl -s -H "Authorization: Bearer pk_YOUR_KEY_HERE" "https://api.dcast.pro/api/v1/videos?page=1&limit=50"

# One title with its playback block
curl -s -H "Authorization: Bearer pk_YOUR_KEY_HERE" "https://api.dcast.pro/api/v1/videos/VIDEO_ID"
# → data.playback = { playable, hls, embed, playUrl, accessTokenUrl, thumbnail, requiresToken }

Keep your catalog fresh with webhooks (video.processing.completed, video.processing.failed) instead of polling — see Webhooks.

3. Playback

Option A — the embeddable player (recommended for paid content)

Put playback.embed (https://dcast.tv/embed/VIDEO_ID) in an <iframe>. Any domain may embed it unless the creator has set an embed allowlist (Account). The player asks the platform for a pass itself and, when it is refused, shows a paywall that depends on the reason:

Payment requests made inside the player come from the DCAST player origin, so the integration-domain requirement described in Monetization → Domain verification applies to your own /checkout/* calls, not to the iframe.

Option B — your own player

A browser player on your own domain requires the content owner's PRO or VIP plan. When your page (any origin other than a DCAST site) calls accessTokenUrl, playback.hls, keys or segments, the platform checks the plan of the account that owns the video or stream and that account's embed allowlist (Account; empty = every site). Admitted responses carry Access-Control-Allow-Origin: <your origin> without credentials, so send a DCAST sign-in token as Authorization: Bearer, not as a cookie. Refusals are readable by your page:

The Option A iframe plays from the DCAST origin and is available on every plan. Changes to a plan or an allowlist reach your pages within about a minute.

Read playback.requiresToken on GET /videos/:id:

• true (every video) — playback.hls alone does not play: it answers 401 MASTER_PASS_REQUIRED until the request carries a playback pass.
• Take the address to play from playback.accessTokenUrl: play the masterUrl it returns. For your own video, GET /videos/:id/play returns hls already signed.

accessTokenUrl is GET https://api.dcast.pro/api/videos/VIDEO_ID/access-token. It is not part of /api/v1 and does not read your pk_ key: it decides for the viewer. It admits a request when one of these holds:

curl -s "https://api.dcast.pro/api/videos/VIDEO_ID/access-token?accessCode=A1B2C3D4E5F60718"

# 200
{ "success": true,
  "masterUrl": "https://<delivery-host>/video/VIDEO_ID/master.m3u8?token=...",
  "expiresIn": 300 }

# 401 (sign-in needed) or 403 (refused)
{ "error": "Access denied", "reason": "payment_required", "message": "...",
  "paywall": { "requiresPurchase": true, "requiresSubscription": false, "requiresTier": false,
               "price": 4.99, "tierId": null, "tierName": null, "creatorId": "..." } }

Play masterUrl. The pass for the master playlist is valid for 300 seconds; segment and key passes for 1800 seconds. A 503 with DELIVERY_WORKER_UNAVAILABLE means no delivery host could be chosen at that moment — retry.

4. Selling

The Partner API checkout endpoint buys as the key owner

POST /checkout/subscription (body tierId, creatorUsername, optional interval, successUrl, cancelUrl) returns { sessionId, checkoutUrl } for a hosted Stripe Checkout page. The buyer is always the account that owns the API key. There is no customerEmail or userId field, and sending an X-User-Token for a different user is refused 401 INVALID_USER_TOKEN (“Multi-user desktop flow via a shared pk_ key is currently disabled”).

Consequence: with one key for your site, every checkout would be bought by, and granted to, your own account — not to the viewer who clicked. This endpoint fits an app where each end user holds their own key; it cannot run a storefront for many viewers. It is origin-locked: see domain verification.

Paid videos are bought inside the embedded player.

What works for a multi-viewer site today

• Let the embedded player sell. Paid videos are bought inside the player by email; subscriptions go through a DCAST sign-in. The payment goes through the creator's connected payment gateway.
• Author access keys for people the creator wants to let in. Keys are created in the DCAST dashboard (videos: Content → Videos, access keys panel), one at a time or in bulk (up to 1000 per request). A key is a 16-character code with a seat rule (one screen at a time, or unlimited), an optional expiry and an optional redemption limit. The viewer types it into the embedded player, or your player passes it as ?accessCode=. The video pass accepts only keys scoped to that exact video. Keys cannot be created through the Partner API today.
• Free membership: POST /subscribers with { email, tierId? } returns a link to your public page where the person joins a free tier by their own click; the call itself creates no account and no subscription. It opens SUBSCRIBERS videos once the viewer has joined and is signed in to DCAST. Paid tiers are refused 400 PAID_TIER_USE_CHECKOUT.

Reconciling sales

GET /purchases, GET /videos/:videoId/purchases and GET /monetization/payments list completed sales of your content (all three need a FULL_ACCESS key or finance:read). purchase.completed is not in the webhook catalogue; reconcile sales from the list endpoints. subscription.created, subscription.renewed and subscription.cancelled are in the event catalogue.

5. Checklist

1. Create a FULL_ACCESS key; keep it on your server.
2. Create tiers (POST /tiers) and set each video's visibility, isPaid/price, requiredTierId.
3. Make sure the creator's payout account is connected: GET /monetization/connect-status must say connected: true. The call needs an Owner-class key or finance:read.
4. Render the catalog from GET /videos (or GET /channel/:username/videos for public titles only).
5. Play with the embedded player for anything paid or members-only; use your own player only with a pass from accessTokenUrl or a code you hold.
6. If your site calls /checkout/* from its own pages, declare and verify its domain first.
7. Subscribe to webhooks and reconcile sales from the purchases endpoints.

Teaser for paid videos

A paid or subscriber-only video shows a visitor who has not bought it a teaser behind the buy card: your own promo clip, or an automatic preview. You, as the owner, and your buyers see the full video. The promo clip is set in the dashboard. Through the Partner API, PATCH /api/v1/videos/{id} that makes a published video paid also creates the automatic preview, and GET /api/v1/videos/{id}/teaser shows whether the video is gated, which clip visitors see and the state of each clip.

Which videos get a teaser

• Pay-per-view videos, subscriber videos and tier-exclusive videos, so every locked video invites a visitor in the same way. A paid video gets an automatic preview even when it is private.
• Free videos show no teaser: a free public video plays normally, and a free private video or a free video shared only by link gets no automatic preview.

The automatic preview

The automatic preview is the first 60 seconds of the video, blurred and without sound.

When you make a finished free video paid, its preview is prepared at that moment. A video made paid while it is still processing gets its preview when the processing finishes. A video that is still uploading is never cut into a preview before all of its bytes have arrived.

A video whose processing failed or was cancelled is not cut into a preview. A video that already carries your own promo clip gets no automatic preview, because your clip is shown instead.

Your own promo clip

A promo clip plays clear, with sound, behind the buy button, and is shown instead of the automatic preview.

1. In the dashboard open VIDEOS and click the gear icon on the card of the video to open Editing Video. The video has to have finished processing.
2. Set Monetization to anything but Free. The block What viewers see when access is closed appears; choose Teaser.
3. Click Upload promo and choose a video file of at most 300 MB.
4. The window says Preparing the promo clip for about a minute, until it says Promo clip is in place. Then click Save Changes.

Replace promo swaps the clip for another file, and Remove promo goes back to the automatic preview. Switching the block to the cover deletes the promo clip; the window asks before it does.

To see the video as a visitor does, open its watch link in a private browser window.

Step by step

The same steps, with common problems and their fixes, are in the help centre: Show visitors a teaser of a paid video. Selling access through the API is described in Monetization API.