Video Ads

Video Ads generates short-form video advertising (YouTube Shorts, TikTok, Facebook Reels, Instagram Reels) from a plain-text brief — writing the script, recording a voiceover, sourcing footage, and assembling the final clip automatically. Marketing/sales users work from the Video Ads Studio to generate and publish creatives, review results in the Videos/Posts/Campaigns grids, and admins configure the platform credentials the pipeline and publishers depend on.

What you can do

• Generate an AI video ad from a short brief (what it's for, target audience, tone, aspect ratio, target length, voice, footage source, whether to burn in subtitles) and watch it render with a live progress bar and stage label ("Writing script", etc.).
• Upload a ready-made video (MP4/MOV/M4V, up to 200 MB) straight into the library instead of generating one.
• Browse the video library (Studio or the video-library grid) with status badges (draft, queued, rendering, ready, failed), progress %, aspect, length, footage source, and voice.
• Retry a failed or already-ready render to regenerate the video.
• Delete a video, which also removes its rendered files.
• Publish a ready video to one or more platforms at once (YouTube, TikTok, Facebook, Instagram), immediately or on a schedule, with per-platform title/description/hashtags/privacy pre-filled from the generated script.
• Track publish status per platform in the video-posts grid (pending, scheduled, publishing, posted, failed), including the resulting post URL or error.
• Track paid campaigns manually per platform in the video-campaigns grid — budget, spend, impressions, views, clicks, objective, dates, notes — linked back to the creative that's running.
• Connect YouTube and TikTok accounts via an in-app OAuth "Connect" flow (admin only).
• Configure stock-footage and platform credentials in Video Ads → Settings (admin only), with secrets masked after saving.
• Open the Studio directly from the Videos grid via the "Open Studio" toolbar button.

Common tasks

1. Generate a video ad In the Video Ads Studio, click to create a new ad, enter a brief plus optional audience/tone/aspect ratio/duration/voice/footage source, and submit. The ad is created with status queued; a detached render job then writes the script, generates voiceover, sources footage, and assembles the final file, updating status/progress/stage as it goes (draft → queued → rendering → ready, or failed with an error message).

2. Upload your own video instead From the Studio, upload an existing MP4/MOV/M4V file (≤200 MB). It's added to the library as ready immediately — no rendering — with a thumbnail and duration extracted automatically.

3. Retry a failed render From the library, retry a video whose status is failed (or re-render one that's ready). This resets it to queued, clears the previous error, and starts a fresh render job.

4. Publish a video to social platforms Once a video's status is ready, choose one or more target platforms (YouTube, TikTok, Facebook, Instagram), optionally edit the pre-filled title/description/hashtags/privacy per platform, and either publish immediately or set a schedule date/time. Each platform creates its own row in the Posts grid, moving from pending/scheduled through publishing to posted (with a link to the live post) or failed (with an error).

5. Connect a YouTube or TikTok account As an admin, save the platform's OAuth client credentials in Video Ads → Settings, then use the "Connect" button to complete the OAuth flow in a popup; the resulting token is stored automatically so future publishes don't need re-authorization.

6. Track a paid campaign Create a row in the Campaigns grid, pick the platform and (optionally) the video creative it promotes, set objective/budget/dates, and manually update spend/impressions/views/clicks as the campaign runs (or once live ad-platform sync is available, via external_id).

Data model

• video_ad — one video creative: the generation brief (audience, tone, aspect, target duration, voice, footage source, subtitles), the AI-written script (script_json: hook, scenes, CTA, title, description, hashtags), render lifecycle (status/progress/stage/error), and the rendered file/thumbnail path, duration, and size.
• video_ad_publish — one post of one video to one platform: platform, status (pending/scheduled/publishing/posted/failed), post title/description/hashtags/privacy, schedule time, posted time, the platform's post id/URL, and any error.
• video_campaign — one paid campaign per platform: name, status (draft/active/paused/ended), objective, linked creative, daily/total budget, start/end dates, and performance metrics (spend, impressions, views, clicks, conversions), plus external_id/metrics_synced_at reserved for future live ad-platform sync.

Configuration & integrations

Configured under Video Ads → Settings (admin only), stored per-site with secrets encrypted:

• Stock footage — Pexels API key (primary) and/or Pixabay API key (fallback), used to source b-roll per scene. With neither key set, the pipeline falls back to product images (Ken Burns pans over item photos) or a branded gradient card, so generation never hard-fails for lack of footage.
• Script generation — Claude, via the platform's internal LLM client, writes the scene-by-scene script (no separate key to configure here — uses the platform's existing LLM setup).
• Voiceover — Kokoro TTS (self-hosted, OpenAI-compatible speech endpoint) renders each scene's line to audio.
• YouTube — a Google Cloud OAuth client (client id + secret); connecting an account via OAuth stores a refresh token used for resumable uploads (youtube.upload scope). Vertical videos under 3 minutes publish automatically as Shorts.
• TikTok — a TikTok developer app (client key + secret); OAuth connect stores an access/refresh token pair (access tokens live 24h and refresh automatically on publish). Unaudited TikTok apps can only post privately (SELF_ONLY) until the app passes TikTok's review.
• Facebook Reels / Instagram Reels — no separate credentials here; publishing reuses the existing Meta Ads app's stored Page token, with just the target Facebook Page ID and Instagram user ID kept in Video Ads settings. Instagram Reels requires the rendered file to be reachable at a public HTTPS URL, which the platform's own static file serving provides.

API reference

All endpoints are under /api/v1/videoads and require the Video Ads app to be enabled for the tenant; most require at least the sales role, deletion and settings require admin/superuser.

• GET /videoads/videos — list recent videos in the library.
• GET /videoads/videos/{video_id} — get one video's full detail, including script and render status.
• POST /videoads/generate — create a new video ad from a brief and start the AI render pipeline.
• POST /videoads/videos/{video_id}/retry — reset a failed/ready video to queued and re-render it.
• DELETE /videoads/videos/{video_id} — soft-delete a video and remove its rendered files.
• POST /videoads/upload — upload an existing MP4/MOV/M4V straight into the library as ready.
• GET /videoads/voices — list available TTS voices.
• GET /videoads/videos/{video_id}/publishes — list publish attempts for a video.
• POST /videoads/videos/{video_id}/publish — create one publish row per requested platform (immediate or scheduled) and kick off publishing.
• GET /videoads/settings — get the current (masked) Video Ads settings.
• PUT /videoads/settings — update stock-footage/YouTube/TikTok/Facebook/Instagram settings.
• GET /videoads/youtube/auth-url / GET /videoads/youtube/callback — YouTube OAuth connect flow.
• GET /videoads/tiktok/auth-url / GET /videoads/tiktok/callback — TikTok OAuth connect flow.

The Videos, Posts, and Campaigns list screens (video-library, video-posts, video-campaigns) are standard grid CRUD via the platform's generic grid API rather than bespoke endpoints — search, sort, inline edit (Campaigns only), and delete work the same way as any other module grid.