Store harvested still frames of a scene
Multipart. Part meta (JSON): { composition_version, duration_ms, source: "agent"|"editor"|"worker", frames: [{ t_ms, width, height }] }; then one frames file per entry, in order (webp, jpeg or png, sn
Multipart. Part meta (JSON): { composition_version, duration_ms, source: "agent"|"editor"|"worker", frames: [{ t_ms, width, height }] }; then one frames file per entry, in order (webp, jpeg or png, sniffed by magic bytes; the declared size must match the image). Needs the editor role on the scene's project. The frames must belong to the scene's CURRENT composition_version and duration (409 stale_version / duration_mismatch with the current values otherwise). At most 16 frames per call and 16 stored per scene version, each at most 400 KB and 160..960 px wide with t_ms inside the duration (413 over the size caps). A frame at an occupied slot (same t_ms and width, or within 150 ms) is a duplicate unless its source outranks the stored one (worker > agent > editor), which replaces it. Stored publicly under media/<account>/frames/<scene>/<version>/. On success the scene's published thumbnail_url and filmstrip_url move forward to this version (never back to an older one). About 200 calls per hour per account.
Authorization
bearerAuth Typecut API key. Generate one in app.typecut.ai → Settings → API keys. Send as Authorization: Bearer tc_live_….
In: header
Path Parameters
uuidRequest Body
multipart/form-data
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/scenes/497f6eca-6276-4993-bfeb-53cbbbba6f08/frames" \ -F meta="{\"composition_version\":7,\"duration_ms\":5000,\"source\":\"editor\",\"frames\":[{\"t_ms\":250,\"width\":480,\"height\":270}]}" \ -F frames="[ \"string\" ]"{
"data": {
"scene_id": "861eef56-1159-4a95-802f-abab2d0cc192",
"composition_version": 0,
"duration_ms": 0,
"results": [
{
"t_ms": 0,
"width": 0,
"status": "stored",
"url": "string"
}
],
"stored": 0,
"replaced": 0,
"duplicates": 0,
"rejected_cap": 0,
"published": {
"moved": true,
"thumbnail_url": "string",
"filmstrip_url": "string"
}
}
}{
"error": {
"type": "string",
"code": "string",
"message": "string"
}
}{
"error": {
"type": "string",
"code": "string",
"message": "string"
}
}{
"error": {
"type": "string",
"code": "string",
"message": "string"
}
}{
"error": {
"type": "string",
"code": "string",
"message": "string"
}
}{
"error": {
"type": "string",
"code": "string",
"message": "string"
}
}{
"error": {
"type": "string",
"code": "string",
"message": "string"
}
}{
"error": {
"type": "string",
"code": "string",
"message": "string"
}
}{
"error": {
"type": "string",
"code": "string",
"message": "string"
}
}