Video posts

Gets a video onto the right post, on the channels that can carry it, with a caption written for sound-off viewing, then checks the post is ready.

Before you start

1. get_account: time zone, autonomy (video attaching works at every level, scheduling needs schedule).
2. list_channels: for each target see the network, video requirement (YouTube needs one), needs_reconnect, and how it is connected. Only channels connected through ProPost's publishing integration (via: "managed" in get_channel_stats, paid plans) can carry video. Bluesky, Mastodon, Google Business and directly connected channels refuse with video_unsupported.
3. The post: get_post or create it with create_draft first. A video is attached to an existing post.
4. Ask where the video lives: a public link, or a file the assistant holds.

Workflow

A. The video has a public https link

1. attach_video with post_id and video_url. The link must serve the video file itself (not a page with a player), answer with a video Content-Type and a Content-Length, use the default https port, carry no credentials in the URL, and finish within about 4 minutes. Up to 5 redirects are followed. Private or internal addresses are refused.
2. Read the response: has_video should be true and applied_to_linked lists linked copies that also got it.

B. The video is a local file (no public link)

1. start_video_upload with post_id, file_name (e.g. launch.mp4), mime_type (one of video/mp4, video/quicktime, video/webm, video/x-m4v, video/mpeg) and the exact size_bytes (at most 1 GB).
2. It returns upload_url, method: "PUT", headers, size_bytes, expires_in_seconds. PUT exactly size_bytes bytes of the file to upload_url with those headers before the link expires (default 15 minutes). The link carries no ProPost credentials; do not send any.
3. finish_video_upload with post_id. It checks the file arrived at the declared size. Nothing changes on the post until this step.
4. If you cannot run an HTTP PUT yourself (no file access or network tool), say so and ask the person to upload the video in ProPost's composer, or to host it at a public link and use path A. Do not pretend it worked.

A new start_video_upload replaces an earlier unfinished one.

Then, for both paths

1. Write or refine the caption (guidance below) with update_post.
2. check_post: fix every issue. A missing video on YouTube gives video_required.
3. At schedule level, add_to_queue or schedule_post with an ISO time and the person's offset. At drafts, tell them it is waiting in ProPost.
4. To undo: remove_video (also clears an unfinished upload).

Which channels carry video

Linked copies: apply_to_linked defaults to true and puts the video on every unpublished linked copy whose channel can carry video, replacing its video. Set it to false to keep the video on one post. Copies on channels that cannot carry video are skipped; mention it (a Bluesky copy then needs its own image or a link).

Writing guidance

• Assume sound off. Most feeds autoplay muted. The first frame and the first two seconds carry a text hook (4 to 7 words) burned into the video. Tell the person to edit this into the file; you cannot change pixels.
• Caption does a different job from the video. Do not paraphrase it. Give the context the video lacks: who it is for, the one takeaway, what to do next. LinkedIn: 2 to 5 short lines. Instagram/TikTok: a hook line plus one line, 0 to 3 tags. YouTube: first line is the title, then a description with timestamps only if the person supplied them.
• Format: vertical 9:16 for TikTok and Instagram Reels; vertical or square for LinkedIn; landscape 16:9 for YouTube. Short beats long: under 60 seconds unless it earns more.
• Captions on the video (subtitles) help accessibility and retention. Suggest burning them in; do not promise ProPost adds them.
• A thumbnail or cover: attach an image only where the network supports it alongside video; otherwise tell the person to set it in the network.
• Example caption for a founder clip: "We cut onboarding from 9 days to 2. This is the one change that did most of it (60 seconds). Which step in your process would you remove first?" Use figures the person gave.

Guardrails

• Do not download or re-host videos that are not the person's own or are not licensed for reuse. Ask if unsure.
• Do not send private or signed links that expire before publishing; the video is copied at attach time, but verify has_video rather than assuming.
• Never publish_now without an explicit yes after showing the caption and channel. Large videos can take a while to process on the network side; report the post's status with get_post afterwards.
• Do not attach a video to a published post (already_published).

If something fails

• video_unsupported: the channel cannot carry video via ProPost. Remove the video from that copy (remove_video) or use apply_to_linked: false.
• video_unavailable: video is not configured for the account; tell them to check their plan or ProPost settings. Do not retry in a loop.
• unsupported_type: convert to MP4, MOV, WebM, M4V or MPEG.
• video_too_large: over 1 GB. Compress or trim.
• video_length_unknown: the link did not declare its size. Use path B.
• video_size_mismatch: the file differs from the declared size. Check the link or re-measure size_bytes.
• video_too_slow: the host is too slow for the 4-minute budget. Use path B or a faster host.
• blocked_url / fetch_failed: the link is private, not https, has credentials or a non-standard port, or the server refused it. Ask for a public link.
• upload_failed: retry once from start_video_upload.
• upload_incomplete: the PUT did not finish or the size was wrong; PUT again before the link expires, or start over.
• no_pending_upload: run start_video_upload first. no_video: nothing to remove.
• video_required / network_rejected: attach a video; read the post error and fix format or length.
• Others: see ../CONVENTIONS.md.