Skill: vizardai/vizard-api-skills (version 1.0.0)

--- name: using-vizard-api description: Use when needing to clip long videos into short social media clips, edit short videos with subtitles or b-roll, publish clips to social platforms, or generate AI captions using Vizard.ai API. Use when user asks to automate video content creation with Vizard. --- # Using Vizard.ai API ## Overview Vizard API converts long videos into AI-clipped short videos optimized for TikTok, YouTube Shorts, and Instagram Reels. It also edits short videos with subtitles, B-roll, and branding. All endpoints use REST + JSON. **Base URL:** `https://elb-api.vizard.ai/hvizard-server-front/open-api/v1` **Auth header:** `VIZARDAI_API_KEY: YOUR_API_KEY` **Requires paid Vizard plan.** ## Core Workflow ``` Submit Video → Poll for Results → (Optional) Publish / Generate Caption ``` ### Step 1: Submit a Video **Mode A — Clip a long video** (returns multiple clips): ```python import requests, time headers = { "Content-Type": "application/json", "VIZARDAI_API_KEY": "YOUR_API_KEY" } resp = requests.post( "https://elb-api.vizard.ai/hvizard-server-front/open-api/v1/project/create", headers=headers, json={ "videoUrl": "https://www.youtube.com/watch?v=XXXXX", "videoType": 2, # 2=YouTube, 1=direct file, 3=GDrive, 4=Vimeo "lang": "en", # or "auto" for auto-detect "preferLength": [0] # 0=auto, 1=<30s, 2=30-60s, 3=60-90s, 4=>90s } ) project_id = resp.json()["projectId"] ``` **Mode B — Edit a short video** (≤3 min, returns 1 edited video): ```python resp = requests.post( "https://elb-api.vizard.ai/hvizard-server-front/open-api/v1/project/create", headers=headers, json={ "videoUrl": "https://example.com/video.mp4", "videoType": 1, "ext": "mp4", "lang": "auto", "getClips": 0, # 0 = editing mode "subtitleSwitch": 1, "headlineSwitch": 1, "autoBrollSwitch": 1, "removeSilenceSwitch": 1, "ratioOfClip": 1 # 1=9:16, 2=1:1, 3=4:5, 4=16:9 } ) project_id = resp.json()["projectId"] ``` ### Step 2: Poll for Results (every 30 seconds) ```python def wait_for_clips(project_id, api_key, max_wait=1200): headers = {"VIZARDAI_API_KEY": api_key} url = f"https://elb-api.vizard.ai/hvizard-server-front/open-api/v1/project/query/{project_id}" for _ in range(max_wait // 30): time.sleep(30) r = requests.get(url, headers=headers).json() if r["code"] == 2000 and r.get("videos"): return r["videos"] # list of clip objects if r["code"] not in (2000, 1000): raise RuntimeError(f"Error: {r}") raise TimeoutError("Processing timed out") clips = wait_for_clips(project_id, "YOUR_API_KEY") # Each clip: videoId, videoUrl (valid 7 days), title, transcript, viralScore ``` ### Step 3 (Optional): Publish to Social Media ```python # First get connected account IDs accounts = requests.get( "https://elb-api.vizard.ai/hvizard-server-front/open-api/v1/project/social-accounts", headers={"VIZARDAI_API_KEY": "YOUR_API_KEY"} ).json()["accounts"] # Then publish requests.post( "https://elb-api.vizard.ai/hvizard-server-front/open-api/v1/project/publish-video", headers={**headers}, json={ "finalVideoId": clips[0]["videoId"], "socialAccountId": accounts[0]["id"], "post": "" # empty = AI auto-generates caption + hashtags } ) ``` ### Step 3 (Optional): Generate AI Social Caption ```python resp = requests.post( "https://elb-api.vizard.ai/hvizard-server-front/open-api/v1/project/ai-social", headers=headers, json={ "finalVideoId": clips[0]["videoId"], "aiSocialPlatform": 2, # 1=General,2=TikTok,3=Instagram,4=YouTube,5=Facebook,6=LinkedIn,7=Twitter "tone": 2, # 0=Neutral,1=Interesting,2=Catchy,3=Serious,4=Question "voice": 0 # 0=First person, 1=Third person } ) caption = resp.json()["aiSocialContent"] ``` ## Quick Reference See `api-reference.md` for full parameter tables, videoType values, status codes, and editing options. ### Supported Video Sources (`videoType`) | Value | Source | |-------|--------| | 1 | Direct file URL (.mp4/.mov/.avi/.3gp) — also requires `ext` | | 2 | YouTube | | 3 | Google Drive | | 4 | Vimeo | | 5 | StreamYard | | 6 | TikTok | | 7 | Twitter | | 9 | Twitch | | 10 | Loom | | 11 | Facebook | | 12 | LinkedIn | ### Key Status Codes | Code | Meaning | |------|---------| | 2000 | Success | | 1000 | Still processing (keep polling) | | 4001 | Invalid API key | | 4003 | Rate limit exceeded | | 4007 | Insufficient account time/credits | | 4008 | Failed to download video | ## Common Mistakes - **Not waiting long enough:** 4K or long videos can take 10-30 min. Poll every 30s; don't give up after a few retries. - **Using `getClips: 0` for a long video:** Editing mode only works for videos ≤3 minutes. - **Missing `ext` for direct files:** `videoType: 1` requires `"ext": "mp4"` (or other format). - **`videoUrl` expires after 7 days:** Re-query the API to get a fresh download link. - **Social caption won't work on silent videos:** `ai-social` endpoint requires spoken dialogue.

