# ViralClaw API

> The first SaaS built for AI agents. Transform videos into viral shorts with AI-powered captions via a simple REST API.

ViralClaw is a video captioning API designed specifically for AI agents and automation workflows. Send a video URL, choose a caption style, and receive a captioned viral short — all via API. No UI required.

## Pricing

- 3 free credits on signup (no credit card)
- $29 for 200 credits (one-time purchase, credits never expire)
- 1 credit = 1 minute of video (rounded up)
- Refund available if fewer than 10 credits used

## Authentication

All API requests require the `X-API-Key` header. Get your key at signup.

## Base URL

```
https://api.viral-claw.com/api/v1
```

## Endpoints

### Account & Credits

- `GET /api/v1/credits` — Check credit balance, plan, and rate limit
- `GET /api/v1/me` — Full account info with today's usage
- `GET /api/v1/styles` — List available caption styles
- `GET /api/v1/usage?days=7` — Usage history with daily breakdown

### Video Processing

- `POST /api/v1/add-captions` — Add captions to a single video (multipart/form-data)
  - Fields: `video_url` or `video` (file), `style`, `language`, `webhook_url`, `priority`
  - Returns: `{"job_id": 42}`

- `POST /api/v1/generate-shorts` — Full pipeline: long video → multiple viral shorts
  - Fields: `video_url` or `video` (file), `style`, `language`, `count` (1-20), `webhook_url`, `priority`
  - Returns: `{"job_id": 43}`

### Jobs

- `GET /api/v1/jobs/{job_id}` — Poll job status
  - Status values: `queued`, `processing`, `done`, `failed`
  - When done: includes `output_url` (public download link)

### Shorts Management

- `GET /api/v1/shorts?page=1&per_page=20&status=done` — List your shorts (paginated)
- `GET /api/v1/shorts/{short_id}` — Get single short with signed download URL
- `DELETE /api/v1/shorts/{short_id}` — Delete a short

### Health

- `GET /health` — API health check (no auth required)

## Caption Styles

| Style ID  | Name     | Description                        |
|-----------|----------|------------------------------------|
| hormozi   | Hormozi  | Bold, high-contrast, keyword highlights |
| mrbeast   | MrBeast  | Rainbow gradient, maximum impact   |
| tiktok    | TikTok   | Glowing neon, trendy vibes         |
| minimal   | Minimal  | Clean, elegant, professional       |
| karaoke   | Karaoke  | Word-by-word highlight             |

## Rate Limits

- Free: 10 requests/minute
- Paid: 30 requests/minute
- Returns HTTP 429 with `Retry-After` header when exceeded

## Error Codes

| Status | Meaning                                         |
|--------|-------------------------------------------------|
| 400    | Bad request (invalid style, missing video, etc) |
| 401    | Invalid or missing API key                      |
| 402    | Insufficient credits                            |
| 403    | Feature not available on your plan              |
| 404    | Job or short not found                          |
| 429    | Rate limit exceeded                             |
| 500    | Server error                                    |

Error response format: `{"detail": "Insufficient credits: need 5, have 2"}`

## Webhooks

When a job completes, ViralClaw sends a POST request to your `webhook_url` with the full job result including `output_url`. Include `webhook_token` in your request to receive it back in the webhook header for verification.

## Quick Start

```bash
# 1. Check your balance
curl -H "X-API-Key: YOUR_KEY" https://api.viral-claw.com/api/v1/credits

# 2. Submit a video
curl -X POST https://api.viral-claw.com/api/v1/add-captions \
  -H "X-API-Key: YOUR_KEY" \
  -F "video_url=https://example.com/video.mp4" \
  -F "style=hormozi"

# 3. Check job status
curl -H "X-API-Key: YOUR_KEY" https://api.viral-claw.com/api/v1/jobs/42
```

## OpenClaw Skill

Install: `openclaw skill install viralclaw`

The skill is open source and fully auditable. No shell execution, no filesystem access outside /tmp, no credential harvesting.

## Links

- [API Documentation](https://api.viral-claw.com/)
- [OpenClaw Skill (GitHub)](https://github.com/viralclaw/openclaw-skill)
- [Pricing](https://api.viral-claw.com/#pricing)