---
name: viibeo
description: >
  Create, poll, export, and publish faceless TikTok/Reels/Shorts with the Viibeo
  Agent REST API (or MCP). Use when the user wants AI short-form video without
  filming, a daily faceless channel, Autopilot scheduling, or to automate Viibeo
  from OpenClaw / any agent with HTTP tools.
version: 1.0.0
homepage: https://www.viibeo.com/agents
metadata:
  openclaw:
    requires:
      env:
        - VIIBEO_API_KEY
      bins:
        - curl
    primaryEnv: VIIBEO_API_KEY
    envVars:
      - name: VIIBEO_API_KEY
        required: true
        description: API key from Viibeo Dashboard → Settings → Developers (prefix vii_)
      - name: VIIBEO_BASE_URL
        required: false
        description: Override API host (default https://www.viibeo.com)
---

# Viibeo — faceless shorts for agents

Viibeo turns a prompt into a faceless short (script → voiceover → visuals → captions → MP4).
This skill uses the **public Agent REST API**. Prefer webhooks over busy polling when the
user can receive callbacks.

## Prerequisites

1. Account: https://www.viibeo.com/login
2. API key (`vii_…`): Dashboard → Settings → Developers
3. Credits on the account (Free exports may be watermarked; Lite+ for clean MP4)
4. Set `VIIBEO_API_KEY` in the environment. Never print the full key in chat logs.

Always call **`https://www.viibeo.com`** (not the apex). Apex redirects can drop `Authorization`.

```bash
export VIIBEO_BASE_URL="${VIIBEO_BASE_URL:-https://www.viibeo.com}"
export AUTH="Authorization: Bearer ${VIIBEO_API_KEY}"
```

OpenAPI: `${VIIBEO_BASE_URL}/api/v1/openapi.json`  
Human docs: https://www.viibeo.com/agents  
Detailed curl recipes: see `references/rest-api.md`

## When to use

- User asks to make a TikTok / Reel / Short without filming
- Automate a niche channel (scary facts, true crime, money tips, etc.)
- Check credits, list videos, export MP4, or publish to connected socials
- Set up Autopilot series or outbound webhooks

## Default workflow (one short)

1. **Credits** — `GET /api/v1/credits`
2. **Create** — `POST /api/v1/videos` with a concrete niche prompt (not “make a viral video”)
3. **Wait** — webhook `generation.completed`, or poll `GET /api/v1/jobs/{jobId}` until `COMPLETED`
4. **Export** — `POST /api/v1/exports` with `videoId`
5. **Wait** — webhook `export.ready`, or poll `GET /api/v1/exports/{jobId}` for `outputUrl`
6. **Optional** — `POST /api/v1/publish` to connected `TIKTOK` / `INSTAGRAM` / `YOUTUBE`

### Create (example)

```bash
curl -sS -X POST "${VIIBEO_BASE_URL}/api/v1/videos" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{
    "prompt": "True crime: three facts about the 1890s poison ring that sound fake but are documented. Faceless documentary tone.",
    "type": "Faceless",
    "duration": "15s",
    "mediaSource": "AI Images",
    "captionStyle": "hormozi"
  }'
```

Save `jobId` and `videoId` from the `201` response.

### Poll generation

```bash
curl -sS "${VIIBEO_BASE_URL}/api/v1/jobs/${JOB_ID}" -H "$AUTH"
```

Stop when status is `COMPLETED` (or fail on `FAILED`). Agent/MCP jobs skip interactive script review.

### Export MP4

```bash
curl -sS -X POST "${VIIBEO_BASE_URL}/api/v1/exports" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{"videoId":"'"${VIDEO_ID}"'","resolution":"1080p","quality":80}'
```

Then poll `GET /api/v1/exports/{jobId}` until you have `outputUrl`.

## Prompt tips

- One niche, one claim, one hook style.
- Prefer `15s` or `30s` for first tests. Allowed: `15s`, `30s`, `1m`, `2m`, `3m`.
- `type`: `Faceless` (default) or `Story`.
- `mediaSource`: `AI Images` (fast), `AI Video`, or `Stock Footage`.
- Before creating, you can `POST /api/v1/ideas` with `{ "niche": "psychology", "count": 5 }`.

## Webhooks (preferred)

```bash
curl -sS -X POST "${VIIBEO_BASE_URL}/api/v1/webhooks" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/hooks/viibeo",
    "events": [
      "generation.completed",
      "generation.failed",
      "export.ready",
      "export.failed",
      "publish.completed"
    ]
  }'
```

Store the returned `secret` once. Prefer waiting on these events instead of tight poll loops.

## MCP alternative

If the runtime supports HTTP MCP, you can use the same key against:

`POST` tools on `https://www.viibeo.com/api/mcp` with header `Authorization: Bearer vii_…`

Tool names mirror OpenAPI operationIds (`create_short`, `get_generation_status`, `start_export`, …). Prefer REST from this skill unless MCP is already connected.

## Limits & safety

- Free tier exports may include a watermark — tell the user if they are on Free.
- Never echo or log the full API key.
- Publishing requires platforms already connected in the Viibeo dashboard.
- Autopilot series creation may require an Autopilot-capable plan.
- Do not invent endpoints; when unsure, refetch OpenAPI.

## Install (OpenClaw / ClawHub)

After this skill is published:

```bash
openclaw skills install @OWNER/viibeo
# or
clawhub install @OWNER/viibeo
```

Local path install for development:

```bash
clawhub install ./public/skills/viibeo
```