Revid API foundations

Everything every other skill in this library depends on. Read this once.

When to use

Always — but transparently. Other skills assume the agent already knows:

• how to authenticate
• which endpoint to hit
• how to wait for the result
• the response envelope shape

The shape of every Revid call

POST https://www.revid.ai/api/public/v3/render
Header:  key: $REVID_API_KEY
Body:    { "workflow": "<one-of-9>", "source": { … }, … }
   ↓
{ "success": 1, "pid": "p_…" }
   ↓
GET https://www.revid.ai/api/public/v3/status?pid=p_…
   ↓ (poll every 5–8 s)
{ "status": "ready", "videoUrl": "https://cdn.revid.ai/v/…mp4", … }

That's the entire contract. Skills only differ in the body of POST /render.

Auth

key: $REVID_API_KEY

The header is literally named key (not Authorization). If unset, fail with a clear message instead of calling the API.

The 9 workflows

Pick the workflow that matches the input shape, not the output you want. The same script-to-video workflow can produce a Reel, a YouTube short, or a LinkedIn square — that's just aspectRatio.

Source mapping

Each workflow expects one of these source.* fields:

If you put text in the wrong field, the call fails 422 with a schema error.

Common knobs every skill should set

1. aspectRatio — pick from the consumer surface:

   • Reels / TikTok / Shorts → 9:16
   • LinkedIn / Instagram feed → 1:1
   • YouTube long-form → 16:9

2. voice.enabled — true for narrated content; false for music-only or caption-only outputs.

3. captions.enabled — keep true by default. Most short-form watches happen on mute.

4. music.enabled — true for promo / ad / story content; false for talking-head where the avatar voice should breathe.