Update Video | TutorFlow Agent Platform Docs

Authenticated Update Endpoints

These endpoints use the Platform API key and the video request id returned by Create Video. Use them when an agent or backend needs to edit video metadata, scene scripts, scene layout, timing, subtitles, clips, or effects without using the public editToken.

All paths are prefixed with /v1/platform/videos/:id.

Method	Path	Purpose
`PATCH`	`/`	Update video metadata
`POST`	`/scenes`	Add a scene
`PATCH`	`/scenes/:sceneId`	Update a scene
`DELETE`	`/scenes/:sceneId`	Delete a scene
`PUT`	`/scenes/reorder`	Reorder scenes

Updates are available after the video generation request has completed.

PATCH /

Updates video-level metadata.

curl -X PATCH https://api.tutorflow.io/v1/platform/videos/{id} \
  -H "Authorization: Bearer tf_platform_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Photosynthesis for Kids",
    "description": "Updated narration and scene plan.",
    "aspectRatio": "9:16",
    "bgmAudioKey": "platform/{workspaceId}/bgm/calm.mp3",
    "bgmVolume": 0.2,
    "bgmOffset": 0,
    "userNarrationScript": "Custom full-video narration notes.",
    "thumbnailKey": "platform/{workspaceId}/videos/{videoId}/thumb.jpg",
    "metadata": { "language": "en", "targetDurationSeconds": 45 }
  }'

Body

Field	Type	Description
`title`	`string`	Video title
`description`	`string`	Video description
`aspectRatio`	`string`	`16:9`, `9:16`, or `1:1`
`bgmAudioKey`	`string`	S3 key for background music
`bgmVolume`	`number`	Background music volume
`bgmOffset`	`number`	Start offset in seconds
`userNarrationScript`	`string`	Manual narration notes or override
`videoKey`	`string`	Rendered mp4 key
`thumbnailKey`	`string`	Thumbnail image key
`renderStatus`	`string`	Render status override
`metadata`	`object`	Free-form metadata

Returns VideoEditResDto, including all scenes.

POST /scenes

Adds a scene to the video.

curl -X POST https://api.tutorflow.io/v1/platform/videos/{id}/scenes \
  -H "Authorization: Bearer tf_platform_..." \
  -H "Content-Type: application/json" \
  -d '{
    "script": "Plants use sunlight to turn water and carbon dioxide into food.",
    "displayText": "Plants make food from sunlight",
    "remotionTemplate": "keyword",
    "keywords": ["plant", "sunlight", "leaf"],
    "duration": 7,
    "transitionOut": "fade"
  }'

Body

Field	Type	Required	Description
`script`	`string`	Yes	Narration script for the scene
`order`	`number`	No	0-indexed scene order. Defaults to the end.
`displayText`	`string`	No	On-screen text
`remotionTemplate`	`string`	No	Scene layout/template, such as `keyword`, `title`, or `quote`
`keywords`	`string[]`	No	Keywords for clip search and overlays
`duration`	`number`	No	Scene duration in seconds
`transitionOut`	`string`	No	Transition to the next scene

Returns the created VideoSceneResDto.

PATCH /scenes/:sceneId

Updates any supported scene field, including script, layout, timing, subtitles, clip settings, effects, and metadata.

curl -X PATCH https://api.tutorflow.io/v1/platform/videos/{id}/scenes/{sceneId} \
  -H "Authorization: Bearer tf_platform_..." \
  -H "Content-Type: application/json" \
  -d '{
    "order": 1,
    "script": "The leaves capture sunlight using chlorophyll.",
    "displayText": "Leaves capture sunlight",
    "ttsAudioKey": "platform/{workspaceId}/videos/{videoId}/scenes/{sceneId}/tts.mp3",
    "videoClipKey": "platform/{workspaceId}/videos/{videoId}/clips/leaf.mp4",
    "videoClipSource": "custom",
    "remotionTemplate": "keyword",
    "keywords": ["leaf", "chlorophyll"],
    "duration": 6.5,
    "audioOffset": 0,
    "audioDuration": 5.8,
    "videoOffset": 1.2,
    "videoDuration": 6.5,
    "subtitleOffset": 0,
    "subtitleDuration": 5.8,
    "subtitles": [
      { "text": "The leaves capture sunlight", "offset": 0, "duration": 2.7 }
    ],
    "transitionOut": "fade",
    "transitionDuration": 0.5,
    "videoEffect": "vignette",
    "metadata": { "shot": "close-up" }
  }'

Body

Field	Type	Description
`order`	`number`	Scene order
`script`	`string`	Narration script. Updating this does not regenerate TTS automatically.
`displayText`	`string`	On-screen text
`ttsAudioKey`	`string`	TTS audio key
`videoClipKey`	`string`	Clip key
`videoClipSource`	`string`	Clip source, such as `stock` or `custom`
`remotionTemplate`	`string`	Scene layout/template
`keywords`	`string[]`	Clip search and overlay keywords
`duration`	`number`	Scene duration in seconds
`audioOffset` / `audioDuration`	`number`	TTS timing
`videoOffset` / `videoDuration`	`number`	Clip timing
`subtitleOffset` / `subtitleDuration`	`number`	Subtitle timing
`subtitles`	`array`	Subtitle chunks: `[{ text, offset, duration }]`
`transitionOut`	`string`	Transition style
`transitionDuration`	`number`	Transition duration in seconds
`videoEffect`	`string`	Visual effect
`metadata`	`object`	Free-form metadata

Returns the updated VideoSceneResDto.

DELETE /scenes/:sceneId

Deletes a scene.

curl -X DELETE https://api.tutorflow.io/v1/platform/videos/{id}/scenes/{sceneId} \
  -H "Authorization: Bearer tf_platform_..."

Returns 204 No Content.

PUT /scenes/reorder

Replaces scene order with the supplied scene ID list.

curl -X PUT https://api.tutorflow.io/v1/platform/videos/{id}/scenes/reorder \
  -H "Authorization: Bearer tf_platform_..." \
  -H "Content-Type: application/json" \
  -d '{ "sceneIds": ["uuid-3", "uuid-1", "uuid-2"] }'

The list length must equal the current scene count, and every id must belong to the video.

Returns the updated VideoEditResDto.