Skip to main content
POST
cURL
Use 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 model to aleph2 and provide videoUri for a video of up to 30 seconds.
  • Optional: include promptText to 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 in keyframes. Each object contains an image uri and exactly one position: The keyframe timestamp must fall inside its edit window. If you use 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

Use targetAspectRatio 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. If 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 returned id 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

Authorization
string
header
required

Your CometAPI API key.

Body

application/json

Aleph 2 video-editing request.

model
enum<string>
required

Model ID for this request.

Available options:
aleph2
videoUri
required

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.

Required string length: 13 - 2048
Pattern: ^https://
promptText
string

Optional instruction describing the edit, from 1 to 1,000 characters. Can be omitted when using keyframes.

Required string length: 1 - 1000
keyframes
object[] | null

One 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.

Maximum array length: 5

Guidance image positioned using seconds.

targetAspectRatio
enum<string>

Target aspect ratio for expansion. The input video and keyframes are letterboxed to this shape before generation.

Available options:
16:9,
4:3,
3:2,
1:1,
2:3,
3:4,
9:16,
21:9
ratio
string
deprecated

Deprecated aspect-ratio field. Use targetAspectRatio instead.

seed
integer

Sampling seed. Omit for a random seed; 0 is treated as omission.

Required range: 0 <= x <= 4294967295
outputFormat
enum<string>

Output 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.

Available options:
mp4,
prores,
png_sequence,
sdr_rec709_10bit
proresProfile
enum<string>

ProRes profile. Include only with outputFormat set to prores; omit for 4444. The 4444 and 4444 XQ profiles have an opaque alpha channel.

Available options:
422,
4444,
422 Proxy,
422 LT,
422 HQ,
4444 XQ
contentModeration
object

Content moderation settings. Omit to use the standard settings.

Response

The task was created. Save its id for task retrieval.

id
string
required

Task ID for GET /runwayml/v1/tasks/{id}.

status
string

Task state, when returned.

createdAt
string<date-time>

Task submission timestamp, when returned.

output
string<uri>[]

Result URLs, when returned.

failure
string

Failure explanation, when returned.

failureCode
string

Machine-readable failure code, when returned.

estimatedCost
object

Task estimate metadata, when returned.

cost
object

Task cost metadata, when returned.

Last modified on September 22, 2026