Skip to main content
This guide explains the recommended workflow for using the Viral Ads Clone API. It focuses on the two project modes and how to create videos repeatedly from the same project.

​
Overview

The API has three main endpoints:
  • POST /v1/video/viral-ads-clone: create a clone project
  • GET /v1/video/viral-ads-clone/{project_id}: query project status, script, video tasks, and billing
  • POST /v1/video/viral-ads-clone/{project_id}/videos: create video tasks from a project script
The project creation request accepts public URLs only. The backend stores the reference video, product images, and optional avatar image before creating the project. After the project is created, script generation starts in the background.

​
Project Modes

​
Auto Mode

Use mode: "auto" when you want the system to generate the first batch of videos automatically. Flow:
  1. Create a project with POST /v1/video/viral-ads-clone and mode: "auto".
  2. The backend stores the input media and creates the project.
  3. The backend generates the analysis and script.
  4. Once the script is ready, the backend automatically creates the first video generation task batch.
  5. Poll GET /v1/video/viral-ads-clone/{project_id} to check the project status, view_script, task_ids, and tasks.
Typical project states:
  • generating_script: the script is still being prepared
  • generating_video: video tasks have been created and are queued or running
  • script_ready: the script is available; this may appear when no video task is currently running
  • failed: the project failed
Auto mode creates only one automatic first batch for the project. It will not repeatedly create automatic video tasks for the same project.

​
Manual Mode

Use mode: "manual" when you want to review the script before creating videos. Flow:
  1. Create a project with POST /v1/video/viral-ads-clone and mode: "manual".
  2. Poll GET /v1/video/viral-ads-clone/{project_id} until view_script is returned.
  3. Review or edit the script on your side.
  4. Call POST /v1/video/viral-ads-clone/{project_id}/videos to create video tasks.
  5. Poll the project detail endpoint again, or query each returned task ID with the task API.
Manual mode will not create video tasks automatically. Video generation starts only when you call the /videos endpoint.

​
Recreating Videos From the Same Project

After a project has a generated script, you can call:
multiple times for the same project_id. Each call creates a new batch of video tasks and returns new task_ids. This is useful when you want to:
  • regenerate videos with the same script
  • try a lightly edited script
  • create more outputs from the same project
  • retry with different video options such as out_number, resolution, or aspect_ratio
If you pass a script in the /videos request, that script is used only for the current video batch. It does not overwrite the project original view_script. The project detail endpoint returns all video tasks created from the project, including:
  • the automatic first batch from auto mode
  • all later batches created by calling /videos
  • queued, running, succeeded, failed, and error tasks

​
Billing Notes

Creating a project charges API credits for script generation after the media URLs are stored successfully. Creating videos charges API credits for each video task batch. If a video task fails and is refunded or not finally charged, its credits_cost is returned as 0. Use the billing object in the project detail response to understand total usage:
  • script_credits_cost: credits charged for script generation
  • video_credits_cost: credits currently charged or reserved for non-failed video tasks
  • total_credits_cost: script plus video credits
For auto mode:
For manual mode: