Creates a new video from this one, pointing back at it through
parentVideoId. regenerate: true (charging credits) writes the next
episode of a faceless video: a new script on the same theme, a new
voice-over and new visuals. On other video types it only writes a new
title and caption, and the scenes, actor and narration are reused.
render: true queues the render as soon as the clip is ready.
On an automation, regenerate: true is refused with
warning-automation-needs-prompt when the automation has nothing to
write from (no scriptPrompt and no prompt), since the clip would
repeat its first video.
The editor's pipeline guards (nothing failed, nothing already waiting to publish) are deliberately off here: an integration builds its own flow and is not looking at the publishing pipeline view.
Authorization
bearerAuth An API key created under Settings > API & Webhooks. Keys start with sf_live_.
In: header
Path Parameters
Header Parameters
Unique key per action (a UUID works well). Reusing it replays the first response instead of running the action again, so a retry after a timeout can never generate, render, publish or charge twice.
length <= 255Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/videos/string/clips" \ -H "Content-Type: application/json" \ -d '{ "regenerate": true, "render": true }'{ "data": { "id": "string", "title": "string", "type": "faceless", "subType": "string", "isAutomation": true, "parentVideoId": "string", "isClip": true, "brief": { "prompt": "string", "text": "string", "scriptPrompt": "string", "description": "string", "descriptionPrompt": "string", "inputMode": "auto", "videoDuration": "subminute", "language": "string", "aspectRatio": "9:16", "imageStyle": "auto", "styleAuto": true, "connectedBRolls": true, "animateBRolls": true, "animationQuality": "normal", "bRollPace": "fast", "backgroundMusic": true, "bRollTransitions": true, "customStyleText": "string", "voiceId": "string", "voiceProvider": "openai", "showSubtitles": true, "presentationTone": null, "presentationAssets": [], "presenter": { "imageUrl": "http://example.com", "avatarId": "string", "name": "string", "placement": "first", "occurrences": 1 }, "targetDuration": 0, "characterImageUrl": "http://example.com", "characterDescription": "string" }, "mood": "energetic", "presentationMood": null, "durationSeconds": 0, "media": { "sourceUrl": "http://example.com", "audioUrl": "http://example.com", "captionsUrl": "http://example.com", "thumbnailUrl": "http://example.com", "renderUrl": "http://example.com", "bytes": 0 }, "process": { "status": "QUEUED", "progress": 0, "statusText": "string", "queuedAt": "2019-08-24T14:15:22Z", "startedAt": "2019-08-24T14:15:22Z", "error": { "code": "string", "message": "string", "blocked": true, "action": "upgrade", "reference": "string", "retryAt": "2019-08-24T14:15:22Z", "platform": "string" } }, "render": { "status": "QUEUED", "progress": 0, "queuedAt": "2019-08-24T14:15:22Z", "startedAt": "2019-08-24T14:15:22Z", "error": { "code": "string", "message": "string", "blocked": true, "action": "upgrade", "reference": "string", "retryAt": "2019-08-24T14:15:22Z", "platform": "string" } }, "publish": { "status": "SCHEDULED", "scheduledAt": "2019-08-24T14:15:22Z", "startedAt": "2019-08-24T14:15:22Z", "publishedAt": "2019-08-24T14:15:22Z", "failedAt": "2019-08-24T14:15:22Z", "platforms": [ "string" ], "missingPlatforms": [ "string" ], "unhealthyPlatforms": [ "string" ], "caption": "string", "error": { "code": "string", "message": "string", "blocked": true, "action": "upgrade", "reference": "string", "retryAt": "2019-08-24T14:15:22Z", "platform": "string" }, "stats": { "checkedAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z", "available": true, "totals": { "views": 0, "likes": 0, "comments": 0, "shares": 0 }, "platforms": [ { "views": 0, "likes": 0, "comments": 0, "shares": 0, "platform": "string", "status": "published", "url": "string", "error": "string" } ] } }, "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z", "config": { "captionsFontFamily": "string", "captionsFontWeight": "string", "captionsAnimation": "fadeInSlideUp", "captionsWordEffects": "", "captionsTextTransform": "none", "layoutMode": "wrap", "captionsPrimaryColor": "string", "captionsSecondaryColor": "string", "captionsAccentColor": "string", "captionsStrokeColor": "string", "captionsSecondaryStrokeColor": "string", "captionsAccentStrokeColor": "string", "captionsShadowColor": "string", "captionsFirstWordColor": "string", "captionsHighlightBackground": "string", "captionsFontSize": 20, "captionsVerticalPosition": 0, "captionsTextStroke": 0, "captionsActiveWordStroke": 0, "captionsLetterSpacing": -5 }, "captions": [ { "id": "string", "startMs": 0, "endMs": 0, "text": "string", "punctuated_word": "string", "confidence": 0 } ], "captionsPages": [ { "id": "string", "startMs": 0, "endMs": 0, "hidden": true, "emoji": {}, "audioEffect": {} } ], "bRolls": [ { "id": "string", "startMs": 0, "endMs": 0, "text": "string", "prompt": "string", "keywords": "string", "mediaType": "ai_image", "url": "http://example.com", "type": "string", "qualityUrls": {}, "posterUrl": "http://example.com", "sourceWidth": 0, "sourceHeight": 0, "stockQuery": "string", "credit": { "source": "string", "author": "string", "license": "string", "url": "http://example.com" }, "animation": "string", "transition": "string", "layout": "string", "scale": 0, "hidden": true, "audioEffect": {}, "presenter": { "imageUrl": "http://example.com", "avatarId": "string", "name": "string", "bytes": 0, "generatedAt": "2019-08-24T14:15:22Z" } } ], "presentationScenes": [], "scenes": [ { "imagePrompt": "string", "animationPrompt": "string", "narration": "string", "voiceDescription": "string", "duration": 3, "id": "string", "status": "string", "imageUrl": "http://example.com", "videoUrl": "http://example.com" } ] }}Create a video and queue its generation POST
Creates a video from a brief and immediately queues the generation pipeline, so this call is asynchronous: it returns as soon as the job is enqueued, with `process.status: QUEUED`. Poll `GET /videos/{id}` or subscribe to `video.generation_completed`. The brief may be sent flat or nested under `brief`; the nested form wins, so a serialized video can be posted straight back. Unknown keys are ignored, a known key with a malformed value is a `400`. Generation charges credits and counts against the monthly generation limit, so it can be refused with `warning-no-credits`, `warning-plan-generations`, `warning-plan-storage` or `warning-plan-duration`. Pass `process.render: true` to chain the render as soon as generation finishes. `isAutomation` is refused here: create a blueprint with `POST /automations` instead.
Delete a video DELETE
Deletes the video, every clip made from it, and the stored files they own, then credits the freed bytes back to the workspace storage quota. This cannot be undone.