> ## Documentation Index > Fetch the complete documentation index at: https://docs.goosybear.ai/llms.txt > Use this file to discover all available pages before exploring further. # Videos on a site > List, upload, attach, caption, set the start behaviour of, and detach the videos a site plays, through the API. A site can play videos from the workspace's own library, or finished videos made in Goosy. These calls take the optional `workspace` argument ([Which workspace](https://docs.goosybear.ai/api/pages.md#which-workspace)). **Which calls need approval.** On a member's own key, each call runs in one call. On a key with no member behind it (a service account), the calls that cost something answer `confirmation_required` first, and the same call repeated with the `confirmation_id` does it. There is no call that deletes a hosted video; do that in Goosy. | Call | What it does | | - | - | | `page.videos` | Lists the videos a site plays and the ones it could play. Reads only. | | `page.video_upload` | Brings a video file of your own into the workspace. | | `page.video_attach` | Puts a video on a site. | | `page.video_captions` | Turns on captions in the languages you name. | | `page.video_set_playback` | Sets how a video starts, and whether it shows captions. | | `page.video_set_thumbnail` | Sets the picture shown before it plays. | | `page.video_detach` | Takes a video off a site. | ## Read the videos `page.videos` takes `site_id`. It lists the videos the site plays and the workspace videos it could play, each with whether it is ready. A video on the site carries the player address the page embeds, how it starts, whether captions show, and its thumbnail. `placements` lists each page that plays a video, in order. A finished video made in Goosy that is not hosted yet is listed under `finished` with the `video_id` `page.video_attach` takes. ## Upload your own file `page.video_upload` works in steps, named by `action`: 1. `start` with `filename`, `mime_type` and `byte_size`. The answer is one upload address, or parts to sign. 2. `sign_parts` with the `upload_id` and `part_numbers`, for a file sent in parts. Send the parts in order. 3. `complete` records the video (give it a `title`). Name `captions` here to buy them at the same time. 4. `abort` abandons an upload. The video is stored and **never hosted until you attach it to a site.** Storage is charged per month. Captions are charged per language minute, so on a service-account key, `start` and a `complete` that names captions answer `confirmation_required` first. ## Attach a video `page.video_attach` takes `site_id` and `video_id`, plus optional `captions`, `playback_mode` (`preview`, `opening_frame` or `thumbnail`), `show_captions`, and `replace_attachment_id` to swap one attachment for another. `playback_mode` and `show_captions` are stored as the video's default on this site once it is attached. The `video_id` is one of the workspace's videos, or a finished video made in Goosy. While a finished video's file is still being prepared, the answer is `copying`; make the same call again and it attaches. A video with no approved cut yet is refused by name. Attaching a video that isn't hosted yet starts hosting it, which **charges the workspace for encoding**. Captions are charged only when you name them. ## Captions `page.video_captions` takes `site_id`, `video_id` and `languages`, short tags such as `en` or `pt-BR`. Captions are off until you call it. Each language is charged per minute of video, once, when the captions are ready. Only the workspace's own videos can be captioned, not a template's. ## How a video starts `page.video_set_playback` takes `site_id` and the `attachment_id` from `page.videos`. | Field | What it does | | - | - | | `mode` | `preview` plays it muted on a loop as soon as the page opens. `opening_frame` shows its first frame with a play button. `thumbnail` shows its thumbnail until it is pressed. `null` returns it to the player's own defaults. | | `captions` | `true` or `false`. Shows the video's captions only when it has them. | | `placement` | Optional. To set one spot rather than the whole site, give that player's `page_path` and `slot` from `placements`. `null` for `mode` or `captions` here clears that spot back to the video's setting. | The live page plays the new setting from its next view. Nothing is published and nothing is charged. A setting fixed in the page's own embed address still wins. ## The thumbnail `page.video_set_thumbnail` takes `video_id` and `image_id`, the id of an image file in the workspace. The thumbnail belongs to the video, so every site that plays it shows the same picture. It costs nothing, and a template's video keeps its own thumbnail. ## Take a video off `page.video_detach` takes the `attachment_id`. It is **refused by name while the live version of the site still plays the video**, so remove it from the site and publish first. When no site plays the video any more, its hosting ends after a short grace period and the original stays in the workspace. ## Where to go next * [Pages API](https://docs.goosybear.ai/api/pages.md) * [Create, undo and schedule](https://docs.goosybear.ai/api/pages-drafting-and-scheduling.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.