> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vidjutsu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Clone viral videos

> Take a viral TikTok or Instagram video, check it's cloneable, and generate your own version with a swapped identity.

# Your agent can clone viral videos now

Cloning takes a public TikTok or Instagram video, evaluates whether its motion and framing will transfer cleanly, and generates a new video with your character performing the same motion. Create your character once, then reuse its id on every clone.

<Info>
  Need an API key? Follow [Get your API key](/get-api-key) first.
</Info>

## Before you start

* All URLs passed between steps must be `https://`. Plain `http://` is rejected.
* TikTok and Instagram links are not directly fetchable by the generation providers. Stage the source first with `POST /v1/videos/download/tiktok` or `POST /v1/videos/download/instagram` — every later step takes the staged VidJutsu URL, not the original platform link.
* Source clips are capped at 15 seconds. A longer `sourceVideoUrl` passed to `POST /v1/clones/video` is rejected with a 422 and `error: "video_too_long"`.
* `POST /v1/clones/check` accepts source videos up to about 2 minutes for the cloneability read, but the actual clone call is still capped at 15 seconds, so trim or pick a short segment before generating.
* Starting images returned by `POST /v1/clones/starting-image` are guaranteed clean: no captions, watermarks, or platform UI, regardless of what the source frame or your prompt asked for.
* `model` defaults to `"kling"` (Kling motion control, keeps the original sound). Pass `model: "seedance"` for the alternate model, which renders 9:16 at 480p through video-edit.
* Characters are a persisted, reusable resource. Create one once, keep its `id`, and pass that `id` into every clone from then on instead of regenerating a character each time.

## Create your character first

Before you clone anything, create the character you want to appear in your clones. This only needs to happen once.

```bash theme={null}
curl -X POST https://api.vidjutsu.ai/v1/characters \
  -H "Authorization: Bearer $VIDJUTSU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A friendly host in their late 20s, casual streetwear, warm studio lighting"
  }'
```

```json theme={null}
{
  "id": "char_2a91b7f4",
  "imageUrl": "https://cdn.vidjutsu.ai/characters/chr_2a91.../image.png",
  "model": "nano-banana-2"
}
```

`referenceImageUrl` is optional if you already have a face or identity image to guide the generation; without it, the character comes purely from `prompt`. The call is synchronous and shares the daily clone admission limit. Save `id`: it is what you pass to every clone that should use this character, so you only create it once.

To see the characters you've already created, list them:

```bash theme={null}
curl https://api.vidjutsu.ai/v1/characters \
  -H "Authorization: Bearer $VIDJUTSU_API_KEY"
```

Or fetch one directly by id:

```bash theme={null}
curl https://api.vidjutsu.ai/v1/characters/char_2a91b7f4 \
  -H "Authorization: Bearer $VIDJUTSU_API_KEY"
```

**Errors**: `403 subscription_required`, `429` on the shared clone admission limit. `404` if the character id doesn't exist or belongs to another tenant.

## The clone calls

### 1. Stage the source video

```bash theme={null}
curl -X POST https://api.vidjutsu.ai/v1/videos/download/tiktok \
  -H "Authorization: Bearer $VIDJUTSU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.tiktok.com/@creator/video/123456789"
  }'
```

```json theme={null}
{
  "assetId": "asset_8f2c...",
  "url": "https://cdn.vidjutsu.ai/uploads/tt_8f2c.../video.mp4",
  "platform": "tiktok",
  "externalId": "123456789",
  "sourceUrl": "https://www.tiktok.com/@creator/video/123456789",
  "contentType": "video/mp4",
  "size": 4213880,
  "sha256": "b7e2...",
  "reused": false
}
```

Repeated imports of the same post reuse the same asset (`reused: true`), so restaging is cheap. Use `url` from the response as the `videoUrl` / `sourceVideoUrl` for every step below.

**Errors**: `403 subscription_required` if the key has no active subscription. `429` with a `Retry-After` header if the daily import limit for the endpoint is hit; the window resets at 00:00 UTC.

### 2. Check whether it will clone well

```bash theme={null}
curl -X POST https://api.vidjutsu.ai/v1/clones/check \
  -H "Authorization: Bearer $VIDJUTSU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "videoUrl": "https://cdn.vidjutsu.ai/uploads/tt_8f2c.../video.mp4",
    "context": "Two-person kitchen scene, single continuous take, minimal camera movement"
  }'
```

```json theme={null}
{
  "verdict": "strong",
  "score": 95,
  "evidence": [
    "Single continuous shot with a stable, mostly static camera",
    "One clearly framed subject occupying the center third",
    "No fast cuts or overlaid text obscuring the motion"
  ],
  "model": "gemini-3.5-flash"
}
```

