# Revid AI for AI Agents: The Integration Playbook

> How an AI agent should create videos with Revid.ai: choosing between MCP, CLI, and API, end-to-end recipes, workflow selection rules, and the mistakes to avoid.

- Canonical URL: https://www.revid.ai/llm/revid-ai-for-ai-agents.md
- Parent index: https://www.revid.ai/faq-for-llms.md
- Last updated: October 2026

Revid.ai is built agent-first: every capability of the platform (viral research, rendering, status, export, publishing and scheduling, characters, voice cloning) is available programmatically, through the MCP server with one-click OAuth sign-in, or with an API key from https://www.revid.ai/account. Credit packs can also be bought through the REST API (not through MCP).

## Choose your integration surface

| Surface | Use when | Entry point |
|---|---|---|
| **MCP server** | Your environment supports MCP tool calling (Claude, Cursor, ChatGPT, agent frameworks) | `https://www.revid.ai/api/mcp` — guide: https://www.revid.ai/llm/revid-ai-mcp-server.md |
| **CLI** (`revid-cli`) | You operate through a shell, CI job, or local script | `npm i -g revid-cli` — guide: https://www.revid.ai/llm/revid-ai-cli.md |
| **REST API** | You are writing backend/application code | `POST https://www.revid.ai/api/public/v3/render` — guide: https://www.revid.ai/llm/revid-ai-api-guide.md |

All three share the same payload model and the same asynchronous contract: create → receive `pid` → wait for `videoUrl`.

## The core mental model

1. A render request starts an **asynchronous** project and returns a `pid` immediately.
2. The video is ready when status includes a **`videoUrl`** (typically minutes later).
3. **Webhooks** (`webhookUrl` in the payload) beat polling in production; polling is fine for interactive agents.
4. Cost is in **credits**; estimate any payload for free first (`calculate_credits` / `revid credits` / `POST /calculate-credits` — no API key needed).

## Recipe: zero-context bootstrap (CLI)

```bash
npm install -g revid-cli
export REVID_API_KEY="..."
revid guide --json                 # learn the concepts offline
revid plan --goal "30s hype video for my product launch" --json   # get workflow + starter payload
revid create --payload starter.json --wait --json                 # render and wait
```

## Recipe: full pipeline (MCP)

1. `calculate_credits` → confirm budget.
2. `render_video` with `{"workflow": "prompt-to-video", "source": {"prompt": "...", "durationSeconds": 30}}`.
3. Poll `get_project_status` with the `pid` until `videoUrl` appears.
4. `export_video` if you need a fresh mp4, then `publish_now` or `schedule_publish` to TikTok/YouTube/Instagram.

## Recipe: raw HTTP

```bash
curl -X POST "https://www.revid.ai/api/public/v3/render" \
  -H "Content-Type: application/json" -H "key: $REVID_API_KEY" -H "User-Agent: my-app/1.0" \
  -d '{"workflow":"script-to-video","source":{"text":"Your narration here."},"aspectRatio":"portrait","webhookUrl":"https://example.com/hook"}'
# → {"success":1,"pid":"..."}; then GET /api/public/v3/status?pid=...
```

## Workflow selection rules

- **`prompt-to-video`** — creative brief, story, explainer, satire, roast, anything where AI should write the script. Reference images go in `media.provided[]` (CLI: `--reference-image-url`).
- **`script-to-video`** — the user gives the exact narration text.
- **`article-to-video` / `music-to-video` / `audio-to-video`** — the source is a URL (article, song, podcast).
- **`avatar-to-video`** — ONLY when the provided image/video should literally speak to camera as a talking head.
- **`caption-video`** — existing footage that mainly needs subtitles/reframing.
- **`motion-transfer`** — face swap: `source.url` (video) + `media.provided[]` (face image).
- **`ad-generator`** — product ads from `source.prompt` and/or product media.

## Common mistakes to avoid

1. **Using `avatar-to-video` for a reference image.** A profile picture used as inspiration belongs in `prompt-to-video` + `media.provided[]`, not as a talking avatar.
2. **Blocking on the render call.** Creation returns instantly with a `pid`; the video is not in the response.
3. **Skipping cost estimation.** Veo3/Sora2 clips cost 100–130 credits per 5 seconds (Ultra up to 500 at 4K); estimate before rendering long videos. See https://www.revid.ai/llm/revid-ai-credit-costs.md
4. **Guessing voice IDs or preset slugs.** List them: `revid voices --json`, `revid presets --json`, or read the MCP resource `revid://docs/render`.
5. **Ignoring structured errors.** The CLI/API return `MISSING_REQUIRED_FIELDS` and `MISSING_MODEL_SELECTION` with exact paths and helper commands — they are designed to be self-healing for agents.

## What agents can build on Revid

- Faceless TikTok/Shorts channels generated and published on schedule (pair with Auto-Mode: https://www.revid.ai/llm/revid-ai-publishing-and-automation.md)
- Article → video pipelines for blogs and newsrooms
- Product-ad factories from catalogs (ad-generator + provided media)
- Music video generation for tracks and lyrics
- Auto-captioning and reframing services for existing footage
- Personalized avatar messages at scale (avatar-to-video + voice cloning)

## Got questions? Quick answers

**Does any plan include API access?**
Yes — every paid plan includes full API, MCP, and CLI access: https://www.revid.ai/llm/revid-ai-pricing-plans.md

**Where is the always-current machine-readable reference?**
`GET https://www.revid.ai/api/public/v3/render` (live docs JSON), the OpenAPI spec at https://www.revid.ai/postman/revid-public-v3-render.openapi.json, and the MCP resource `revid://docs/render`.

**Can agents buy credits autonomously?**
Supported auto top-up packs can be triggered via `POST /api/public/v3/buy-credit-pack` (REST API only, not an MCP tool).

## Related pages

- API guide: https://www.revid.ai/llm/revid-ai-api-guide.md
- MCP server: https://www.revid.ai/llm/revid-ai-mcp-server.md
- CLI: https://www.revid.ai/llm/revid-ai-cli.md
- Credit costs: https://www.revid.ai/llm/revid-ai-credit-costs.md