Viral Video Clone โ
Viral Video Clone turns a proven viral video into a reusable template for batch production. Provide one viral reference video and your product images; the system learns the reference video's style, pacing and shot structure, then combines them with your product to generate a brand-new marketing video with the same style and rhythm.
Typical use cases: e-commerce short videos, cross-border marketing assets, and cloning a creator's style at scale.
Types โ
The Mode parameter selects one of three types:
| Type | Mode value | Description |
|---|---|---|
| Script-level clone | script (default) | Learns the reference video's script structure and style and generates a new video from your product information; duration, aspect ratio, voiceover language and target market can be specified |
| Motion-level clone | motion | Follows the reference video's motion and shot sizes segment by segment, replacing the person, product, outfit or background with the reference images you provide; output duration and aspect ratio follow the reference video |
| Depth video estimation | depth | Standalone capability that outputs only the black-and-white depth video of the reference video |
Model Tiers โ
Choose a model tier with AIGCParam.ModelTier. Depth video estimation needs no tier.
| Tier | ModelTier value | Script-level clone | Motion-level clone | Max duration per generation | Max reference images |
|---|---|---|---|---|---|
| Pro | pro | Supported | Supported | 30 s | 9 |
| Flash | flash (default) | Supported | Supported | 15 s | 9 |
API Reference โ
| Purpose | API | Official docs | API Explorer |
|---|---|---|---|
| Start a viral clone task | CloneViral | CloneViral | Try it online |
| Query task results | DescribeCloneViralTask | DescribeCloneViralTask | Try it online |
Basics โ
| Item | Value |
|---|---|
| Endpoint | mps.intl.tencentcloudapi.com |
| API version | Version: 2019-06-12 |
| Region | Common parameter โ not required for this API |
| Invocation | Asynchronous: CloneViral returns a TaskId, then poll with DescribeCloneViralTask |
| Rate limit | 20 requests/second for both APIs |
| Result retention | Temporary links kept for 24 hours by default; results can also be written to your own COS via Output |
| Authentication | Tencent Cloud API 3.0 common parameters (TC3-HMAC-SHA256 signing); see API Reference |
Prerequisites โ
Before you start: sign up / sign in to a Tencent Cloud international account, activate MPS, and grant the service role authorization. If you use a sub-account, make sure it has permission to call MPS.
Billing โ
- Script-level and motion-level clone: billed as "Viral Clone", priced separately per model tier.
- Depth video estimation: billed as "Depth Video Estimation".
See the MPS pricing page on the Tencent Cloud website for unit prices.
Start a Task (CloneViral) โ
Basic Parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
Mode | No | String | Clone type: script (script-level clone, default) / motion (motion-level clone) / depth (depth video estimation) |
VideoUrl | Yes | String | URL of the viral reference video |
Product | Depends on type | Object | Product information, see below |
Persona | No | Object | Model persona, see below |
Reference | No | Object | Additional reference assets (outfits, backgrounds), see below |
AIGCParam | No | Object | Generation parameters, see below |
ContentParam | No | Object | Content and style parameters, see below |
Output | No | Object | Output location, see below |
Product Parameters (Product) โ
Required for script-level clone, with at least 1 product image; optional for motion-level clone (non-commerce videos can omit it); not needed for depth video estimation.
| Parameter | Required | Type | Description |
|---|---|---|---|
Product.Images | Depends on type | Array of String | Product image URLs. Required for script-level clone (at least 1); optional for motion-level clone, where they serve as product reference images |
Product.Name | No | String | Product name |
Product.Description | No | String | Product selling points |
Model Persona Parameters (Persona) โ
Passing a Persona object enables model persona settings.
| Parameter | Required | Type | Description |
|---|---|---|---|
Persona.Images | No | Array of String | Persona reference image URLs that define how the person in the output looks |
Persona.Gender | No | String | Gender: male / female / any |
Persona.Age | No | String | Age group: teenager / youth / middle_aged / senior |
Persona.Ethnicity | No | String | Appearance: caucasian / asian / latino / african / middle_eastern |
Persona.BodyType | No | String | Body type: slim / standard / athletic / chubby |
Additional Reference Assets (Reference) โ
Motion-level clone only
Reference is currently supported only with Mode=motion; passing it with other types returns a parameter error. Use Persona.Images for person images and Product.Images for product images.
| Parameter | Required | Type | Description |
|---|---|---|---|
Reference.Outfits | No | Array of String | Outfit reference image URLs. With multiple outfits, the person changes outfits in order at the reference video's shot transitions |
Reference.Backgrounds | No | Array of String | Background / scene reference image URLs |
Generation Parameters (AIGCParam) โ
| Parameter | Required | Type | Description |
|---|---|---|---|
AIGCParam.ModelTier | No | String | Model tier: pro / flash (default); see Model Tiers |
AIGCParam.Duration | No | Integer | Video duration in seconds, script-level clone only. Omit or pass 0 to follow the reference video; when specified, the range depends on the tier: 2โ15 for flash, 4โ30 for pro |
AIGCParam.AspectRatio | No | String | Aspect ratio. If omitted, 9:16 (portrait) or 16:9 (landscape) is chosen automatically from the reference video. Options: 9:16 / 16:9 / 3:4 / 4:3 / 1:1 / 21:9 / adaptive (match the reference video; not supported on flash) |
AIGCParam.Resolution | No | String | Resolution: 720p (default) / 1080p. Ignored for depth video estimation, which follows the reference video's resolution |
AIGCParam.DepthWithAudio | No | Boolean | Whether the depth video keeps the reference video's audio track; default false (no audio) |
Content & Style Parameters (ContentParam) โ
| Parameter | Required | Type | Description |
|---|---|---|---|
ContentParam.UserPrompt | No | String | Custom prompt with extra requirements for the generated video |
ContentParam.Language | No | String | Voiceover language, script-level clone only: zh (Chinese) / en (English) / ja (Japanese) / ko (Korean) / es (Spanish) / pt (Portuguese) / de (German) / fr (French) / it (Italian) / pl (Polish) / instrumental (music only, no voiceover) |
ContentParam.Market | No | String | Target market, which shapes the localized style, script-level clone only: north_america / europe / china / japan / korea / sea (Southeast Asia) / brazil |
Output Parameters (Output) โ
If omitted, results are returned as temporary links (kept for 24 hours).
| Parameter | Required | Type | Description |
|---|---|---|---|
Output.Type | No | String | Output type: url (default, temporary link valid for 24 hours) / cos (write to the specified COS bucket and path) |
Output.CosInfo.Region | No | String | Region of the COS bucket, used when Type=cos |
Output.CosInfo.Bucket | No | String | COS bucket name, used when Type=cos |
Output.CosInfo.Dir | No | String | Output directory; defaults to the root directory when empty |
Response Parameters โ
| Parameter | Type | Description |
|---|---|---|
TaskId | String | Task ID returned once the task is created; use it to poll progress and results |
Status | String | Task status โ FAIL is returned on failure |
Message | String | Error message returned on failure |
RequestId | String | Unique request ID, required when troubleshooting |
Request Examples โ
The URLs, product name and selling points below are sample values โ replace them with your own assets. The reference video and reference images must be publicly reachable by the service.
Example 1: Script-Level Clone โ
{
"Mode": "script",
"VideoUrl": "https://your-bucket-1250000000.cos.ap-singapore.myqcloud.com/viral/reference.mp4",
"Product": {
"Images": [
"https://your-bucket-1250000000.cos.ap-singapore.myqcloud.com/viral/pic1.png",
"https://your-bucket-1250000000.cos.ap-singapore.myqcloud.com/viral/pic2.png",
"https://your-bucket-1250000000.cos.ap-singapore.myqcloud.com/viral/pic3.png"
],
"Name": "Ice Silk White Dress",
"Description": "Cooling ice-silk fabric, quick-dry and breathable, multiple colors available"
},
"AIGCParam": {
"ModelTier": "flash",
"Duration": 10,
"AspectRatio": "9:16",
"Resolution": "720p"
},
"ContentParam": {
"UserPrompt": "Show the product in a sunny park setting",
"Language": "en",
"Market": "north_america"
},
"Persona": {
"Gender": "female",
"Age": "youth",
"Ethnicity": "asian",
"BodyType": "standard"
}
}Response:
{
"Response": {
"TaskId": "1300057393-ViralCloneAsync-bfea1147-48d4-418f-87b0-71ba350c38bc",
"RequestId": "bfea1147-48d4-418f-87b0-71ba350c38bc"
}
}Example 2: Motion-Level Clone โ Swap the Person + Specify the Outfit โ
Set the person with Persona.Images and describe the outfit in UserPrompt:
{
"Mode": "motion",
"VideoUrl": "https://your-bucket-1250000000.cos.ap-singapore.myqcloud.com/viral/motion/original.mp4",
"AIGCParam": { "ModelTier": "pro" },
"ContentParam": {
"UserPrompt": "Change the outfit to a black leather jacket over a black crew-neck top"
},
"Persona": {
"Images": ["https://your-bucket-1250000000.cos.ap-singapore.myqcloud.com/viral/motion/persona.jpg"]
}
}Example 3: Motion-Level Clone โ Swap the Person + Product + Background โ
Replace the person, product and background together; the background image goes in Reference.Backgrounds:
{
"Mode": "motion",
"VideoUrl": "https://your-bucket-1250000000.cos.ap-singapore.myqcloud.com/viral/dance/original.mov",
"AIGCParam": { "ModelTier": "pro" },
"Persona": {
"Images": ["https://your-bucket-1250000000.cos.ap-singapore.myqcloud.com/viral/dance/persona.png"]
},
"Product": {
"Images": ["https://your-bucket-1250000000.cos.ap-singapore.myqcloud.com/viral/dance/product.jpg"]
},
"Reference": {
"Backgrounds": ["https://your-bucket-1250000000.cos.ap-singapore.myqcloud.com/viral/dance/background.png"]
}
}Example 4: Depth Video Estimation โ
Depth video estimation can be used on its own: with just one reference video, the system extracts the frame structure and outputs the corresponding black-and-white depth video. It is also the first step of motion-level clone โ motion-level clone keeps generating a new video on top of the depth video, while depth video estimation stops once the depth video is output.
Set Mode to depth and pass the reference video; no product images or tier are needed:
{
"Mode": "depth",
"VideoUrl": "https://your-bucket-1250000000.cos.ap-singapore.myqcloud.com/viral/reference.mp4",
"AIGCParam": {
"DepthWithAudio": true
}
}Query Results (DescribeCloneViralTask) โ
Request Parameters โ
| Parameter | Required | Type | Description |
|---|---|---|---|
TaskId | No | String | Task ID returned by CloneViral (marked optional in the docs, but you should always pass it when querying) |
Response Parameters โ
| Parameter | Type | Description |
|---|---|---|
Status | String | WAIT: waiting; RUN: running; FAIL: failed; DONE: succeeded |
Message | String | Error message returned on failure |
VideoUrls | Array of String | Video URL list returned when Status is DONE; kept for 24 hours |
RequestBody | String | The request body used to create the task, handy for checking parameters |
RequestId | String | Unique request ID |
Example โ
POST / HTTP/1.1
Host: mps.intl.tencentcloudapi.com
Content-Type: application/json
X-TC-Action: DescribeCloneViralTask
<Common request parameters>
{
"TaskId": "24000191-ViralClone-92e56dab-2a5b-4537-b49f-854563d4903f"
}Response:
{
"Response": {
"Status": "DONE",
"VideoUrls": [
"https://laurie-tmp-1300828900.cos.ap-nanjing.myqcloud.com/viral_clone/20260720/24000191-ViralClone-92e56dab-2a5b-4537-b49f-854563d4903f/clip.mp4"
],
"RequestId": "74aeda83-63cc-4404-9f10-e43e841d242c"
}
}Result links are temporary
VideoUrls are kept for only 24 hours โ download them or copy them to your own storage promptly. For long-term storage, use Output to write results straight to your own COS when starting the task.
Calling from Python โ
Send raw JSON with CommonClient, not MpsClient.CloneViral
The CloneViral request model in the international SDK tencentcloud-sdk-python-intl-en still carries the old field set and lacks Mode, Reference, Output, Persona.Images and DepthWithAudio. When you fill those fields via from_json_string, the SDK only prints a fileds are useless warning and does not send them to the server โ the task silently runs as the default script-level clone. The code below uses CommonClient.call_json to send JSON directly, so every field reaches the server as-is.
import os, time
from tencentcloud.common import credential
from tencentcloud.common.common_client import CommonClient
from tencentcloud.common.profile.client_profile import ClientProfile
from tencentcloud.common.profile.http_profile import HttpProfile
cred = credential.Credential(os.environ["TENCENT_SECRET_ID"], os.environ["TENCENT_SECRET_KEY"])
client_profile = ClientProfile(httpProfile=HttpProfile(endpoint="mps.intl.tencentcloudapi.com"))
client = CommonClient("mps", "2019-06-12", cred, "ap-singapore", profile=client_profile)
# 1. Start a motion-level clone
resp = client.call_json("CloneViral", {
"Mode": "motion",
"VideoUrl": "https://your-bucket-1250000000.cos.ap-singapore.myqcloud.com/viral/motion/original.mp4",
"AIGCParam": {"ModelTier": "pro"},
"Persona": {"Images": ["https://your-bucket-1250000000.cos.ap-singapore.myqcloud.com/viral/motion/persona.jpg"]},
})["Response"]
if resp.get("Status") == "FAIL":
raise RuntimeError(resp.get("Message"))
task_id = resp["TaskId"]
# 2. Poll for the result
while True:
r = client.call_json("DescribeCloneViralTask", {"TaskId": task_id})["Response"]
if r["Status"] == "DONE":
print("Video URLs:", r["VideoUrls"])
break
if r["Status"] == "FAIL":
raise RuntimeError(f"task failed: {r.get('Message')}")
time.sleep(5)Credentials, region and endpoint are configured the same way as in the SDK Reference.
Related Docs โ
| Doc | Description |
|---|---|
| API Reference | General conventions for MPS authentication, TC3 signing and request execution |
| SDK Reference | End-to-end flow for calling key MPS APIs with the official SDKs |
| Media AI Agent Quick Start | The VOD-side video editing agent in the same section |