`verdict` is `strong`, `possible`, or `weak`, backed by a 0-100 `score` and the `evidence` behind it. Branch on the result: a `strong` or `possible` verdict is worth continuing, `weak` usually is not. This call is synchronous and shares the same daily clone admission limit as the character, starting-image, and video steps.

**Errors**: `403 subscription_required`, `429` with `Retry-After` on the shared clone admission limit.

### 3. Compose the starting frame

Pass the `id` from [Create your character first](#create-your-character-first) as `characterId`. `POST /v1/clones/starting-image` accepts either `characterId` (reuse the character you already created) or `characterImageUrl` (a one-off image), but exactly one of the two.

```bash theme={null}
curl -X POST https://api.vidjutsu.ai/v1/clones/starting-image \
  -H "Authorization: Bearer $VIDJUTSU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "characterId": "char_2a91b7f4",
    "prompt": "Standing at a kitchen counter, mid-gesture, facing camera",
    "sourceVideoUrl": "https://cdn.vidjutsu.ai/uploads/tt_8f2c.../video.mp4"
  }'
```

```json theme={null}
{
  "imageUrl": "https://cdn.vidjutsu.ai/clones/frame_5d0e.../frame.png",
  "model": "nano-banana-2"
}
```

`sourceVideoUrl` is optional; passing it grounds the composition in the source clip's opening frame so the pose and framing line up with the motion you're about to clone. The returned frame is always clean, no overlays or platform UI, no matter what the source or prompt included. Synchronous and shares the clone admission limit.

**Errors**: `403 subscription_required`, `429` on the shared clone admission limit. `422` if both or neither of `characterId` / `characterImageUrl` are provided, or if `characterId` doesn't resolve to a character you own.

### 4. Submit the clone

```bash theme={null}
curl -X POST https://api.vidjutsu.ai/v1/clones/video \
  -H "Authorization: Bearer $VIDJUTSU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "startingImageUrl": "https://cdn.vidjutsu.ai/clones/frame_5d0e.../frame.png",
    "sourceVideoUrl": "https://cdn.vidjutsu.ai/uploads/tt_8f2c.../video.mp4",
    "model": "kling"
  }'
```

```json theme={null}
{
  "id": "clone_9c7a1e",
  "status": "processing"
}
```

`model` defaults to `"kling"`; pass `"seedance"` for the 480p 9:16 alternate. `prompt` is an optional override of the default identity-swap prompt and only applies to `seedance`. This call is asynchronous: it returns `202` immediately with a task `id` to poll.

**Errors**: `403 subscription_required`. `422 video_too_long` if `sourceVideoUrl` runs past 15 seconds. `429` with `Retry-After` on the shared clone admission limit.

### 5. Poll for the result

```bash theme={null}
curl https://api.vidjutsu.ai/v1/clones/video/clone_9c7a1e \
  -H "Authorization: Bearer $VIDJUTSU_API_KEY"
```

```json theme={null}
{
  "id": "clone_9c7a1e",
  "status": "completed",
  "videoUrl": "https://d2h7xmz5gqybh9.cloudfront.net/clones/clone_9c7a1e/output.mp4"
}
```

Poll while `status` is `"processing"`. On `"completed"`, `videoUrl` carries the finished clip. On `"failed"`, `error` explains why. Status reads are not billed and not rate-limited. Unknown ids, or ids owned by another tenant, return `404`.

## SDK and CLI

<Info>
  The `vidjutsu clone run` CLI command requires the CLI's clone release. If you're on an older CLI version, run the calls directly against the API or the TypeScript SDK below until you upgrade.
</Info>

Create your character once:

```bash theme={null}
vidjutsu clone character --prompt "A friendly host in their late 20s, casual streetwear"
```

This prints the character's `id`. Reuse that id on every clone:

```bash theme={null}
vidjutsu clone run https://www.tiktok.com/@creator/video/123456789 --character char_2a91b7f4
```

The CLI command wraps the remaining calls: stage, check, starting image (using the character id you passed), submit, poll, printing the verdict and score before it commits to generation.

## Continue the workflow

<CardGroup cols={2}>
  <Card title="Scrape guide" icon="magnifying-glass" href="/guides/scrape">
    Preview a TikTok or Instagram post's engagement before you decide what to clone.
  </Card>

  <Card title="API reference" icon="code" href="/api-reference/introduction">
    Full request and response schemas for every clone endpoint.
  </Card>

  <Card title="Overlay and disclaimer" icon="film" href="/sdk/overlay">
    Add a text overlay or disclaimer card to the finished clone before you publish.
  </Card>

  <Card title="Authentication" icon="key-round" href="/authentication">
    Get an API key and pass it as a bearer token.
  </Card>
</CardGroup>