Share a video
Makes a share page for a finished video: one HTML page on `usercontent.b3os.org` that plays the MP4 with its poster, captions and chapters, carries Open Graph tags for link previews, and works as an iframe embed on any site. No script runs on it (`Content-Security-Policy: sandbox`). The link is signed like every artifact URL and lasts as long as the video's MP4 (7 days by default). Sharing again returns the same page while it lasts (200); a new one answers 201. Off by default: creating a share page needs the `render.share_pages` feature flag on for your organization, and answers 404 `feature_not_enabled` without it. The page plays the video from the video's own signed file links, which stay valid until the video expires: stopping the share (or deleting the video) takes the page down within 60 seconds, but only deleting the video ends the file links a viewer or a link preview already has. There is no password option.
POST
/v1/render/videos/{video_id}/share
Makes a share page for a finished video: one HTML page on `usercontent.b3os.org` that plays the MP4 with its
poster, captions and chapters, carries Open Graph tags for link previews, and works as an iframe embed on any
site. No script runs on it (`Content-Security-Policy: sandbox`). The link is signed like every artifact URL and
lasts as long as the video's MP4 (7 days by default). Sharing again returns the same page while it lasts
(200); a new one answers 201.
Off by default: creating a share page needs the `render.share_pages` feature flag on for your organization,
and answers 404 `feature_not_enabled` without it. The page plays the video from the video's own signed file
links, which stay valid until the video expires: stopping the share (or deleting the video) takes the page
down within 60 seconds, but only deleting the video ends the file links a viewer or a link preview already
has. There is no password option.
Authentication
Bearer Token (b3os_sk_ API key or b3os_pat_ token)
Path Parameters
video_id
string
required
path
The video ID (`vid_…`).
Example:
"vid_01m5t4c5ep9bdfhtx7nk2k3vq7"Request Body
application/jsontitle
string
The page title and preview title. Default the first beat's `title`, else "Video".
Responses
200
The video's share page, made earlier and still valid.
application/jsonobject
string
REQUIRED
Enum:
video_sharevideo_id
string
REQUIRED
artifact_id
string
REQUIRED
The share page's artifact (kind `share`, `share.html`).
title
string
REQUIRED
url
string (uri)
REQUIRED
The share page, a signed `usercontent.b3os.org` URL valid until `expires_at`.
embed_html
string
REQUIRED
An `<iframe>` of the page, 960 wide at the video's aspect ratio, ready to paste.
width
integer
REQUIRED
The video's width in pixels.
height
integer
REQUIRED
The video's height in pixels.
created_at
string (date-time)
REQUIRED
expires_at
string (date-time)
REQUIRED
When the page and its link end (the MP4's own expiry).
201
A new share page.
400
The request failed validation (`invalid_request`, `invalid_url`).
401
Missing, malformed, expired or revoked credentials (`unauthorized`).
403
Authenticated but not allowed (`forbidden`, `egress_denied`).
404
No such video in this project (`video_not_found`), or share pages are off for your organization (`feature_not_enabled`: the `render.share_pages` flag is not on).
409
The video has not finished, or has no MP4 to share (`conflict`).
413
The request body exceeds this operation's limit.
415
The Content-Type is not accepted by this operation.
429
A rate, concurrency or quota limit applies (`rate_limited`, `concurrency_limited`, `quota_exceeded`).
500
Something failed inside B3OS (`internal`). Retry with backoff.
503
The node or the product is not available right now (`node_unavailable`, `product_unavailable`, `capacity_unavailable`).
curl -X POST 'https://beta-api.b3os.org/v1/render/videos/vid_01m5t4c5ep9bdfhtx7nk2k3vq7/share' \ -H 'Authorization: Bearer YOUR_API_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "title": "The Example launch plan in 30 seconds"}'const response = await fetch('https://beta-api.b3os.org/v1/render/videos/vid_01m5t4c5ep9bdfhtx7nk2k3vq7/share', { method: 'POST', headers: { "Authorization": "Bearer YOUR_API_TOKEN", "Content-Type": "application/json" }, body: JSON.stringify({ "title": "The Example launch plan in 30 seconds" })});const data = await response.json();console.log(data);import requestsheaders = { 'Authorization': 'Bearer YOUR_API_TOKEN'}response = requests.post('https://beta-api.b3os.org/v1/render/videos/vid_01m5t4c5ep9bdfhtx7nk2k3vq7/share', headers=headers, json={ "title": "The Example launch plan in 30 seconds"})print(response.json())
200
Response
{ "object": "video_share", "video_id": "vid_01m5t4c5ep9bdfhtx7nk2k3vq7", "artifact_id": "art_01m6e0s3a1f7r7d0jq0b6kq9x2", "title": "The Example launch plan in 30 seconds", "url": "https://usercontent.b3os.org/a/art-01m6e0s3a1f7r7d0jq0b6kq9x2/share.html?node=n1&exp=1762714800&sig=12hc4wex0XbLjNwjo97CNLfYAYLYSocWC5EJHJen4k_Y2vc2NGOivDeNbR3cM06Pd1eeYYlT0__LXvPUkNieBw", "embed_html": "<iframe src=\"https://usercontent.b3os.org/a/art-01m6e0s3a1f7r7d0jq0b6kq9x2/share.html?node=n1&exp=1762714800&sig=12hc4wex0XbLjNwjo97CNLfYAYLYSocWC5EJHJen4k_Y2vc2NGOivDeNbR3cM06Pd1eeYYlT0__LXvPUkNieBw\" width=\"960\" height=\"540\" style=\"border:0\" allow=\"fullscreen\" allowfullscreen loading=\"lazy\" title=\"The Example launch plan in 30 seconds\"></iframe>", "width": 1920, "height": 1080, "created_at": "2026-11-02T12:00:00.000Z", "expires_at": "2026-11-09T11:59:40.000Z"}API Playground
Try this endpoint
POST
/v1/render/videos/{video_id}/share