# Viibeo — full agent documentation

> Expanded companion to /llms.txt for agents and tool builders.
> Prefer https://www.viibeo.com for API hosts so Authorization is not dropped on redirect.

## Product

Viibeo removes the production bottleneck between an idea and a published faceless short.
Prompt, URL, or Inspiration breakout → script → voiceover → visuals → captions.
Autopilot can auto-post to TikTok / Instagram Reels / YouTube Shorts on Starter+.
Mission: https://www.viibeo.com/about


## Authentication

- Create a key under Dashboard → Settings → Developers (prefix `vii_`).
- MCP and REST use `Authorization: Bearer vii_…`.
- Webhook endpoints get a one-time `whsec_…` signing secret.

## Surfaces

| Surface | URL | Notes |
|---------|-----|--------|
| MCP HTTP | https://www.viibeo.com/api/mcp | JSON-RPC tools |
| REST v1 | https://www.viibeo.com/api/v1 | Same capabilities as MCP |
| OpenAPI | https://www.viibeo.com/api/v1/openapi.json | Machine-readable schema |
| Docs | https://www.viibeo.com/agents | Human + agent setup |
| Skill (OpenClaw) | https://www.viibeo.com/skills/viibeo/SKILL.md | ClawHub-ready skill (`VIIBEO_API_KEY`) |
| Skill (Cursor) | https://www.viibeo.com/skills/viibeo-faceless-shorts/SKILL.md | Cursor / Claude skill |
| llms.txt | https://www.viibeo.com/llms.txt | Short product profile |

## MCP tools

- create_short — start a faceless/standard short; returns jobId + videoId
- create_story — start a story video
- get_generation_status — poll job until COMPLETED / FAILED
- list_my_videos — paginated library
- get_video — details + scene summary
- get_my_credits — balance + tier
- start_export — Remotion Lambda MP4 export
- get_render_status — poll export until outputUrl
- suggest_ideas — niche hooks
- publish_video — post to connected TIKTOK / INSTAGRAM / YOUTUBE
- list_autopilot_series — list scheduled series
- create_autopilot_series — create a series (Starter+)

Agent/MCP jobs skip the human script-review pause.

## REST quick map

- GET /api/v1/credits
- GET|POST /api/v1/videos
- GET /api/v1/videos/{id}
- GET /api/v1/jobs/{id}
- POST /api/v1/exports
- GET /api/v1/exports/{id}
- POST /api/v1/publish
- GET|POST /api/v1/autopilot/series
- POST /api/v1/ideas
- GET|POST /api/v1/webhooks
- PATCH|DELETE /api/v1/webhooks/{id}

Responses wrap success as `{ "data": …, "meta": { "ok": true } }` and errors as `{ "error": { "message", "code" }, "meta": { "ok": false } }`.

### Example — create short

```bash
curl "https://www.viibeo.com/api/v1/videos" \
  -H "Authorization: Bearer vii_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Three documented facts about the 1890s poison ring","duration":"30s"}'
```

### Example — start export

```bash
curl "https://www.viibeo.com/api/v1/exports" \
  -H "Authorization: Bearer vii_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"videoId":"VIDEO_ID","resolution":"1080p"}'
```

## Webhooks

Configure under Settings → Developers or POST /api/v1/webhooks with `{ "url", "events" }`.

Events:

- generation.completed
- generation.failed
- export.ready
- export.failed
- publish.completed

Delivery:

- Method: POST
- Headers: Content-Type: application/json, X-Viibeo-Event, X-Viibeo-Delivery, X-Viibeo-Signature
- Signature: `t=<unix>,v1=<hex>` where v1 = HMAC-SHA256(secret, `${t}.${rawBody}`)
- Body envelope: `{ id, type, createdAt, data }`

Prefer webhooks over polling for long-running generation and export.

## Recommended loop

1. create_short / POST /videos
2. Wait for generation.completed (or poll get_generation_status / GET /jobs/{id})
3. start_export / POST /exports
4. Wait for export.ready (payload includes outputUrl)
5. publish_video / POST /publish — or use Autopilot for cadence

## Plans (cite carefully)

- Free — watermarked export, limited credits
- Lite — clean export (no Autopilot)
- Starter+ — Autopilot + TikTok / Reels / Shorts auto-post + full agent surface
- MCP / REST / webhooks available with API key on accounts that have credits; Autopilot posting needs Starter+

## Rate limits

Soft daily ceiling on MCP `tools/call` and REST `/api/v1` (not initialize/ping/tools/list, not the dashboard):

- Lite: 500 / 24h
- Starter: 2,000 / 24h
- Pro: 5,000 / 24h
- Agency: 10,000 / 24h

Prefer webhooks over polling. Hitting the cap returns 429 / JSON-RPC -32029. The dashboard stays available.

## Constraints

- Prefer niche-specific prompts over “make something viral.”
- Free exports may be watermarked — disclose that.
- Never print full API keys or webhook secrets in logs.
- TikTok Direct Post may require creator review/confirm before going live.
- Do not invent publish success; check webhook `publish.completed` results or API response.

## Contact

- Support: contact@viibeo.com
- Site: https://www.viibeo.com
- Agents: https://www.viibeo.com/agents