Restyle a video

Starts a job that re-composes the source video's archived raw capture with a new style, captions, output size or formats. No browser runs and narration is reused, so it takes seconds. Camera moves are not changed. The result is a new video (`restyled_from` names the source). The raw capture is kept as long as the source video (7 days).

POST /v1/render/videos/{video_id}/restyle
Starts a job that re-composes the source video's archived raw capture with a new style, captions, output size or formats. No browser runs and narration is reused, so it takes seconds. Camera moves are not changed. The result is a new video (`restyled_from` names the source). The raw capture is kept as long as the source video (7 days).

Authentication

Bearer Token (b3os_sk_ API key or b3os_pat_ token) API Key (cookie: __Host-b3os_session)

Path Parameters

video_id string required path
The video ID (`vid_…`).
Example: "vid_01m5t4c5ep9bdfhtx7nk2k3vq7"

Query Parameters

wait integer optional query
Seconds to wait for the job to finish before responding, from 0 to 60. If it finishes in time the response is `200` with the finished job; otherwise `202` with the job as it is, a `Location` to poll and `Retry-After`. `0` (the default) returns immediately.

Header Parameters

Idempotency-Key string optional header
A unique value (for example a UUID) that makes this request safe to retry. Scoped to your project for 24 hours: a retry with the same key, method, path and body returns the stored response with `Idempotent-Replayed: true`, and only to the same API key. Reusing the key for a different request returns `409 idempotency_key_conflict`.

Request Body required

application/json
style object
Style presets plus overrides, the same object as a timeline's `style` (restyle replaces exactly this). Field values inside `overrides` follow the compositor's style type (padding, corner radius, shadow, colors, gradients); strings are escaped before they reach any HTML or CSS.
background string
A preset ID from `GET /v1/render/presets`, such as `midnight`, `browser-dark` or `mac`.
frame string
A preset ID from `GET /v1/render/presets`, such as `midnight`, `browser-dark` or `mac`.
cursor string
A preset ID from `GET /v1/render/presets`, such as `midnight`, `browser-dark` or `mac`.
captions string
A preset ID from `GET /v1/render/presets`, such as `midnight`, `browser-dark` or `mac`.
click_effect string
A preset ID from `GET /v1/render/presets`, such as `midnight`, `browser-dark` or `mac`.
overrides object
Style fields that override the presets.
captions object
burn_in string
`none`: sidecar files only. `static`: draw each cue. `karaoke`: also highlight the spoken word.
Enum: none, static, karaoke
sidecars string[]
Array of: string
max_chars_per_line integer
max_lines integer
max_chars_per_second number
output object
width integer REQUIRED
height integer REQUIRED
fps integer REQUIRED
Enum: 24, 25, 30, 50, 60
formats string[]
Array of: string
webhook object
Where to deliver this job's events. Deliveries are `POST`s of a `WebhookEvent` signed with `B3OS-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">` using the endpoint's secret (`POST /v1/webhooks/secret`). Failed deliveries are retried with backoff for 24 hours. Delivery goes through the egress guard, so private and loopback addresses are refused.
url string (uri) REQUIRED
An `https://` URL.
events string[]
Event types to deliver. Defaults to the terminal events (`job.succeeded`, `job.failed`, `job.canceled`); `["*"]` delivers every event.
Array of: string
metadata object
Up to 16 string key-value pairs you attach to an object for your own use. Keys are 1 to 40 characters of `A-Z a-z 0-9 _ . : -`; values are at most 500 characters. B3OS never interprets them.

Responses

