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

# Viral Ad Clone

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:

```http theme={null}
POST /v1/video/viral-ads-clone/{project_id}/videos
```

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

## Recommended Integration Pattern

For auto mode:

```text theme={null}
Create project with mode=auto
  -> Poll project detail
  -> Read view_script when available
  -> Wait for auto-created task_ids/tasks
  -> Optionally call /videos again to create more videos
```

For manual mode:

```text theme={null}
Create project with mode=manual
  -> Poll project detail until view_script is available
  -> Review or edit script
  -> Call /videos
  -> Poll project detail or task detail for results
  -> Call /videos again whenever you need another batch
```