Revid API Foundations

Foundation knowledge for every Revid skill — auth, the single render endpoint, the workflow discriminator, polling, webhooks, and the response envelope. Load...

Security Scan

The skill is an instruction-only Revid API reference that consistently requests a single Revid API key and describes only API calls the skill needs; nothing obvious is disproportionate, but the skill's origin is unspecified so verify the key and provenance before enabling it.

Purpose & Capability

Name and description claim to provide foundational Revid API guidance and the SKILL.md only requires a single Revid API key and documents the /render and /status endpoints — these requirements are consistent with the stated purpose.

Instruction Scope

The instructions describe HTTP calls, the required header (key: $REVID_API_KEY), response handling, polling, webhook usage, and failure modes. They do not ask the agent to read unrelated files or secrets. Note: the polling guidance implies frequent outbound requests (every 5–8s) which may be costly or noisy if run unattended.

Install Mechanism

There is no install spec and no code files — this is instruction-only, so nothing will be written to disk by an installer.

Credentials

The only credential/config required is REVID_API_KEY (declared in the skill metadata and used in instructions). That is proportional to a skill that calls Revid's API; no unrelated secrets or multiple credentials are requested.

Persistence & Privilege

always:false and default autonomous invocation are set. The skill does not request permanent presence or system-wide changes. Autonomous invocation is the platform default and not by itself a concern.

Assessment

This skill is an instruction-only Revid API reference and appears coherent: it only needs a single REVID_API_KEY and documents how to call /render and poll /status. Before installing, confirm the skill's provenance (no homepage/source listed) and that you trust the owner. Protect the REVID_API_KEY: use a key with minimal scope or a dedicated account, rotate it if possible, and avoid exposing it to untrusted agents. If you expect high-volume or unattended renders, prefer setting webhookUrl (recommended in the doc) to avoid continuous polling, and monitor usage/charges. Finally, if you are uncomfortable with autonomous agent actions, restrict the agent's permissions or require manual invocation for operations that will use your API key.

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

Workflow	Use when input is…
script-to-video	Already-written script (text).
prompt-to-video	A one-liner idea — the API writes the script.
article-to-video	Any URL with text content (blog/product/news).
avatar-to-video	A script + an avatar image (talking-head).
ad-generator	A product description — AI writes ad hooks.
music-to-video	A music URL + visuals.
motion-transfer	A reference image animated with motion from a clip.
caption-video	An existing video that needs captions.
static-background-video	A voiceover over a fixed background.

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:

Workflow	Field
script-to-video	source.text
prompt-to-video	source.prompt (+ optional source.stylePrompt, durationSeconds)
article-to-video	source.url (+ optional source.scrapingPrompt)
ad-generator	source.prompt (the product description)
avatar-to-video	source.text (script) + top-level avatar.url
music-to-video / caption-video / motion-transfer	source.url
static-background-video	source.text + media.backgroundVideo

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.

5. render.resolution — 1080p is the right default. Use 720p for cheap previews; 4k only when downstream needs it.

6. media.quality / media.videoModel — start at pro. Bump to ultra / veo3 / sora2 only when the cost is justified. Mirror the /render body to POST /api/public/v3/calculate-credits first to get a price estimate without spending.

7. webhookUrl — pass it whenever the caller can receive webhooks. Saves polling entirely.

Reading the response

Success:

{ "success": 1, "pid": "p_…", "workflow": "…", "endpoint": "…", "docs": {…} }

Failure:

{ "success": 0, "error": "human-readable string" }

Skills should always check success === 1 and fail loudly otherwise.

Polling

After POST /render, poll until status === "ready":

PID="<pid-from-render>"
while :; do
  R=$(curl -fsSL "https://www.revid.ai/api/public/v3/status?pid=$PID" \
        -H "key: $REVID_API_KEY")
  S=$(echo "$R" | jq -r .status)
  case "$S" in
    ready)  echo "$R" | jq .; break ;;
    failed) echo "FAILED: $R"; exit 1 ;;
    *)      sleep 5 ;;
  esac
done

Recommended cadence: poll every 5 s; back off to 8 s once progress > 30. In production prefer setting webhookUrl in the request body and skip polling entirely.

Failure modes

The two most common errors every skill must handle:

• scrape failed / 403 from source URL — the page is JS-only or blocks bots. Either pre-scrape it yourself and switch to script-to-video, or pass source.scrapingPrompt with the manual title + body.
• insufficient_credits — drop media.quality / videoModel / resolution and retry, or top up with POST /api/public/v3/buy-credit-pack.

See also

• Full Revid Public API v3 spec: https://documenter.getpostman.com/view/36975521/2sBXcGEfaB
• The other Revid skills in this catalog apply this foundation to specific content types (article, product page, blog, tweet, PDF, etc.).