Create a Runway video-to-video task
Edit a video with Runway Aleph 2 through CometAPI, using a text prompt, timed guidance images, and an optional target aspect ratio.
aleph2 to edit a source video with a text prompt. The request returns a
task id; retrieve task details to get the finished output.
Prepare the request
- Authenticate with your CometAPI API key.
- Set
modeltoaleph2and providevideoUrifor a video of up to 30 seconds. - Optional: include
promptTextto describe the edit, with 1 to 1,000 characters. You can also omit it when using keyframes. - Replace the example media URL with an accessible HTTPS URL. Media fields also accept Base64 data URIs with an encoded size of up to 5 MB.
Add timed guidance images
To guide particular moments, supply one to five objects inkeyframes.
Each object contains an image uri and exactly one position:
range,
set it on every keyframe. Otherwise, omit range from every keyframe.
Omit keyframes when you do not need guidance images. An empty array or
null is treated as omission.
Choose the frame shape and format
UsetargetAspectRatio to request expansion to 16:9, 4:3, 3:2, 1:1,
2:3, 3:4, 9:16, or 21:9. The input video and guidance images are
letterboxed to this shape before generation. The deprecated ratio field
is optional; use targetAspectRatio for aspect-ratio control.
outputFormat is prores, you can set proresProfile to 422, 4444,
422 Proxy, 422 LT, 422 HQ, or 4444 XQ. The default profile is 4444.
The alpha channel in 4444 and 4444 XQ is opaque. Omit proresProfile
for other output formats.
For an explicit sampling seed, use 1 through 4294967295. Omit seed
for a random seed; 0 is treated as omission.
Retrieve the result
Save the returnedid and use
Get a Runway task to retrieve the task status.
When status is SUCCEEDED, read the result URLs from output. If the task
fails, inspect failure and failureCode when present.Authorizations
Your CometAPI API key.
Body
Aleph 2 video-editing request.
Model ID for this request.
aleph2 Input video to edit, with a maximum duration of 30 seconds. Use an accessible HTTPS URL or a Base64 data URI with an encoded size of up to 5 MB.
13 - 2048^https://Optional instruction describing the edit, from 1 to 1,000 characters. Can be omitted when using keyframes.
1 - 1000One to five timed guidance images. Each image uses exactly one of seconds or at. Omit when no guidance images are needed; an empty array or null is treated as omission.
5Guidance image positioned using seconds.
- Option 1
- Option 2
Target aspect ratio for expansion. The input video and keyframes are letterboxed to this shape before generation.
16:9, 4:3, 3:2, 1:1, 2:3, 3:4, 9:16, 21:9 Deprecated aspect-ratio field. Use targetAspectRatio instead.
Sampling seed. Omit for a random seed; 0 is treated as omission.
0 <= x <= 4294967295Output format: mp4 for H.264 MP4, prores for ProRes MOV, png_sequence for a ZIP of PNG frames, or sdr_rec709_10bit for 10-bit Rec.709 HEVC MP4. Omit for mp4.
mp4, prores, png_sequence, sdr_rec709_10bit ProRes profile. Include only with outputFormat set to prores; omit for 4444. The 4444 and 4444 XQ profiles have an opaque alpha channel.
422, 4444, 422 Proxy, 422 LT, 422 HQ, 4444 XQ Content moderation settings. Omit to use the standard settings.
Response
The task was created. Save its id for task retrieval.
Task ID for GET /runwayml/v1/tasks/{id}.
Task state, when returned.
Task submission timestamp, when returned.
Result URLs, when returned.
Failure explanation, when returned.
Machine-readable failure code, when returned.
Task estimate metadata, when returned.
Task cost metadata, when returned.