API Reference

Base URL

https://api.vidjutsu.ai

Authentication

Most endpoints require an API key passed as a Bearer token in the Authorization header:

curl https://api.vidjutsu.ai/v1/clones/check \
  -H "Authorization: Bearer vj_live_your_key_here"

Get your API key by subscribing with any card via Stripe.

Endpoints

Clone

The clone workflow. Each clone endpoint shares one daily admission limit. See the clone viral videos guide for the full sequence.

Method	Endpoint	Description
POST	`/v1/clones/check`	Score whether a source video will clone well (verdict + 0-100 score)
POST	`/v1/characters`	Create a reusable character (`char_...`)
GET	`/v1/characters`	List your characters
GET	`/v1/characters/{id}`	Fetch one character by id
POST	`/v1/clones/starting-image`	Compose a clean character-swapped starting frame
POST	`/v1/clones/video`	Submit the motion clone, returns a task id
GET	`/v1/clones/video/{id}`	Poll the clone task for the finished video

Download

Stage one video’s file to the CDN, one call per video.

Method	Endpoint	Description	Calls / day
POST	`/v1/videos/download/tiktok`	Stage a TikTok video’s file	metered
POST	`/v1/videos/download/instagram`	Stage an Instagram video’s file	metered

Discovery (scrape)

Metadata and discovery only. Scrape returns raw source URLs and never stages media. All scrape endpoints share one daily rate group (500/day). See scrape.

Method	Endpoint	Description
POST	`/v1/scrape/tiktok/trending`	Trending feed by region
POST	`/v1/scrape/tiktok/profile/videos`	Videos for a TikTok profile
POST	`/v1/scrape/tiktok/video`	Single TikTok video metadata
POST	`/v1/scrape/instagram/user/reels`	Reels for an Instagram profile
POST	`/v1/scrape/instagram/post`	Single Instagram post metadata

Full scrape list on the scrape page.

Processing

Each processing endpoint has its own daily rate-limit bucket. Buckets are independent.

Method	Endpoint	Description	Calls / day
POST	`/v1/watch`	AI watches video, freeform prompt	50
POST	`/v1/extract`	Pull frames, audio, metadata	100
POST	`/v1/transcribe`	Speech-to-text with word timing	30
POST	`/v1/compliance/video`	Scan a video against platform TOS	20
POST	`/v1/compliance/prompt`	Scan text against platform TOS	100
POST	`/v1/overlay`	Burn text overlay onto a video	50
POST	`/v1/disclaimer`	Burn a disclaimer card onto a video	50
POST	`/v1/check`	Validate a spec against rules	100
GET	`/v1/check/rules`	Load per-client custom rules	unmetered
PUT	`/v1/check/rules`	Save per-client custom rules	unmetered

Storage

Storage endpoints are unmetered under your subscription.

Method	Endpoint	Description
POST	`/v1/upload`	Upload media to CDN
POST	`/v1/upload/url`	Upload from external URL
POST/GET/PUT/DELETE	`/v1/accounts`	Manage account records (supports tag filtering)
POST/GET/PUT/DELETE	`/v1/posts`	Manage post records
POST/GET/PUT/DELETE	`/v1/references`	Manage reference records
POST/GET/PUT/DELETE	`/v1/assets`	Manage asset records
POST/GET/PUT/DELETE	`/v1/projects`	Manage serializable editor timeline projects

Billing & Keys

Method	Endpoint	Description
POST	`/v1/subscribe`	Start a subscription checkout session
GET	`/v1/credits/status`	Poll checkout status, retrieve API key
GET	`/v1/usage`	Remaining daily capacity per endpoint
GET	`/v1/pricing`	Current pricing + limits table
POST	`/v1/api_keys/rotate`	Rotate your API key
POST	`/v1/api_keys/recover`	Recover a lost API key
GET	`/v1/info`	API discovery + endpoint catalog

Response codes

Code	Description
`200`	Success (read operations, edits)
`201`	Created (new records)
`202`	Accepted (async operation started)
`400`	Missing or invalid parameters
`401`	Missing or invalid API key
`403`	Subscription inactive or expired (`subscription_required`)
`422`	Unprocessable request (for example `video_too_long` on a clone over 15 seconds)
`429`	Daily rate limit reached

Error format

All errors return a consistent JSON structure. On 429, the response includes retryAfter (seconds until the bucket resets at 00:00 UTC):

{
  "error": "rate_limited",
  "message": "Daily limit reached for watch (50/day). Resets at midnight UTC.",
  "limit": 50,
  "retryAfter": 14523
}

Synchronous and async responses

Most endpoints return a synchronous 200 with the result in the body. The clone video call is asynchronous: POST /v1/clones/video returns 202 with a task id, which you poll with GET /v1/clones/video/{id}.

CORS

The REST API allows cross-origin requests from any origin. Public integrations should send Content-Type and Authorization; idempotent operations may also use Idempotency-Key.

Versioning

Responses include the VidJutsu-Version header indicating the current API version.

Overview

Clone

Download

Billing & Keys

Auth

Agent Auth (auth.md)

Processing

Compliance

Check Rules

Upload

Assets

Accounts

Posts

References

Editor Projects

Scrape

Base URL

Authentication

Endpoints

Clone

Download

Discovery (scrape)

Processing

Storage

Billing & Keys

Tags

Response codes

Error format

Synchronous and async responses

CORS

Versioning

​Base URL

​Authentication

​Endpoints

​Clone

​Download

​Discovery (scrape)

​Processing

​Storage

​Billing & Keys

​Tags

​Response codes

​Error format

​Synchronous and async responses

​CORS

​Versioning

Base URL

Authentication

Endpoints

Clone

Download

Discovery (scrape)

Processing

Storage

Billing & Keys

Tags

Response codes

Error format

Synchronous and async responses

CORS

Versioning