---
name: vidguy-api
description: >
  Interact with the VidGuy public REST API to create videos, upload and analyze
  long-form clips, render selected clip candidates, poll async jobs, inspect
  credit balance and transactions, top up credits via x402 payment, list
  available offerings and templates, and cancel queued work. Use when the user
  asks to call the VidGuy API, create a video programmatically, integrate with
  VidGuy, check API credits, poll a job, upload a clip for analysis, render
  clips, use x402, build an API client, or automate video production through
  HTTP requests. Triggers on: VidGuy API, REST API, API key, API integration,
  programmatic video, clip analysis API, x402 credits, Bearer token, curl
  vidguy, /api/v1, offerings endpoint, poll job status.
allowed-tools: Read, Grep, Glob, Bash
---

# VidGuy Public API

Base URL: `https://www.vidguy.ai/api/v1`

## Authentication

Every request requires a Bearer API key:

```http
Authorization: Bearer vf_live_YOUR_API_KEY
Content-Type: application/json
```

Set `VIDGUY_API_KEY` in the environment before running examples.

## Endpoints at a glance

| Method | Path | Purpose |
|--------|------|---------|
| POST | `/jobs` | Create a job (video, clip analysis, or clip render) |
| GET | `/jobs/{id}` | Poll job status |
| POST | `/videos` | Create video (legacy compatibility) |
| GET | `/videos` | List videos |
| GET | `/videos/{id}` | Get video detail |
| DELETE | `/videos/{id}` | Cancel a queued video |
| GET | `/credits` | Check balance and recent transactions |
| POST | `/credits/topup` | Top up credits with x402 |
| GET | `/offerings` | List supported offerings |
| GET | `/templates` | List template metadata |
| POST | `/uploads` | Create a presigned upload URL |

## Workflow A: Create a video

1. Check balance: `GET /credits`
2. Create job:

```bash
curl -X POST https://www.vidguy.ai/api/v1/jobs \
  -H "Authorization: Bearer $VIDGUY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "offeringId": "video_production",
    "input": {
      "topic": "Five ways founders can use AI agents this week",
      "durationSeconds": 30,
      "platform": "tiktok",
      "videoType": "faceless"
    }
  }'
```

3. Poll `GET /jobs/{jobId}` every 5-10 s until `completed`, `failed`, or `cancelled`.

### video_production input fields

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| topic | string | yes | 3-5000 chars |
| durationSeconds | number | yes | 10, 15, 30, 45, or 60 |
| platform | string | yes | tiktok, reels, shorts, youtube, linkedin |
| videoType | string | yes | faceless, whiteboard, ugc, brainrot |
| ugc | object | when ugc/brainrot | Character and scene settings |
| contentSources | object | no | URLs, scripts, or reference material |
| audio | object | no | Voice, music, sound effect preferences |
| style | object | no | Visual style; use `visualStyle: "chalkboard"` for board mode |
| brand | object | no | Brand colors, logo, fonts |
| templateId | string | no | Template ID from `/templates` |
| additionalInstructions | string | no | Max 500 chars |

## Workflow B: Clip analysis and render

1. Get a signed upload URL:

```bash
curl -X POST https://www.vidguy.ai/api/v1/uploads \
  -H "Authorization: Bearer $VIDGUY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileName":"episode.mp4","fileType":"video/mp4","fileSize":10485760}'
```

2. Upload the file to the returned `uploadUrl` with a PUT request.
3. Start analysis:

```bash
curl -X POST https://www.vidguy.ai/api/v1/jobs \
  -H "Authorization: Bearer $VIDGUY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "offeringId": "clip_analysis_upload",
    "input": {
      "r2Key": "<r2Key from upload response>",
      "fileName": "episode.mp4",
      "contentType": "video/mp4",
      "preferences": {
        "clipCount": 3,
        "maxClipSeconds": 30,
        "hookFocus": "high-energy"
      }
    }
  }'
```

4. Poll until `awaiting_selection`. The response `result.candidates` array contains clip options.
5. Render selected candidates:

```bash
curl -X POST https://www.vidguy.ai/api/v1/jobs \
  -H "Authorization: Bearer $VIDGUY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "offeringId": "clip_render",
    "input": {
      "analysisJobId": "<jobId from step 3>",
      "candidateIds": ["<candidate-uuid-1>", "<candidate-uuid-2>"]
    }
  }'
```

6. Poll until `completed`. Result contains rendered clip URLs.

### hookFocus values

`big-reveals` | `high-energy` | `concise-explainers` | `surprise-moments` | `story-payoff`

## Workflow C: x402 credit top-up

1. Request top-up:

```bash
curl -X POST https://www.vidguy.ai/api/v1/credits/topup \
  -H "Authorization: Bearer $VIDGUY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"credits": 10, "paymentMethod": "x402"}'
```

2. If response is `402`, read the `accepts` array for payment requirements.
3. Complete the payment using the provided x402 requirement (scheme, network, asset, amount, payTo).
4. Retry the same request with `X-PAYMENT` or `PAYMENT-SIGNATURE` header.

## Job states

| State | Terminal | Meaning |
|-------|----------|---------|
| `queued` | no | Accepted, waiting to start |
| `processing` | no | Actively running |
| `awaiting_selection` | no | Clip analysis ready for user selection |
| `completed` | yes | Final output ready |
| `failed` | yes | Workflow failed |
| `cancelled` | yes | Cancelled by user |

## Error handling

All errors return: `{ "error": "...", "message": "...", "details": {} }`

| Status | Retry? | Meaning |
|--------|--------|---------|
| 400 | no | Invalid input |
| 401 | no | Bad or missing API key |
| 402 | payment | Insufficient credits or x402 payment flow |
| 403 | no | Not authorized |
| 404 | no | Resource not found |
| 429 | backoff | Rate limit (Pro: 30/min, Enterprise: 100/min) |
| 502/503 | backoff | Upstream or pipeline unavailable |

## Guardrails

- Prefer `/jobs` for new integrations. Treat `/videos` as a legacy compatibility path.
- Use upload-based clip analysis only. Do not use YouTube ingestion in the public API.
- Stop polling when status is `completed`, `failed`, or `cancelled`.
- Back off polling gradually if a job takes longer than expected.

## Advanced reference

- **Full endpoint schemas and response shapes**: See [references/endpoints.md](references/endpoints.md)
- **OpenAPI spec**: `https://www.vidguy.ai/api/openapi.json`
- **Interactive docs**: `https://www.vidguy.ai/docs/api-reference`