Skip to main content

✂️ Viral Shorts from Long-form Content

The ZapCap API provides a powerful feature to automatically generate viral-worthy short clips from your long-form content. This guide will walk you through the process of creating and managing clipping tasks.

Overview​

Clipping tasks allow you to extract the most engaging segments from your longer videos, perfect for creating viral shorts for social media platforms. The API handles the entire process, from analyzing your content to delivering ready-to-share clips.

Creating a Clipping Task​

To create a clipping task, you'll use the POST /videos/{videoId}/clipTask endpoint. Here's what you need to know:

Request Body​

The request body should conform to the CreateVideoClipTaskRequestDto:

{
  maxClips: number;
  durationRange: ClipDurationRange;
}
  • maxClips: The maximum number of clips you want to generate. This should be between 1 and 5. Note that the actual number of clips returned may be less than this value.
  • durationRange: The desired duration range for your clips. This is an enum with the following options:
    • lt_30s: Less than 30 seconds
    • gte_30s_lt_60s: Between 30 seconds and 1 minute
    • gte_60s_lt_90s: Between 1 minute and 1.5 minutes
    • gte_90s_lt_180s: Between 1.5 minutes and 3 minutes

Response​

Upon successful creation of a clipping task, you'll receive a CreateVideoClipTaskResponseDto:

{
  id: string;
}

This id is crucial as you'll use it to query the status of your clipping task later.

Monitoring Clipping Task Status​

To check the status of your clipping task, use the GET /videos/{videoId}/clipTask/{id} endpoint. The response will be a GetVideoClipTaskResponseDto:

{
  id: string;
  status: VideoClipTaskStatus;
  clips: ClipResponse[];
  error?: string;
}
  • id: The unique identifier of the clipping task.
  • status: The current status of the task. Possible values are:
    • pending: The task is queued and waiting to be processed.
    • clipping: The API is currently analyzing and clipping your video.
    • clipped: The clipping process is complete, but final processing is still ongoing.
    • completed: The task is finished, and clips are ready for download.
    • failed: The task encountered an error during processing.
  • clips: An array of ClipResponse objects, each containing:
    • url: The download URL for the clip.
    • theme: A descriptive theme for the clip content.
  • error: If the task failed, this field will contain an error description.

Clipping Task Lifecycle​

  1. Task Creation: You create a new clipping task using the POST /videos/{videoId}/clipTask endpoint.
  2. Processing: The API analyzes your video and identifies the most engaging segments based on your specified criteria.
  3. Clipping: The selected segments are extracted and processed into individual clips.
  4. Completion: Once all clips are ready, the task status changes to completed, and you can download the clips.

Best Practices​

  1. Optimal Clip Count: Start with requesting 3-5 clips to get a good variety of content.
  2. Duration Selection: Choose a duration range that fits your target platform.
  3. Regular Polling: Check the task status periodically to know when your clips are ready. Tasks can take 3-5 minutes to complete.
  4. Error Handling: Always check for the error field in the response to handle any issues that may arise during processing.

Costs and Billing​

Understanding the costs associated with clipping tasks is crucial for managing your budget effectively. The ZapCap API uses a sophisticated pricing model that takes into account both the transcription of your original video and the generation of clips.

Cost Components​

  1. Transcription Cost: A portion of the transcription cost is charged for clipping tasks.

    • Base transcription cost: $0.03 per minute of video

  2. Clip Generation Cost: This varies based on the duration range you select:

    • Less than 30 seconds: $0.075 per clip
    • 30 seconds to 1 minute: $0.10 per clip
    • 1 minute to 1.5 minutes: $0.125 per clip
    • 1.5 minutes to 3 minutes: $0.15 per clip

Calculating Total Cost​

The total cost for a clipping task is calculated as follows:

Total Cost = Transcription Cost + (Clip Cost * Number of Clips)

Where:

  • Transcription Cost = (Video Duration in Minutes) * $0.03
  • Clip Cost is based on the selected duration range
  • Number of Clips is the maxClips value you specify (1-5)

Billing Process​

  1. When you create a clipping task, the maximum potential cost (based on maxClips) is calculated.
  2. This amount is temporarily held from your account balance.
  3. If the task is successful, the held amount is charged.
  4. If fewer clips are generated than requested, you'll be refunded for the difference.

Example Cost Calculation​

Let's say you have a 10-minute video and request 3 clips of 30-60 seconds each:

  1. Transcription Cost: (10 * $0.03) = $0.30
  2. Clip Cost: $0.10 * 3 = $0.30
  3. Total Cost: $0.30 + $0.30 = $0.60

Refunds​

If the API generates fewer clips than requested, you'll be automatically refunded for the unused clip costs. For example, if you requested 3 clips but only 2 were generated, you'd be refunded the cost of 1 clip.

Limitations and Considerations​

  • The number of clips returned may be less than maxClips if the API can't find enough engaging segments that meet your criteria.
    • You will only be charged for the clips that are successfully generated.
  • Clipping tasks are subject to the same TTL (Time to Live) rules as other tasks in the ZapCap API. Ensure you download your clips before they expire.
  • The API uses advanced algorithms to identify engaging content, but the results may not always align perfectly with human judgment. It's recommended to review the clips before publishing.

By leveraging the clipping tasks feature, you can efficiently create viral-worthy short-form content from your long-form videos, saving time and maximizing your content's reach across various platforms.