Generate Preview
Generate visual previews from video: animated GIFs, thumbnails, mosaics, or short clips.
/v1/preview
1 credit
Description
Generate visual previews from video: animated GIFs, thumbnails, video mosaics (contact sheets), or short MP4 clips. All processing is done via ffmpeg.
Request Body
Send a JSON body with the following parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| url | string | Yes | — | Source video URL |
| preview_type | string | Yes | — | "gif", "thumbnail", "mosaic", "clip" |
| timestamp | string | No | 25% of duration | Frame to extract (thumbnail only). Seconds or "MM:SS". |
| start | string | No | null | Start time for gif/clip |
| duration | number | No | 5 (gif), 10 (clip) | Duration in seconds. Max: 15 (gif), 30 (clip). |
| width | int | No | 480 | Output width in pixels. Height auto-scales. |
| columns | int | No | 4 | Mosaic columns (max 8) |
| rows | int | No | 4 | Mosaic rows (max 8) |
| fps | int | No | 10 | GIF frames per second (max 20) |
Preview Types
gif
Animated GIF from a video segment. Great for social media sharing, embed previews, and messaging apps.
Parameters: start, duration, width, fps.
thumbnail
Single frame extracted as JPEG. Use for content previews, video catalogs, and OG images.
Parameters: timestamp (defaults to 25% of video duration), width.
mosaic
Grid of evenly-spaced frames (contact sheet). Use for content moderation, quick visual scanning, and
video cataloging. Parameters: columns, rows, width.
clip
Short MP4 preview clip. Use for hover previews, video teasers, and embed players.
Parameters: start, duration.
Code Examples
Animated GIF
curl -X POST "https://videoconduit.com/v1/preview" \
-H "Authorization: Bearer vc_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"url": "https://youtube.com/watch?v=dQw4w9WgXcQ",
"preview_type": "gif",
"start": "00:00:30",
"duration": 5,
"width": 480,
"fps": 10
}'import requests
response = requests.post(
"https://videoconduit.com/v1/preview",
headers={"Authorization": "Bearer vc_your_api_key"},
json={
"url": "https://youtube.com/watch?v=dQw4w9WgXcQ",
"preview_type": "gif",
"start": "00:00:30",
"duration": 5,
"width": 480,
"fps": 10,
},
)
data = response.json()
print(data["job_id"])const response = await fetch("https://videoconduit.com/v1/preview", {
method: "POST",
headers: {
"Authorization": "Bearer vc_your_api_key",
"Content-Type": "application/json",
},
body: JSON.stringify({
url: "https://youtube.com/watch?v=dQw4w9WgXcQ",
preview_type: "gif",
start: "00:00:30",
duration: 5,
width: 480,
fps: 10,
}),
});
const data = await response.json();
console.log(data.job_id);$client = new GuzzleHttp\Client();
$response = $client->post("https://videoconduit.com/v1/preview", [
"headers" => ["Authorization" => "Bearer vc_your_api_key"],
"json" => [
"url" => "https://youtube.com/watch?v=dQw4w9WgXcQ",
"preview_type" => "gif",
"start" => "00:00:30",
"duration" => 5,
"width" => 480,
"fps" => 10,
],
]);
$data = json_decode($response->getBody(), true);
echo $data["job_id"];body := strings.NewReader(`{
"url": "https://youtube.com/watch?v=dQw4w9WgXcQ",
"preview_type": "gif",
"start": "00:00:30",
"duration": 5,
"width": 480,
"fps": 10
}`)
req, _ := http.NewRequest("POST", "https://videoconduit.com/v1/preview", body)
req.Header.Set("Authorization", "Bearer vc_your_api_key")
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
var data map[string]interface{}
json.NewDecoder(resp.Body).Decode(&data)require "net/http"
require "json"
uri = URI("https://videoconduit.com/v1/preview")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer vc_your_api_key"
req["Content-Type"] = "application/json"
req.body = {
url: "https://youtube.com/watch?v=dQw4w9WgXcQ",
preview_type: "gif",
start: "00:00:30",
duration: 5,
width: 480,
fps: 10,
}.to_json
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)
puts data["job_id"]Thumbnail
curl -X POST "https://videoconduit.com/v1/preview" \
-H "Authorization: Bearer vc_your_api_key" \
-H "Content-Type: application/json" \
-d '{"url": "https://youtube.com/watch?v=dQw4w9WgXcQ", "preview_type": "thumbnail", "timestamp": "01:30"}'Mosaic (Contact Sheet)
curl -X POST "https://videoconduit.com/v1/preview" \
-H "Authorization: Bearer vc_your_api_key" \
-H "Content-Type: application/json" \
-d '{"url": "https://youtube.com/watch?v=dQw4w9WgXcQ", "preview_type": "mosaic", "columns": 4, "rows": 4}'MP4 Clip
curl -X POST "https://videoconduit.com/v1/preview" \
-H "Authorization: Bearer vc_your_api_key" \
-H "Content-Type: application/json" \
-d '{"url": "https://youtube.com/watch?v=dQw4w9WgXcQ", "preview_type": "clip", "start": "00:01:00", "duration": 10}'Response
Initial Response
Returned immediately when the job is created:
{
"job_id": "d4e5f6a7-b8c9-0123-defa-456789012345",
"status": "pending",
"credits_charged": 1
}Completed Job
Returned from GET /v1/jobs/{id} when the job finishes:
{
"job_id": "d4e5f6a7-b8c9-0123-defa-456789012345",
"status": "completed",
"download_url": "https://dl.videoconduit.com/files/d4e5f6a7.gif",
"result_data": {
"preview_type": "gif",
"width": 480,
"height": 270,
"duration": 5.0,
"fps": 10,
"filesize": 1234567
},
"expires_at": "2025-01-15T12:00:00Z"
}Try It
{# Usage: {% include "docs/_playground.html" with endpoint_method="POST" endpoint_path="/v1/download" fields=playground_fields %} playground_fields is a list of dicts passed from the view: [ {"name": "url", "type": "text", "required": True, "placeholder": "https://youtube.com/watch?v=...", "label": "Video URL"}, {"name": "quality", "type": "select", "options": ["best", "1080p", "720p", "480p", "audio"], "default": "best", "label": "Quality"}, ] #}Try It
POST /v1/previewNotes
Async Operation
This endpoint returns a job_id immediately. Poll GET /v1/jobs/{id} for status updates, or configure webhooks for push notifications.
GIF File Size
GIFs can be large. Use lower fps (5-8) and shorter duration for smaller files. For longer previews, consider using the clip type instead.