Planned Feature - This API endpoint is planned for ClypAI’s 2026 launch. The documentation below represents the intended design and may change before release.
Overview The Clips API allows you to generate AI-powered video clips from source videos, manage clip processing, and export clips for various platforms.
All clip endpoints require authentication. See Authentication for details. The Clip Object Unique identifier for the clip
ID of the project this clip belongs to
URL of the original source video
Processing status: pending, processing, completed, failed, exported
Start time in source video (seconds)
End time in source video (seconds)
Clip generation configuration Target aspect ratio: 16:9, 9:16, 1:1, 4:5
Target platform: youtube, tiktok, instagram, twitter, linkedin
Whether to generate captions
Enable smart reframing to keep subject in frame
Automatically detect hooks and highlights
Brand kit to apply to the clip
Generated clip outputs URL of the processed video clip
URL of the clip thumbnail
URL of SRT caption file (if generated)
AI-generated metadata Detected hooks with timestamps
Overall sentiment: positive, neutral, negative
Detected topics and themes
ISO 8601 timestamp of clip creation
ISO 8601 timestamp of last update
Example Clip Object { "id" : "clip_xyz789abc" , "projectId" : "proj_a1b2c3d4e5" , "name" : "Product Demo Highlight" , "sourceVideoUrl" : "https://storage.clypai.com/videos/source_123.mp4" , "status" : "completed" , "duration" : 45.2 , "startTime" : 120.5 , "endTime" : 165.7 , "config" : { "aspectRatio" : "9:16" , "platform" : "tiktok" , "enableCaptions" : true , "reframing" : true , "hookDetection" : true , "brandKitId" : "brand_xyz123" }, "outputs" : { "videoUrl" : "https://storage.clypai.com/clips/clip_xyz789abc.mp4" , "thumbnailUrl" : "https://storage.clypai.com/thumbnails/clip_xyz789abc.jpg" , "captionsUrl" : "https://storage.clypai.com/captions/clip_xyz789abc.srt" }, "metadata" : { "hooks" : [ { "time" : 2.3 , "text" : "Watch this amazing feature" , "confidence" : 0.92 } ], "highlights" : [ 5.2 , 18.7 , 32.1 ], "sentiment" : "positive" , "topics" : [ "product demo" , "features" , "benefits" ] }, "createdAt" : "2024-01-15T10:30:00Z" , "updatedAt" : "2024-01-15T10:35:22Z" }
Generate Clip Create a new AI-powered clip from a source video.
curl -X POST https://api.clypai.com/v1/clips \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "projectId": "proj_a1b2c3d4e5", "name": "Product Demo Highlight", "sourceVideoUrl": "https://example.com/video.mp4", "config": { "aspectRatio": "9:16", "platform": "tiktok", "enableCaptions": true, "reframing": true, "hookDetection": true } }'
Parameters ID of the project to create the clip in
Display name for the clip
URL of the source video file (must be publicly accessible or signed URL)
Start time in source video (seconds). If not provided, AI will detect best segment
End time in source video (seconds). Required if startTime is provided
Clip generation configuration Target aspect ratio: 16:9, 9:16, 1:1, 4:5
Optimize for platform: youtube, tiktok, instagram, twitter, linkedin
Generate captions using AI
Smart reframing to keep subject in frame
Automatically detect hooks and highlights
Brand kit to apply to the clip
Maximum clip duration in seconds (15-300)
Response Whether the request was successful
The created clip object with status pending
{ "success" : true , "data" : { "id" : "clip_xyz789abc" , "projectId" : "proj_a1b2c3d4e5" , "name" : "Product Demo Highlight" , "sourceVideoUrl" : "https://example.com/video.mp4" , "status" : "pending" , "config" : { "aspectRatio" : "9:16" , "platform" : "tiktok" , "enableCaptions" : true , "reframing" : true , "hookDetection" : true }, "createdAt" : "2024-01-15T10:30:00Z" , "updatedAt" : "2024-01-15T10:30:00Z" } }
Clip generation is asynchronous. Use the Get Clip endpoint to poll for status updates, or configure a webhook to receive notifications. List Clips Retrieve a paginated list of clips, optionally filtered by project.
curl "https://api.clypai.com/v1/clips?projectId=proj_a1b2c3d4e5&limit=20" \ -H "Authorization: Bearer YOUR_API_KEY"
Query Parameters Filter clips by project ID
Filter by status: pending, processing, completed, failed, exported
Number of clips to return (max 100)
Pagination cursor from previous response
sortBy
string
default: "createdAt"
Sort field: name, createdAt, updatedAt, duration
Sort direction: asc or desc
Response { "success" : true , "data" : [ { "id" : "clip_xyz789abc" , "projectId" : "proj_a1b2c3d4e5" , "name" : "Product Demo Highlight" , "status" : "completed" , "duration" : 45.2 , "createdAt" : "2024-01-15T10:30:00Z" } ], "pagination" : { "hasMore" : true , "nextCursor" : "eyJpZCI6ImNsaXBfeHl6Nzg5YWJjIn0" } }
Get Clip Retrieve a specific clip by ID.
curl https://api.clypai.com/v1/clips/clip_xyz789abc \ -H "Authorization: Bearer YOUR_API_KEY"
Path Parameters The unique identifier of the clip
Response { "success" : true , "data" : { "id" : "clip_xyz789abc" , "projectId" : "proj_a1b2c3d4e5" , "name" : "Product Demo Highlight" , "sourceVideoUrl" : "https://storage.clypai.com/videos/source_123.mp4" , "status" : "completed" , "duration" : 45.2 , "startTime" : 120.5 , "endTime" : 165.7 , "config" : { "aspectRatio" : "9:16" , "platform" : "tiktok" , "enableCaptions" : true , "reframing" : true }, "outputs" : { "videoUrl" : "https://storage.clypai.com/clips/clip_xyz789abc.mp4" , "thumbnailUrl" : "https://storage.clypai.com/thumbnails/clip_xyz789abc.jpg" , "captionsUrl" : "https://storage.clypai.com/captions/clip_xyz789abc.srt" }, "metadata" : { "hooks" : [ { "time" : 2.3 , "text" : "Watch this amazing feature" , "confidence" : 0.92 } ], "sentiment" : "positive" , "topics" : [ "product demo" , "features" ] }, "createdAt" : "2024-01-15T10:30:00Z" , "updatedAt" : "2024-01-15T10:35:22Z" } }
Export Clip Export a completed clip with platform-specific optimizations.
curl -X POST https://api.clypai.com/v1/clips/clip_xyz789abc/export \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "format": "mp4", "quality": "high", "platform": "tiktok" }'
Path Parameters The unique identifier of the clip to export
Body Parameters Export format: mp4, mov, webm
Export quality: low, medium, high, ultra
Platform-specific optimization: youtube, tiktok, instagram, twitter
Burn captions into video (if available)
Response { "success" : true , "data" : { "exportUrl" : "https://storage.clypai.com/exports/clip_xyz789abc_export.mp4" , "expiresAt" : "2024-01-16T10:35:22Z" , "format" : "mp4" , "quality" : "high" , "fileSize" : 15728640 } }
Export URLs are temporary and expire after 24 hours. Download the file promptly or regenerate the export.
Delete Clip Permanently delete a clip.
curl -X DELETE https://api.clypai.com/v1/clips/clip_xyz789abc \ -H "Authorization: Bearer YOUR_API_KEY"
Path Parameters The unique identifier of the clip to delete
Response { "success" : true , "data" : { "id" : "clip_xyz789abc" , "deleted" : true } }
Processing Status Clip generation goes through several statuses:
pending
Clip creation request received, queued for processing
processing
AI is analyzing video and generating the clip
completed
Clip successfully generated and ready for download
failed
Clip generation failed (check error details in response)
exported
Clip has been exported at least once
Error Responses Invalid Source Video { "success" : false , "error" : { "code" : "invalid_request" , "message" : "Source video URL is not accessible" , "field" : "sourceVideoUrl" } }
Processing Failed { "success" : false , "error" : { "code" : "processing_failed" , "message" : "Clip generation failed: Unsupported video codec" , "details" : { "codec" : "h265" , "supportedCodecs" : [ "h264" , "vp9" ] } } }
Quota Exceeded { "success" : false , "error" : { "code" : "quota_exceeded" , "message" : "Monthly clip generation quota exceeded" , "details" : { "used" : 100 , "limit" : 100 , "resetAt" : "2024-02-01T00:00:00Z" } } }