Change a video

A finished video can change in two calls: PATCH /v1/videos/{id} records what the video should be, and POST /v1/videos/{id}/generate makes it. Nothing is made or charged until you call generate.

PATCH /v1/videos/{id} takes any of these fields:

Field	What it changes
`aspectRatio`	The video’s frame: `16:9` (landscape) or `9:16` (vertical).
`audioId`	A new audio track: a completed narration or a `voiceover` asset, for example the script in another language. See One video, many languages.
`audioTrackId`	One of the video’s earlier audio tracks, to play again.

{id} is the id POST /v1/videos returned, the same id GET /v1/videos/{id} reads.

1. Record the change

curl -X PATCH "https://api.scenema.ai/v1/videos/proj_7c2e91a04b6d3f8" \
  -H "Authorization: Bearer $SCENEMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"aspectRatio": "9:16"}'

Everything is checked at once: an unknown track or narration, a video still being made, a video cut to music all answer with their error here. The answer is the video as it is, with the change in pending:

{ "id": "proj_7c2e91a04b6d3f8", "status": "completed", "aspectRatio": "16:9", "pending": { "aspectRatio": "9:16" } }

Send PATCH again to add to the change or alter it: fields merge. A field set back to what the video has leaves pending, and a field sent as null (for example {"audioId": null}) is cleared from it, so a change can be undone before it is made.

2. Make it

curl -X POST "https://api.scenema.ai/v1/videos/proj_7c2e91a04b6d3f8/generate" \
  -H "Authorization: Bearer $SCENEMA_API_KEY" \
  -H "Idempotency-Key: 6f1c2a90-vertical"

Generate makes everything pending as one change. When something has to be made or exported, it answers 202 with the video processing, which goes through its stages, then completed, and video.completed arrives at its webhook once for the change. When nothing has to be made (a switch to a ratio already made), it answers 200 with the video completed. With nothing pending, it changes nothing and answers 200.

pending empties as the change starts. A generate that is refused (402, or a video already changing) keeps it, so the same generate can be sent again later. A generate that fails with a server error (5xx) does not put it back, so a change is never made twice: read the video, and if it is not processing and pending is empty, send the PATCH again.

A pending audio track and aspect ratio are made in order: the audio track first, then the aspect ratio. A video given a Spanish track and 9:16 is made in 9:16 with the Spanish track, and its 16:9 MP4 is exported again with the Spanish track as well. Such a change reports once, when the new ratio is made: one video.completed (or video.failed) for the whole change.

The video in another aspect ratio

A video made in 16:9 for YouTube can be made in 9:16 for Shorts, Reels and TikTok, and back. The video keeps its storyboard, its design, its narration and its length; only the frame changes.

A ratio the video was never made in. Its keyframes and clips are generated for the new frame, then the video is exported. It costs 15 credits per second at 480p, held when generate is accepted (see Pricing and limits). The stages are images, animation and export.
A ratio the video was made in. The video switches to it at once, and nothing is charged.
A ratio made with an earlier audio track. The video is exported again in that ratio with the track it plays now. Free.

While a new ratio is made, it reads processing in formats, and the MP4s the video already has stay there. Once it is completed, video is the MP4 in the video’s current aspectRatio, and formats lists every ratio:

{
  "id": "proj_7c2e91a04b6d3f8",
  "status": "completed",
  "aspectRatio": "9:16",
  "video": { "url": "https://cdn.scenema.ai/media/...9x16.mp4?...", "width": 480, "height": 854 },
  "formats": [
    { "aspectRatio": "16:9", "status": "completed", "outdated": false, "video": { "url": "https://cdn.scenema.ai/media/...16x9.mp4?...", "width": 854, "height": 480 }, "errorCode": null, "retryable": false },
    { "aspectRatio": "9:16", "status": "completed", "outdated": false, "video": { "url": "https://cdn.scenema.ai/media/...9x16.mp4?...", "width": 480, "height": 854 }, "errorCode": null, "retryable": false }
  ]
}

outdated: true marks an MP4 made with an earlier audio track. Change the video to that ratio (PATCH, then generate) to export it again with the current track, free.

Captions come in every ratio’s MP4, inside its frame, with the SRT file in captionsUrl.

Audio tracks

audioId gives the video a new track and audioTrackId switches back to an earlier one; both are free. One video, many languages covers both, with the track list.

When the video has MP4s in two ratios, a new track is exported in the video’s current ratio. The other ratio’s MP4 keeps the earlier track and reads outdated: true until the video is changed to that ratio. To have both ratios with the new track, put the track and the other ratio in one change before you call generate.

Safe to send again

PATCH is safe to send again as it is: it records the same change. Send an Idempotency-Key header with any unique string per generate. A repeated key returns the video and makes nothing more, so a generate that timed out can be sent again safely.

When a change fails

A new ratio that fails on the way leaves the video as it was: it stays completed in the ratio it had, with that MP4 in video, and error says why. The ratio reads failed in formats, with its errorCode and retryable, and video.failed arrives at the webhook for the change. Other changes stay allowed.

{
  "status": "completed",
  "aspectRatio": "16:9",
  "formats": [
    { "aspectRatio": "16:9", "status": "completed", "outdated": false, "video": { "url": "https://cdn.scenema.ai/media/...16x9.mp4?..." }, "errorCode": null, "retryable": false },
    { "aspectRatio": "9:16", "status": "failed", "outdated": false, "video": null, "errorCode": "PROVIDER_FAILED", "retryable": true }
  ]
}

To retry it, change the video to that ratio again (PATCH, then generate), or send POST /v1/videos/{id}/retry (Failures and retries). The retry reuses every keyframe and clip already made and holds only what is left of the new ratio’s price, so a ratio never costs more than once, up to 3 retries within 7 days.

An audio track change that fails leaves the video as it was, with error saying why. A new ratio sent with it is not made, and its held credits go back.

When a change cannot be made

Status	Code	When
400	`INVALID_REQUEST`	The request asks for nothing, both `audioId` and `audioTrackId` were sent, or `aspectRatio` is not `16:9` or `9:16`.
402	`INSUFFICIENT_CREDITS`	On generate: the workspace cannot hold the new ratio’s price. Nothing changes, and the change stays pending.
404	`VIDEO_NOT_FOUND`	No such video in this workspace.
404	`AUDIO_TRACK_NOT_FOUND`	No track with that id on this video.
409	`VIDEO_NOT_READY`	The video is still being made. Change it once it has completed.
409	`VIDEO_FAILED`	The video itself failed (its first ratio). Retry it, or make a new video.
409	`VIDEO_BUSY`	The video is already changing (or another PATCH or generate is in progress). Try again once it has completed.
409	`MUSIC_LOCKED`	The video is cut to its music, or the audio is a `soundtrack` asset. Make a new video for other audio.
422	`AUDIO_TRACK_UNUSABLE`	The new audio cannot be matched to the video. The change stays pending: clear it with `{"audioId": null}`, or PATCH another track.