path: api-reference.md
content: # Vizard API — Full Reference

## Endpoints Summary

| Method | Path | Purpose |
|--------|------|---------|
| POST | `/project/create` | Submit video for clipping or editing |
| GET | `/project/query/{projectId}` | Poll for results |
| GET | `/project/social-accounts` | List connected social accounts |
| POST | `/project/publish-video` | Publish clip to social media |
| POST | `/project/ai-social` | Generate AI social caption |

---

## POST /project/create — Submit Video

### Required Parameters (both modes)

| Field | Type | Description |
|-------|------|-------------|
| `videoUrl` | string | URL of the video source |
| `videoType` | int | Source platform (see table in SKILL.md) |
| `lang` | string | Language code or `"auto"`. Full list: [supported languages](https://docs.vizard.ai/docs/supported-languages) |
| `ext` | string | **Required only for `videoType: 1`** — file extension: `mp4`, `mov`, `avi`, `3gp` |

### Clipping Mode Parameters (long video → multiple clips)

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `preferLength` | int[] | [0] | Clip length preference: 0=auto, 1=<30s, 2=30-60s, 3=60-90s, 4=>90s |
| `getClips` | int | 1 | 1 = clipping mode (default), 0 = editing mode |
| `projectName` | string | auto | Custom project name |
| `webhookUrl` | string | — | POST callback URL when processing completes |

### Editing Mode Parameters (short video ≤3min → 1 enhanced video)

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `getClips` | int | — | **Must be 0** for editing mode |
| `ratioOfClip` | int | 1 | Output ratio: 1=9:16, 2=1:1, 3=4:5, 4=16:9 |
| `subtitleSwitch` | int | 1 | 0=hide subtitles, 1=show |
| `emojiSwitch` | int | 0 | 0=no emoji, 1=auto-add emoji in subtitles |
| `highlightSwitch` | int | 0 | 0=off, 1=auto-highlight key words |
| `autoBrollSwitch` | int | 0 | 0=off, 1=AI-generated B-roll |
| `headlineSwitch` | int | 1 | 0=no headline hook, 1=show |
| `removeSilenceSwitch` | int | 0 | 0=off, 1=remove silence and filler words |
| `templateId` | long | — | Apply a branding template (ratio must match `ratioOfClip`) |
| `projectName` | string | auto | Custom project name |

### Response

```json
{ "code": 2000, "projectId": 17861706 }
```

---

## GET /project/query/{projectId} — Poll Results

### Response Fields

| Field | Type | Description |
|-------|------|-------------|
| `code` | int | 2000=success, 1000=still processing |
| `projectId` | long | Project ID |
| `projectName` | string | Project name |
| `shareLink` | string | Shareable project link (Business/Team plan only) |
| `videos` | array | List of output clips (sorted by viral score) |

### `videos` Object

| Field | Type | Description |
|-------|------|-------------|
| `videoId` | long | Clip ID (use for publish/caption APIs) |
| `videoUrl` | string | Download URL — **valid 7 days only** |
| `videoMsDuration` | long | Duration in milliseconds |
| `title` | string | AI-generated title |
| `transcript` | string | Full speech transcript |
| `viralScore` | string | Engagement score 0–10 (clipping mode only) |
| `viralReason` | string | Why this clip is engaging |
| `relatedTopic` | string | Stringified JSON array of keywords |
| `clipEditorUrl` | string | Web editor URL for this clip |

### Status Codes

| Code | Meaning |
|------|---------|
| 2000 | Success |
| 1000 | Still processing |
| 4001 | Invalid API key |
| 4002 | Clipping failed |
| 4003 | Rate limit exceeded |
| 4004 | Unsupported video format |
| 4005 | Invalid URL (clipping mode) or video too long (editing mode) |
| 4006 | Illegal parameter |
| 4007 | Insufficient account time/credits |
| 4008 | Failed to download video |

---

## GET /project/social-accounts — List Social Accounts

### Response

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Use as `socialAccountId` when publishing |
| `platform` | string | Platform name (Instagram, TikTok, etc.) |
| `username` | string | Connected account username |
| `status` | string | `active`, `expired`, `locked`, `not connected` |
| `expiresAt` | long | Unix timestamp (ms) when auth expires |

---

## POST /project/publish-video — Publish to Social Media

### Parameters

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `finalVideoId` | long | ✅ | `videoId` from query response |
| `socialAccountId` | string | ✅ | From social-accounts endpoint |
| `post` | string | ❌ | Post caption. Empty string = AI auto-generates |
| `publishTime` | long | ❌ | Unix timestamp (ms) for scheduled publish. Omit = publish now |
| `title` | string | ❌ | YouTube only. Empty = AI-generated title |

### Platform Character Limits

| Platform | Limit |
|----------|-------|
| TikTok | 2,200 |
| Instagram | 2,200 |
| Facebook | 2,200 |
| LinkedIn | 3,000 |
| YouTube | 5,000 (post), 100 (title) |
| Twitter/X | 280 |

### Status Codes

| Code | Meaning |
|------|---------|
| 2000 | Publish succeeded |
| 4004 | Feature requires plan upgrade |
| 4011 | Invalid social account ID |

---

## POST /project/ai-social — Generate AI Caption

**Note:** Only works for videos with spoken dialogue.

### Parameters

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `finalVideoId` | long | ✅ | `videoId` from query response |
| `aiSocialPlatform` | int | ❌ | 1=General(default), 2=TikTok, 3=Instagram, 4=YouTube, 5=Facebook, 6=LinkedIn, 7=Twitter |
| `tone` | int | ❌ | 0=Neutral(default), 1=Interesting, 2=Catchy, 3=Serious, 4=Question |
| `voice` | int | ❌ | 0=First person(default), 1=Third person |

### Response

| Field | Type | Description |
|-------|------|-------------|
| `aiSocialContent` | string | Generated caption text with hashtags |
| `aiSocialTitle` | string | AI YouTube title (only for `aiSocialPlatform: 4`) |

### Status Codes

| Code | Meaning |
|------|---------|
| 2000 | Success |
| 4002 | No speech/dialogue detected |
| 4006 | Illegal parameter |

---

## Supported Languages (partial)

`auto`, `en`, `es`, `pt`, `fr`, `de`, `ru`, `zh`, `ja`, `ko`, `ar`, `hi`, `it`, `nl`, `pl`, `tr`

Full list: https://docs.vizard.ai/docs/supported-languages

---

## Rate Limits & Pricing

- See: https://docs.vizard.ai/docs/rate-limit
- See: https://docs.vizard.ai/docs/pricing


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)