{"openapi":"3.1.0","info":{"title":"ClipperGen API","version":"1.0.0","description":"Run the whole ClipperGen flow headless: create a project from an upload or a link, wait for a webhook, list ranked clips, edit and render them.\n\n**Authentication.** Send `Authorization: Bearer <api key>`. Create keys in Settings → API keys; each key belongs to one workspace.\n\n**Rate limits.** 60 requests a minute per key. Over the limit you get 429 `rate_limited` with a `Retry-After` header. Chunk uploads to a signed upload URL are not counted.\n\n**Idempotency.** Send `Idempotency-Key` on any POST. The first response is stored for 24 hours and replayed (with `Idempotent-Replayed: true`) for repeats with the same key. Reusing a key for a different request is a 400.\n\n**Errors.** Every error is `{\"error\": {\"code\", \"message\", \"details\"?}}`.\n\n**Webhooks.** Signed with HMAC-SHA256 in `X-ClipperGen-Signature: t=<unix>,v1=<hex>` over `<t>.<raw body>`. Reject timestamps more than 5 minutes old. Non-2xx answers are retried 5 times, at 1 min, 10 min, 1 h, 6 h, 24 h after the first attempt."},"servers":[{"url":"https://clipper.vioogen.com/v1"}],"tags":[{"name":"Projects"},{"name":"Clips"},{"name":"Renders"},{"name":"Uploads"},{"name":"Usage"},{"name":"Webhooks"},{"name":"Meta"}],"paths":{"/projects":{"get":{"operationId":"listProjects","summary":"List projects","description":"Newest first.","tags":["Projects"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"not":{}},{"type":"string","enum":["uploading","queued","processing","ready","failed"]}]}},{"name":"starting_after","in":"query","required":false,"schema":{"anyOf":[{"not":{}},{"type":"string","maxLength":40}],"description":"A project id; returns projects created before it."},"description":"A project id; returns projects created before it."}],"responses":{"200":{"description":"List projects","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Project"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"429":{"$ref":"#/components/responses/E429"}}},"post":{"operationId":"createProject","summary":"Create a project","description":"Send `source_url` to import a link, or `file_name` and `bytes` to upload a file. For uploads the response includes `upload.url`: PATCH the file to it in chunks, then call complete-upload.","tags":["Projects"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Replays the stored response for 24 hours when the same key is sent again."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"source_url":{"type":"string","format":"uri","maxLength":2048,"description":"Import from a link instead of uploading."},"file_name":{"type":"string","minLength":1,"maxLength":300,"description":"For uploads: the file name, with its extension."},"bytes":{"type":"integer","exclusiveMinimum":0,"maximum":4294967296,"description":"For uploads: exact file size in bytes."},"title":{"type":"string","minLength":1,"maxLength":200},"language":{"type":"string","minLength":2,"maxLength":12,"description":"Spoken language code, e.g. en, hi, ne, or auto (default)."},"webhook_url":{"type":"string","format":"uri","maxLength":2048,"description":"Called with this project's events, as well as your workspace endpoints."},"options":{"type":"object","properties":{"clip_length":{"type":"string","enum":["auto","short","medium","long"],"description":"Target clip length. short is about 15–30 s, medium 30–60 s, long 60–90 s. Default auto."},"max_clips":{"type":"integer","minimum":1,"maximum":15,"description":"Default 10."},"topics":{"type":"array","items":{"type":"string","minLength":1,"maxLength":80},"maxItems":10,"description":"Topic hints that boost matching moments and the transcription vocabulary."},"layout":{"type":"string","enum":["auto","single","split","pip"],"description":"Default auto."},"caption_preset":{"type":"string","enum":["bold-pop","karaoke","minimal","lower-third","boxed","outline","word-pop","ticker"],"description":"Shorthand for caption_style.preset. Default bold-pop."},"caption_style":{"type":"object","properties":{"preset":{"type":"string","enum":["bold-pop","karaoke","minimal","lower-third","boxed","outline","word-pop","ticker"]},"position":{"type":"string","enum":["top","middle","bottom"]},"words_per_line":{"type":"integer","minimum":1,"maximum":6},"uppercase":{"type":"boolean"},"highlight":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"}},"additionalProperties":false},"brand_kit_id":{"type":["string","null"],"description":"Reserved. Brand kits are not available yet, so send null or leave it out."},"aspect_ratios":{"type":"array","items":{"type":"string","enum":["9:16","1:1","4:5"]},"minItems":1,"maxItems":3,"description":"Output shapes: 9:16, 1:1 and 4:5. Default [\"9:16\"]. Previews use the first; renders take any of them."},"skip_intro_outro":{"type":"boolean","description":"Default true."},"remove_fillers":{"type":"boolean","description":"Cut um, uh and similar from clips. Default true."},"add_hooks":{"type":"boolean","description":"Show the hook title for the first seconds of each clip. Default false."}},"additionalProperties":false}},"additionalProperties":false}}}},"responses":{"201":{"description":"Create a project","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"402":{"$ref":"#/components/responses/E402"},"422":{"$ref":"#/components/responses/E422"},"429":{"$ref":"#/components/responses/E429"},"501":{"$ref":"#/components/responses/E501"}}}},"/projects/{id}":{"get":{"operationId":"getProject","summary":"Get a project","description":"Status, stage and progress. Poll this if you are not using webhooks.","tags":["Projects"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Get a project","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}}},"/projects/{id}/complete-upload":{"post":{"operationId":"completeUpload","summary":"Finish an upload","description":"Call once every byte is uploaded. Processing starts and the project moves to `queued`.","tags":["Projects"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Replays the stored response for 24 hours when the same key is sent again."}],"responses":{"200":{"description":"Finish an upload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"404":{"$ref":"#/components/responses/E404"},"409":{"$ref":"#/components/responses/E409"},"429":{"$ref":"#/components/responses/E429"}}}},"/projects/{id}/clips":{"get":{"operationId":"listProjectClips","summary":"List a project's clips","description":"Sorted by score, highest first.","tags":["Clips"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"List a project's clips","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Clip"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}}},"/projects/{id}/transcript":{"get":{"operationId":"getTranscript","summary":"Get the transcript","description":"JSON by default. Send `Accept: application/x-subrip` for SRT or `Accept: text/vtt` for WebVTT (or `?format=srt|vtt`).","tags":["Projects"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["json","srt","vtt"]},"description":"Overrides the Accept header."}],"responses":{"200":{"description":"Get the transcript","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transcript"}},"application/x-subrip":{"schema":{"type":"string","description":"SubRip subtitles"}},"text/vtt":{"schema":{"type":"string","description":"WebVTT subtitles"}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}}},"/clips/{id}":{"get":{"operationId":"getClip","summary":"Get a clip","description":"Includes the clip's transcript words, its edits and its crop path.","tags":["Clips"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Get a clip","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClipDetail"}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}},"patch":{"operationId":"updateClip","summary":"Edit a clip","description":"Change the start or end, cuts, layout, caption style or hook. Visual changes bump `version` and re-render the preview.","tags":["Clips"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":120},"hook":{"type":"string","minLength":1,"maxLength":60},"show_hook":{"type":"boolean"},"layout":{"type":"string","enum":["auto","single","split","pip"],"description":"auto, single, split, or pip (the speaker full frame with the other speaker in a corner)."},"caption_style":{"type":"object","properties":{"preset":{"type":"string","enum":["bold-pop","karaoke","minimal","lower-third","boxed","outline","word-pop","ticker"]},"position":{"type":"string","enum":["top","middle","bottom"]},"words_per_line":{"type":"integer","minimum":1,"maximum":6},"uppercase":{"type":"boolean"},"highlight":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"}},"additionalProperties":false},"start_s":{"type":"number","minimum":0,"description":"New start in source seconds; snapped to the first word that ends after it."},"end_s":{"type":"number","minimum":0,"description":"New end in source seconds; snapped to the last word that starts before it."},"start_word":{"type":"integer","minimum":0,"description":"New start as a transcript word index (wins over start_s)."},"end_word":{"type":"integer","minimum":0},"cuts":{"type":"array","items":{"type":"integer","minimum":0},"maxItems":5000,"description":"Word indices to remove. Replaces the current list."},"fixes":{"type":"object","additionalProperties":{"type":"string","maxLength":60},"propertyNames":{"pattern":"^\\d+$"},"description":"Word index to corrected spelling. Replaces the current map."}},"additionalProperties":false}}}},"responses":{"200":{"description":"Edit a clip","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClipDetail"}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}}},"/clips/{id}/render":{"post":{"operationId":"renderClip","summary":"Render a clip at 1080p","description":"Pick the shape with `aspect_ratio`. Returns a render to poll, or wait for `render.ready`. Asking again for the same clip version and shape returns the same render, unless the brand kit changed since. Exports include the brand kit's intro, outro, end card and music when they are on.","tags":["Renders"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Replays the stored response for 24 hours when the same key is sent again."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"resolution":{"type":"string","enum":["1080p"],"default":"1080p"},"aspect_ratio":{"type":"string","enum":["9:16","1:1","4:5"],"description":"9:16 (1080×1920), 1:1 (1080×1080) or 4:5 (1080×1350). Default: the project's first aspect ratio."}},"additionalProperties":false}}}},"responses":{"202":{"description":"Render a clip at 1080p","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Render"}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}}},"/clips/{id}/publish":{"post":{"operationId":"publishClip","summary":"Publish or schedule a clip","description":"Posts to a connected social account (see `GET /accounts`) now, or at `scheduled_at`. The `publication.posted` or `publication.failed` webhook follows.","tags":["Clips"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Replays the stored response for 24 hours when the same key is sent again."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"account_id":{"type":"string","minLength":1,"maxLength":100},"scheduled_at":{"type":"string","format":"date-time"},"caption":{"type":"string","maxLength":2200}},"required":["account_id"],"additionalProperties":false}}}},"responses":{"202":{"description":"Publish or schedule a clip","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"publication"}},"required":["object"],"additionalProperties":true}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"},"501":{"$ref":"#/components/responses/E501"}}}},"/renders/{id}":{"get":{"operationId":"getRender","summary":"Get a render","description":"Status and, when ready, a download URL valid 7 days.","tags":["Renders"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Get a render","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Render"}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}}},"/usage":{"get":{"operationId":"getUsage","summary":"Get usage","description":"Minutes used and remaining this month.","tags":["Usage"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Get usage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"429":{"$ref":"#/components/responses/E429"}}}},"/accounts":{"get":{"operationId":"listAccounts","summary":"List connected social accounts","description":"Channels connected in Settings → Schedule, for `POST /clips/{id}/publish`.","tags":["Clips"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"List connected social accounts","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","const":"account"},"id":{"type":"string"},"platform":{"type":"string","enum":["youtube","tiktok","instagram","facebook","linkedin"]},"handle":{"type":["string","null"]},"status":{"type":"string"},"sandbox":{"type":"boolean"},"connected_at":{"type":"string"}},"required":["object","id","platform","handle","status","sandbox","connected_at"],"additionalProperties":false}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"429":{"$ref":"#/components/responses/E429"}}}},"/webhooks":{"get":{"operationId":"listWebhooks","summary":"List webhook endpoints","tags":["Webhooks"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"List webhook endpoints","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"429":{"$ref":"#/components/responses/E429"}}},"post":{"operationId":"createWebhook","summary":"Add a webhook endpoint","description":"Used by integrations such as Zapier to subscribe. Endpoints added here also appear in Settings.","tags":["Webhooks"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Replays the stored response for 24 hours when the same key is sent again."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","maxLength":2048},"events":{"type":"array","items":{"type":"string","enum":["project.ready","project.failed","render.ready","publication.posted","publication.failed"]},"minItems":1,"description":"Default: every event."},"description":{"type":"string","maxLength":200}},"required":["url"],"additionalProperties":false}}}},"responses":{"201":{"description":"Add a webhook endpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"429":{"$ref":"#/components/responses/E429"}}}},"/webhooks/{id}":{"delete":{"operationId":"deleteWebhook","summary":"Remove a webhook endpoint","tags":["Webhooks"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Remove a webhook endpoint","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","const":"webhook_endpoint"},"deleted":{"type":"boolean","const":true}},"required":["id","object","deleted"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"401":{"$ref":"#/components/responses/E401"},"404":{"$ref":"#/components/responses/E404"},"429":{"$ref":"#/components/responses/E429"}}}},"/uploads/{id}":{"get":{"operationId":"getUpload","summary":"Get upload offset","description":"Use the signed `upload.url` from the project; no API key needed. Resume from `offset` after a dropped connection.","tags":["Uploads"],"security":[],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"exp","in":"query","required":true,"schema":{"type":"string"},"description":"Part of the signed upload URL."},{"name":"sig","in":"query","required":true,"schema":{"type":"string"},"description":"Part of the signed upload URL."}],"responses":{"200":{"description":"Get upload offset","content":{"application/json":{"schema":{"type":"object","properties":{"offset":{"type":"integer"},"bytes":{"type":"integer"},"completed":{"type":"boolean"}},"required":["offset","bytes","completed"],"additionalProperties":false}}}},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"}}},"patch":{"operationId":"uploadChunk","summary":"Upload a chunk","description":"Send up to `chunk_size` bytes with `Content-Type: application/offset+octet-stream` and `Upload-Offset` set to the current offset. A 409 `conflict` carries the server's offset in `error.details.offset`; resume from there. Not rate limited.","tags":["Uploads"],"security":[],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"exp","in":"query","required":true,"schema":{"type":"string"},"description":"Part of the signed upload URL."},{"name":"sig","in":"query","required":true,"schema":{"type":"string"},"description":"Part of the signed upload URL."},{"name":"Upload-Offset","in":"header","required":true,"schema":{"type":"integer","minimum":0}}],"requestBody":{"required":true,"content":{"application/offset+octet-stream":{"schema":{"type":"string","format":"binary","description":"The next bytes of the file."}}}},"responses":{"200":{"description":"Upload a chunk","content":{"application/json":{"schema":{"type":"object","properties":{"offset":{"type":"integer"}},"required":["offset"],"additionalProperties":false}}}},"400":{"$ref":"#/components/responses/E400"},"403":{"$ref":"#/components/responses/E403"},"404":{"$ref":"#/components/responses/E404"},"409":{"$ref":"#/components/responses/E409"}}}},"/openapi.json":{"get":{"operationId":"getOpenApi","summary":"This OpenAPI document","tags":["Meta"],"security":[],"responses":{"200":{"description":"This OpenAPI document"}}}}},"webhooks":{"project.ready":{"post":{"summary":"project.ready","parameters":[{"name":"X-ClipperGen-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\">` with your workspace signing secret."},{"name":"X-ClipperGen-Event","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-ClipperGen-Delivery","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Event id, the same on every retry. Use it to ignore duplicates."},"type":{"type":"string","const":"project.ready"},"created_at":{"type":"string"},"data":{"type":"object","properties":{"project":{"$ref":"#/components/schemas/Project"}},"required":["project"],"additionalProperties":false}},"required":["id","type","created_at","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx marks the delivery as done. Anything else is retried."}}}},"project.failed":{"post":{"summary":"project.failed","parameters":[{"name":"X-ClipperGen-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\">` with your workspace signing secret."},{"name":"X-ClipperGen-Event","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-ClipperGen-Delivery","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Event id, the same on every retry. Use it to ignore duplicates."},"type":{"type":"string","const":"project.failed"},"created_at":{"type":"string"},"data":{"type":"object","properties":{"project":{"$ref":"#/components/schemas/Project"}},"required":["project"],"additionalProperties":false}},"required":["id","type","created_at","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx marks the delivery as done. Anything else is retried."}}}},"render.ready":{"post":{"summary":"render.ready","parameters":[{"name":"X-ClipperGen-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\">` with your workspace signing secret."},{"name":"X-ClipperGen-Event","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-ClipperGen-Delivery","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Event id, the same on every retry. Use it to ignore duplicates."},"type":{"type":"string","const":"render.ready"},"created_at":{"type":"string"},"data":{"type":"object","properties":{"render":{"$ref":"#/components/schemas/Render"},"clip":{"type":"object","properties":{"id":{"type":"string"},"project_id":{"type":"string"},"rank":{"type":"integer"},"title":{"type":"string"},"score":{"type":"integer"}},"required":["id","project_id","rank","title","score"],"additionalProperties":false}},"required":["render","clip"],"additionalProperties":false}},"required":["id","type","created_at","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx marks the delivery as done. Anything else is retried."}}}},"publication.posted":{"post":{"summary":"publication.posted","parameters":[{"name":"X-ClipperGen-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\">` with your workspace signing secret."},{"name":"X-ClipperGen-Event","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-ClipperGen-Delivery","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Event id, the same on every retry. Use it to ignore duplicates."},"type":{"type":"string","const":"publication.posted"},"created_at":{"type":"string"},"data":{"type":"object","properties":{"publication":{"type":"object","additionalProperties":{}}},"required":["publication"],"additionalProperties":false}},"required":["id","type","created_at","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx marks the delivery as done. Anything else is retried."}}}},"publication.failed":{"post":{"summary":"publication.failed","parameters":[{"name":"X-ClipperGen-Signature","in":"header","required":true,"schema":{"type":"string"},"description":"`t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\">` with your workspace signing secret."},{"name":"X-ClipperGen-Event","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-ClipperGen-Delivery","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Event id, the same on every retry. Use it to ignore duplicates."},"type":{"type":"string","const":"publication.failed"},"created_at":{"type":"string"},"data":{"type":"object","properties":{"publication":{"type":"object","additionalProperties":{}}},"required":["publication"],"additionalProperties":false}},"required":["id","type","created_at","data"],"additionalProperties":false}}}},"responses":{"2XX":{"description":"Any 2xx marks the delivery as done. Anything else is retried."}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_request","unauthorized","quota_exceeded","unsupported_media","source_unreachable","not_found","rate_limited","processing_failed","conflict","not_available","internal_error"]},"message":{"type":"string","description":"What went wrong and what to do about it, in plain English."},"details":{"type":"object","additionalProperties":{},"description":"Extra context, e.g. `field` for a bad parameter or `offset` for an upload conflict."}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"description":"Every error has this shape."},"Project":{"type":"object","properties":{"id":{"type":"string","description":"Id, e.g. prj_7f3c2a91k2abcd"},"object":{"type":"string","const":"project"},"title":{"type":"string"},"status":{"type":"string","enum":["uploading","queued","processing","ready","failed"]},"stage":{"type":"string","enum":["upload","ingest","transcribe","select","render"],"description":"The step running now, or the last one."},"progress":{"type":"integer","minimum":0,"maximum":100,"description":"Overall processing progress."},"stage_progress":{"type":"integer","minimum":0,"maximum":100,"description":"Progress within the current stage (upload progress while uploading)."},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","const":"processing_failed"},"stage":{"type":["string","null"]},"message":{"type":"string"}},"required":["code","stage","message"],"additionalProperties":false},{"type":"null"}]},"source":{"type":"object","properties":{"type":{"type":"string","enum":["upload","url"]},"file_name":{"type":"string"},"bytes":{"type":"integer"},"url":{"type":["string","null"]}},"required":["type","file_name","bytes","url"],"additionalProperties":false},"duration_s":{"type":["number","null"]},"options":{"$ref":"#/components/schemas/ProjectOptions"},"webhook_url":{"type":["string","null"]},"clip_count":{"type":"integer"},"minutes_charged":{"type":"integer","description":"Charged once, when the project is ready. Failed projects cost nothing."},"minute_pool":{"type":"string","enum":["upload","api"],"description":"Which minute pool this project is charged to."},"upload":{"anyOf":[{"$ref":"#/components/schemas/Upload"},{"type":"null"}],"description":"Present while a project is waiting for its file."},"created_at":{"type":"string","description":"ISO 8601 timestamp"},"updated_at":{"$ref":"#/components/schemas/Project/properties/created_at"},"ready_at":{"type":["string","null"],"description":"ISO 8601 timestamp"}},"required":["id","object","title","status","stage","progress","stage_progress","error","source","duration_s","options","webhook_url","clip_count","minutes_charged","minute_pool","upload","created_at","updated_at","ready_at"],"additionalProperties":false},"ProjectOptions":{"type":"object","properties":{"clip_length":{"type":"string","enum":["auto","short","medium","long"]},"max_clips":{"type":"integer"},"topics":{"type":"array","items":{"type":"string"}},"layout":{"type":"string","enum":["auto","single","split","pip"]},"caption_preset":{"type":"string","enum":["bold-pop","karaoke","minimal","lower-third","boxed","outline","word-pop","ticker"]},"caption_style":{"$ref":"#/components/schemas/CaptionStyle"},"brand_kit_id":{"type":"null"},"aspect_ratios":{"type":"array","items":{"type":"string","enum":["9:16","1:1","4:5"]}},"skip_intro_outro":{"type":"boolean"},"remove_fillers":{"type":"boolean"},"add_hooks":{"type":"boolean"},"language":{"type":"string"}},"required":["clip_length","max_clips","topics","layout","caption_preset","caption_style","brand_kit_id","aspect_ratios","skip_intro_outro","remove_fillers","add_hooks","language"],"additionalProperties":false},"Upload":{"type":"object","properties":{"id":{"type":"string","description":"Id, e.g. upl_7f3c2a91k2abcd"},"url":{"type":"string","description":"Signed resumable upload URL. GET it for the current offset; PATCH chunks to it."},"offset":{"type":"integer","description":"Bytes received so far."},"bytes":{"type":"integer","description":"Total bytes expected."},"chunk_size":{"type":"integer","description":"Largest chunk the server accepts per PATCH."},"expires_at":{"type":"string","description":"When this URL stops working. GET the project for a fresh one."}},"required":["id","url","offset","bytes","chunk_size","expires_at"],"additionalProperties":false,"description":"Present while a project is waiting for its file."},"CaptionStyle":{"type":"object","properties":{"preset":{"type":"string","enum":["bold-pop","karaoke","minimal","lower-third","boxed","outline","word-pop","ticker"]},"position":{"type":"string","enum":["top","middle","bottom"]},"words_per_line":{"type":"integer","minimum":1,"maximum":6},"uppercase":{"type":"boolean"},"highlight":{"type":"string","description":"Hex colour of the active word, e.g. #6a3ae8"}},"required":["preset","position","words_per_line","uppercase","highlight"],"additionalProperties":false},"Clip":{"type":"object","properties":{"id":{"type":"string","description":"Id, e.g. clp_7f3c2a91k2abcd"},"object":{"type":"string","const":"clip"},"project_id":{"type":"string"},"rank":{"type":"integer","description":"1 is the strongest clip."},"title":{"type":"string"},"hook":{"type":"string"},"reason":{"type":"string","description":"Why this moment works, in one sentence."},"score":{"type":"integer","minimum":0,"maximum":100},"scores":{"type":"object","properties":{"hook":{"type":"number"},"self_contained":{"type":"number"},"payoff":{"type":"number"},"emotion":{"type":"number"},"clarity":{"type":"number"}},"required":["hook","self_contained","payoff","emotion","clarity"],"additionalProperties":false,"description":"The five criteria, each 0–20."},"start_s":{"type":"number"},"end_s":{"type":"number"},"duration_s":{"type":"number"},"layout":{"type":"string"},"caption_style":{"$ref":"#/components/schemas/CaptionStyle"},"show_hook":{"type":"boolean"},"status":{"type":"string","enum":["rendering","ready","failed"],"description":"State of the preview, 540 wide in the project's first aspect ratio."},"error":{"type":["string","null"]},"version":{"type":"integer","description":"Goes up with every visual edit."},"preview_url":{"type":["string","null"],"description":"Preview MP4, 540 wide, valid 24 hours."},"poster_url":{"type":["string","null"]},"created_at":{"$ref":"#/components/schemas/Project/properties/created_at"},"updated_at":{"$ref":"#/components/schemas/Project/properties/created_at"}},"required":["id","object","project_id","rank","title","hook","reason","score","scores","start_s","end_s","duration_s","layout","caption_style","show_hook","status","error","version","preview_url","poster_url","created_at","updated_at"],"additionalProperties":false},"ClipDetail":{"type":"object","properties":{"id":{"$ref":"#/components/schemas/Clip/properties/id"},"object":{"$ref":"#/components/schemas/Clip/properties/object"},"project_id":{"$ref":"#/components/schemas/Clip/properties/project_id"},"rank":{"$ref":"#/components/schemas/Clip/properties/rank"},"title":{"$ref":"#/components/schemas/Clip/properties/title"},"hook":{"$ref":"#/components/schemas/Clip/properties/hook"},"reason":{"$ref":"#/components/schemas/Clip/properties/reason"},"score":{"$ref":"#/components/schemas/Clip/properties/score"},"scores":{"$ref":"#/components/schemas/Clip/properties/scores"},"start_s":{"$ref":"#/components/schemas/Clip/properties/start_s"},"end_s":{"$ref":"#/components/schemas/Clip/properties/end_s"},"duration_s":{"$ref":"#/components/schemas/Clip/properties/duration_s"},"layout":{"$ref":"#/components/schemas/Clip/properties/layout"},"caption_style":{"$ref":"#/components/schemas/CaptionStyle"},"show_hook":{"$ref":"#/components/schemas/Clip/properties/show_hook"},"status":{"$ref":"#/components/schemas/Clip/properties/status"},"error":{"$ref":"#/components/schemas/Clip/properties/error"},"version":{"$ref":"#/components/schemas/Clip/properties/version"},"preview_url":{"$ref":"#/components/schemas/Clip/properties/preview_url"},"poster_url":{"$ref":"#/components/schemas/Clip/properties/poster_url"},"created_at":{"$ref":"#/components/schemas/Project/properties/created_at"},"updated_at":{"$ref":"#/components/schemas/Project/properties/created_at"},"output_duration_s":{"type":"number","description":"Length after cuts."},"edits":{"type":"object","properties":{"start_word":{"type":"integer"},"end_word":{"type":"integer"},"cuts":{"type":"array","items":{"type":"integer"}},"fixes":{"type":"object","additionalProperties":{"type":"string"}}},"required":["start_word","end_word","cuts","fixes"],"additionalProperties":false},"words":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"text":{"type":"string"},"start_s":{"type":"number"},"end_s":{"type":"number"},"speaker":{"type":"integer"},"cut":{"type":"boolean"}},"required":["index","text","start_s","end_s","speaker","cut"],"additionalProperties":false},"description":"Transcript words inside the clip, with indices for edits."},"crop_path":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"t":{"type":"number"},"x":{"type":"number"},"y":{"type":"number"},"w":{"type":"number"},"h":{"type":"number"}},"required":["t","x","y","w","h"],"additionalProperties":false}},{"type":"null"}],"description":"Crop keyframes once speaker tracking is available; null while clips use the centre crop."}},"required":["id","object","project_id","rank","title","hook","reason","score","scores","start_s","end_s","duration_s","layout","caption_style","show_hook","status","error","version","preview_url","poster_url","created_at","updated_at","output_duration_s","edits","words","crop_path"],"additionalProperties":false},"Render":{"type":"object","properties":{"id":{"type":"string","description":"Id, e.g. rnd_7f3c2a91k2abcd"},"object":{"type":"string","const":"render"},"clip_id":{"type":"string"},"project_id":{"type":"string"},"kind":{"type":"string","enum":["proxy","final"]},"aspect_ratio":{"type":"string","enum":["9:16","1:1","4:5"]},"resolution":{"type":"string","enum":["540p","1080p"],"description":"By width: 1080 wide for finals, 540 for previews."},"width":{"type":"integer"},"height":{"type":"integer"},"intro_s":{"type":"number","description":"Seconds of the brand kit's intro card before the clip. Shift subtitle times by this much to match the file."},"status":{"type":"string","enum":["queued","running","ready","failed"]},"error":{"type":["string","null"]},"clip_version":{"type":"integer"},"download_url":{"type":["string","null"],"description":"Signed MP4 download, valid 7 days."},"download_expires_at":{"type":["string","null"],"description":"ISO 8601 timestamp"},"created_at":{"$ref":"#/components/schemas/Project/properties/created_at"},"finished_at":{"type":["string","null"],"description":"ISO 8601 timestamp"}},"required":["id","object","clip_id","project_id","kind","aspect_ratio","resolution","width","height","intro_s","status","error","clip_version","download_url","download_expires_at","created_at","finished_at"],"additionalProperties":false},"Transcript":{"type":"object","properties":{"object":{"type":"string","const":"transcript"},"project_id":{"type":"string"},"provider":{"type":"string","description":"deepgram, or mock when the server has no transcription key."},"language":{"type":"string"},"speakers":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"name":{"type":"string"}},"required":["index","name"],"additionalProperties":false}},"words":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"text":{"type":"string"},"start_s":{"type":"number"},"end_s":{"type":"number"},"speaker":{"type":"integer"},"confidence":{"type":["number","null"]}},"required":["index","text","start_s","end_s","speaker","confidence"],"additionalProperties":false}}},"required":["object","project_id","provider","language","speakers","words"],"additionalProperties":false},"Usage":{"type":"object","properties":{"object":{"type":"string","const":"usage"},"plan":{"type":"string"},"period_start":{"$ref":"#/components/schemas/Project/properties/created_at"},"period_end":{"$ref":"#/components/schemas/Project/properties/created_at"},"upload_minutes":{"type":"object","properties":{"used":{"type":"integer"},"quota":{"type":"integer"},"remaining":{"type":"integer"}},"required":["used","quota","remaining"],"additionalProperties":false},"api_minutes":{"anyOf":[{"type":"object","properties":{"used":{"type":"integer"},"quota":{"type":"integer"},"remaining":{"type":"integer"}},"required":["used","quota","remaining"],"additionalProperties":false},{"type":"null"}],"description":"The separate API pool on plans that include one; null when API projects share upload minutes."},"api_projects_charge":{"type":"string","enum":["upload_minutes","api_minutes"]},"rate_limit":{"type":"object","properties":{"limit":{"type":"integer"},"remaining":{"type":"integer"},"window_s":{"type":"integer"}},"required":["limit","remaining","window_s"],"additionalProperties":false}},"required":["object","plan","period_start","period_end","upload_minutes","api_minutes","api_projects_charge","rate_limit"],"additionalProperties":false},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string","description":"Id, e.g. whe_7f3c2a91k2abcd"},"object":{"type":"string","const":"webhook_endpoint"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string","enum":["project.ready","project.failed","render.ready","publication.posted","publication.failed"]}},"description":{"type":"string"},"enabled":{"type":"boolean"},"created_at":{"$ref":"#/components/schemas/Project/properties/created_at"}},"required":["id","object","url","events","description","enabled","created_at"],"additionalProperties":false}},"responses":{"E400":{"description":"Invalid request (`invalid_request`, `unsupported_media`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E401":{"description":"Missing, invalid or revoked API key (`unauthorized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E402":{"description":"Out of minutes this month (`quota_exceeded`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E403":{"description":"The signed upload URL is invalid or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E404":{"description":"Not found in this workspace (`not_found`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E409":{"description":"Conflicts with the current state (`conflict`), e.g. an upload offset that is out of date.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E422":{"description":"The link could not be fetched (`source_unreachable`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E429":{"description":"Rate limited (`rate_limited`). Wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"E501":{"description":"Not available on this server yet (`not_available`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"A workspace API key, e.g. cg_sk_…"}}}}