200 The restyled video finished within `wait` seconds, or the event stream.
application/json
id string REQUIRED
object string REQUIRED
Enum: video
status string REQUIRED
`queued` → `running` → one of the terminal statuses `succeeded`, `failed` or `canceled`. A job never leaves a terminal status.
Enum: queued, running, succeeded, failed, canceled
created_at string (date-time) REQUIRED
updated_at string (date-time) REQUIRED
started_at string (date-time) | null
finished_at string (date-time) | null
progress object
How far a job has got, in the job's own unit (pages, items, steps).
completed integer REQUIRED
Units finished, successfully or not.
failed integer
Units that failed (included in `completed`).
total integer | null
Units expected, when known.
unit string REQUIRED
What is counted, such as `pages`, `items` or `steps`.
result object
duration_ms integer REQUIRED
width integer REQUIRED
height integer REQUIRED
fps integer REQUIRED
artifacts object[] REQUIRED
Array of:
id string REQUIRED
object string REQUIRED
Enum: artifact
kind string REQUIRED
Enum: image, mp4, gif, poster, vtt, srt
content_type string REQUIRED
bytes integer
width integer
height integer
duration_ms integer
url string (uri)
Signed URL on `usercontent.b3os.org`, `https://usercontent.b3os.org/a/<id in host-safe form>/<name>?node=&exp=&sig=`: an Ed25519 signature by the node's key over the method, path and expiry (`renderGetArtifactContent`), no cookies. It works as soon as the artifact is reported, while the upload to storage is still finishing.
url_expires_at string (date-time)
created_at string (date-time)
expires_at string (date-time)
When the artifact is deleted.
recording object
reused boolean REQUIRED
True when the video replayed an earlier recording (`recording.reuse`) instead of loading the site.
recorded_at string (date-time)
When the replayed or new recording was made.
error object
An RFC 9457 problem. `code` is stable and listed in the errors catalog; `type` links to its entry. `detail` is human-readable and may change. Extension members appear only for the codes that document them; ignore members you do not recognize.
type string (uri) REQUIRED
`https://docs.beta.b3os.org/errors#<code>`.
title string REQUIRED
Short summary of the problem type.
status integer REQUIRED
The HTTP status code, repeated for convenience.
code string REQUIRED
Stable machine-readable error code from the errors catalog.
detail string REQUIRED
Explanation of this occurrence. Never contains secrets.
instance string
The request ID (`req_…`) of the request that failed. Include it when you contact support.
errors object[]
Validation problems, one per field (`invalid_request` and the other codes that list `errors`).
Array of:
pointer string REQUIRED
Where the problem is: a JSON pointer into the request body (`/url`, `/steps/0/uses`), or `#query/<name>`, `#path/<name>` or `#header/<name>` for parameters.
detail string REQUIRED
What is wrong there.
reason string
Finer-grained cause for codes that document one (`unauthorized`, `forbidden`, `egress_denied`, `upstream_unreachable`, …).
required_scope string
The scope that was missing (`forbidden` with `reason: scope`).
retry_after_s integer
Same value as the `Retry-After` header, for clients that only read the body.
limit object
The limit an error refers to. IDs and current values are listed by `GET /v1/limits`.
id string REQUIRED
Limit ID, such as `vision.scrape.rpm` or `sandboxes.concurrent`.
limit number REQUIRED
The limit's value.
unit string REQUIRED
What the limit counts, such as `requests`, `sandboxes`, `vcpu` or `MiB`.
window_s integer
Window length in seconds for rate limits and quotas.
current number
Current usage against the limit, when known.
current_status string
The object's current status, for state conflicts such as `sandbox_not_running`.
upstream_status integer
The HTTP status the upstream returned (`upstream_error`, `action_output_invalid`).
step string
The failed step, as a step ID (routines), an index (`act`) or a path such as `beats/2/do/0` (render).
pack_error object
The error a pack's error mapping chose (`upstream_error` from pack actions).
code string REQUIRED
message string REQUIRED
retryable boolean REQUIRED
timing object
Server-side phase durations in milliseconds with microsecond resolution: the same phases as the `Server-Timing` header, keyed `<phase>_ms`. `total_ms` is always present. Phase names are product-specific and documented per operation. Example values in this reference are illustrative, not measurements.
total_ms number REQUIRED
expires_at string (date-time) | null
When the job's results are deleted (retention); `null` while the job is not terminal.
metadata object
Up to 16 string key-value pairs you attach to an object for your own use. Keys are 1 to 40 characters of `A-Z a-z 0-9 _ . : -`; values are at most 500 characters. B3OS never interprets them.
webhook object
Where to deliver this job's events. Deliveries are `POST`s of a `WebhookEvent` signed with `B3OS-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">` using the endpoint's secret (`POST /v1/webhooks/secret`). Failed deliveries are retried with backoff for 24 hours. Delivery goes through the egress guard, so private and loopback addresses are refused.
url string (uri) REQUIRED
An `https://` URL.
events string[]
Event types to deliver. Defaults to the terminal events (`job.succeeded`, `job.failed`, `job.canceled`); `["*"]` delivers every event.
Array of: string
source object REQUIRED
url string (uri) REQUIRED
Where the recording starts.
profile string
A vision profile ID or name to start signed in. Responses show the resolved `prof_` ID.
restyled_from string | null REQUIRED
The source video when this video is a restyle.
202 The restyle job was accepted and is still running.
400 The request failed validation (`invalid_request`, `invalid_url`).
401 Missing, malformed, expired or revoked credentials (`unauthorized`).
402 The organization has no credits left, or the key reached its spend cap.
403 Authenticated but not allowed (`forbidden`, `egress_denied`).
404 No such video in this project (`video_not_found`).
409 The source video has no archived capture (`restyle_unavailable`).
413 The request body exceeds this operation's limit.
415 The Content-Type is not accepted by this operation.
422 A style value is unknown or malformed (`style_invalid`).
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/restyle' \  -H 'Authorization: Bearer YOUR_API_TOKEN' \  -H 'Content-Type: application/json' \  -d '{  "style": {    "background": "sunrise",    "frame": "browser-light"  },  "captions": {    "burn_in": "static"  }}'
const response = await fetch('https://beta-api.b3os.org/v1/render/videos/vid_01m5t4c5ep9bdfhtx7nk2k3vq7/restyle', {  method: 'POST',  headers: {      "Authorization": "Bearer YOUR_API_TOKEN",      "Content-Type": "application/json"  },  body: JSON.stringify({    "style": {      "background": "sunrise",      "frame": "browser-light"    },    "captions": {      "burn_in": "static"    }  })});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/restyle', headers=headers, json={  "style": {    "background": "sunrise",    "frame": "browser-light"  },  "captions": {    "burn_in": "static"  }})print(response.json())
200 Response 
{  "id": "vid_01m5t5ra66vedzccbwd5j50zjc",  "object": "video",  "status": "succeeded",  "source": {    "url": "https://app.example.com"  },  "restyled_from": "vid_01m5t4c5ep9bdfhtx7nk2k3vq7",  "created_at": "2026-10-25T19:00:00.000Z",  "updated_at": "2026-10-25T19:00:02.700Z",  "started_at": "2026-10-25T19:00:00.004Z",  "finished_at": "2026-10-25T19:00:02.700Z",  "result": {    "duration_ms": 9480,    "width": 1920,    "height": 1080,    "fps": 60,    "artifacts": []  },  "expires_at": "2026-11-01T19:00:02.700Z",  "metadata": {}}
Previous Cancel a video
Next Get a video's timeline
Ask a question... ⌘I