> ## 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.

# Create Viral Ad Clone Project

> Creates a Viral Ads Clone project from public media URLs. The server stores the media first, creates the project, charges 10 API credits for script generation, and starts background analysis. In auto mode, the first video batch is created automatically after the script is ready. In manual mode, video generation waits for an explicit call to the videos endpoint.



## OpenAPI

````yaml POST /v1/video/viral-ads-clone
openapi: 3.1.0
info:
  title: Loova API
  description: Loova API lets developers generate AI images and videos programmatically.
  version: 1.0.0
servers:
  - url: https://api.loova.ai/api
security:
  - bearerAuth: []
paths:
  /v1/video/viral-ads-clone:
    post:
      summary: Create Viral Ad Clone Project
      description: >-
        Creates a Viral Ads Clone project from public media URLs. The server
        stores the media first, creates the project, charges 10 API credits for
        script generation, and starts background analysis. In auto mode, the
        first video batch is created automatically after the script is ready. In
        manual mode, video generation waits for an explicit call to the videos
        endpoint.
      operationId: createViralAdsCloneProject
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateViralAdsCloneProjectRequest'
            example:
              reference_video_url: https://example.com/reference.mp4
              product_image_urls:
                - https://example.com/product-front.jpg
                - https://example.com/product-side.jpg
              avatar_image_url: https://example.com/avatar.jpg
              prompt: Create a UGC-style skincare ad, keep the tone natural.
              aspect_ratio: '9:16'
              speech_language_option: ''
              duration: 15
              resolution: 720
              out_number: 1
              mode: auto
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateViralAdsCloneProjectResponse'
              example:
                code: 200
                trace_id: 45c30d76f06549b199a3775544515689
                message: null
                data:
                  project_id: 683f1a2b3c4d5e6f7890abcd
                  status: draft
                  current_step: preparing_media
                  mode: auto
                  credits_cost: 10
                  created_at: '2026-06-15T08:00:00Z'
        '400':
          description: Request failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: 400
                trace_id: 45c30d76f06549b199a3775544515689
                message: Detailed error message
                data: null
        '409':
          description: Business-level rejection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                insufficientCredits:
                  summary: Insufficient API credits
                  value:
                    code: 300111
                    trace_id: 45c30d76f06549b199a3775544515689
                    message: Insufficient API credits
                    data: null
                mediaStorageFailed:
                  summary: Media storage failed
                  value:
                    code: 100099
                    trace_id: 45c30d76f06549b199a3775544515689
                    message: Failed to store media from URL
                    data: null
      security:
        - bearerAuth: []
components:
  schemas:
    CreateViralAdsCloneProjectRequest:
      type: object
      required:
        - reference_video_url
        - product_image_urls
      properties:
        reference_video_url:
          type: string
          format: uri
          description: >-
            Public HTTP or HTTPS URL of the reference ad video. The server
            stores this media internally before creating the project.
        product_image_urls:
          type: array
          minItems: 1
          items:
            type: string
            format: uri
          description: >-
            Public HTTP or HTTPS URLs of product reference images. These images
            are stored internally and used for product analysis and video
            generation.
        avatar_image_url:
          type:
            - string
            - 'null'
          format: uri
          description: >-
            Optional public HTTP or HTTPS URL of a person, avatar, model, or
            spokesperson reference image.
        prompt:
          type:
            - string
            - 'null'
          description: >-
            Optional user instruction, such as selling points, style,
            restrictions, or language preference.
        aspect_ratio:
          type: string
          default: '9:16'
          enum:
            - '9:16'
            - '1:1'
            - '16:9'
          description: Target video aspect ratio.
        speech_language_option:
          type:
            - string
            - 'null'
          default: ''
          enum:
            - english
            - spanish
            - portuguese
            - french
            - german
            - arabic
            - chinese
            - japanese
            - korean
            - vietnamese
            - thai
            - indonesian
            - malay
            - filipino
            - hindi
          description: >-
            Optional spoken language preference for generated spoken_audio,
            including voiceover, narration, dialogue, speaker turns, and short
            verbal expressions. Use an empty string to follow the reference
            video's spoken language. If a target language value is provided, it
            takes priority over language instructions in prompt. This field does
            not change visual structure, background music, lyrics, sound
            effects, pacing, camera behavior, or audio sync.
        duration:
          type: integer
          default: 15
          description: Target video duration in seconds.
        resolution:
          type:
            - integer
            - string
          default: 720
          description: Target video resolution. Common values include 720 and 1080.
        out_number:
          type: integer
          minimum: 1
          maximum: 4
          default: 1
          description: >-
            Number of videos to create automatically in auto mode, or the
            default batch size used by the videos endpoint when not provided.
        mode:
          type: string
          enum:
            - auto
            - manual
          default: auto
          description: >-
            `auto` creates the first video batch automatically after the script
            is ready. `manual` only generates the script and waits for the
            videos endpoint.
      description: >-
        Validation rules:

        - `reference_video_url` is required and must be an HTTP or HTTPS URL

        - `product_image_urls` is required and must contain at least one HTTP or
        HTTPS URL

        - `avatar_image_url`, if provided, must be an HTTP or HTTPS URL

        - `speech_language_option`, if provided, controls only generated
        spoken_audio language

        - `out_number` must be between 1 and 4

        - `mode` must be `auto` or `manual`
    CreateViralAdsCloneProjectResponse:
      type: object
      properties:
        code:
          type: integer
        trace_id:
          type: string
        message:
          type:
            - string
            - 'null'
        data:
          type: object
          properties:
            project_id:
              type: string
            status:
              $ref: '#/components/schemas/ViralAdsCloneProjectStatus'
            current_step:
              $ref: '#/components/schemas/ViralAdsCloneCurrentStep'
            mode:
              $ref: '#/components/schemas/ViralAdsCloneMode'
            credits_cost:
              type: number
              description: >-
                API credits charged for script generation. This is 10 for
                project creation.
            created_at:
              type:
                - string
                - 'null'
              format: date-time
    ErrorResponse:
      type: object
      properties:
        code:
          type: integer
        trace_id:
          type: string
        message:
          type:
            - string
            - 'null'
        data:
          type:
            - object
            - 'null'
    ViralAdsCloneProjectStatus:
      type: string
      enum:
        - draft
        - running
        - succeeded
        - failed
      description: Project status.
    ViralAdsCloneCurrentStep:
      type: string
      enum:
        - preparing_media
        - analyzing
        - generating_script
        - script_ready
        - generating_video
        - failed
      description: Coarse-grained current project step.
    ViralAdsCloneMode:
      type: string
      enum:
        - auto
        - manual
      description: Project execution mode.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````