Videos
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.
POST
/
runwayml
/
v1
/
video_to_video
cURL
curl --request POST \
--url https://api.cometapi.com/runwayml/v1/video_to_video \
--header "Authorization: Bearer $COMETAPI_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "aleph2",
"videoUri": "https://example.com/source-video.mp4",
"promptText": "Turn the daytime scene into a snowy winter evening."
}'import os
import requests
response = requests.post(
"https://api.cometapi.com/runwayml/v1/video_to_video",
headers={"Authorization": f"Bearer {os.environ['COMETAPI_KEY']}"},
json={
"model": "aleph2",
"videoUri": "https://example.com/source-video.mp4",
"promptText": "Turn the daytime scene into a snowy winter evening."
},
)
response.raise_for_status()
print(response.json())const response = await fetch(
"https://api.cometapi.com/runwayml/v1/video_to_video",
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.COMETAPI_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"model": "aleph2",
"videoUri": "https://example.com/source-video.mp4",
"promptText": "Turn the daytime scene into a snowy winter evening."
}),
},
);
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cometapi.com/runwayml/v1/video_to_video",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'model' => 'aleph2',
'videoUri' => 'https://example.com/source-video.mp4'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.cometapi.com/runwayml/v1/video_to_video"
payload := strings.NewReader("{\n \"model\": \"aleph2\",\n \"videoUri\": \"https://example.com/source-video.mp4\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.cometapi.com/runwayml/v1/video_to_video")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"model\": \"aleph2\",\n \"videoUri\": \"https://example.com/source-video.mp4\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cometapi.com/runwayml/v1/video_to_video")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"model\": \"aleph2\",\n \"videoUri\": \"https://example.com/source-video.mp4\"\n}"
response = http.request(request)
puts response.read_body{
"id": "00000000-0000-4000-8000-000000000000"
}{
"code": "<string>",
"message": "<string>",
"data": "<unknown>"
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>"
}
}Use
The keyframe timestamp must fall inside its edit window. If you use
If
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:
| Field | Meaning |
|---|---|
seconds | Timestamp from the video start, from 0 through 30 seconds. |
at | Fraction of the video duration, from 0 through 1. |
range.start_seconds | Inclusive start of an optional edit window, in whole seconds. |
range.end_seconds | Exclusive end of that window, in whole seconds; must exceed its start. |
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 | Output |
|---|---|
mp4 | H.264 MP4; used when the field is omitted. |
prores | ProRes MOV. |
png_sequence | ZIP archive containing PNG frames. |
sdr_rec709_10bit | 10-bit Rec.709 HEVC MP4. |
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.Body
application/json
Aleph 2 video-editing request.
Response
The task was created. Save its id for task retrieval.
Last modified on September 22, 2026
⌘I
cURL
curl --request POST \
--url https://api.cometapi.com/runwayml/v1/video_to_video \
--header "Authorization: Bearer $COMETAPI_KEY" \
--header "Content-Type: application/json" \
--data '{
"model": "aleph2",
"videoUri": "https://example.com/source-video.mp4",
"promptText": "Turn the daytime scene into a snowy winter evening."
}'import os
import requests
response = requests.post(
"https://api.cometapi.com/runwayml/v1/video_to_video",
headers={"Authorization": f"Bearer {os.environ['COMETAPI_KEY']}"},
json={
"model": "aleph2",
"videoUri": "https://example.com/source-video.mp4",
"promptText": "Turn the daytime scene into a snowy winter evening."
},
)
response.raise_for_status()
print(response.json())const response = await fetch(
"https://api.cometapi.com/runwayml/v1/video_to_video",
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.COMETAPI_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"model": "aleph2",
"videoUri": "https://example.com/source-video.mp4",
"promptText": "Turn the daytime scene into a snowy winter evening."
}),
},
);
if (!response.ok) throw new Error(await response.text());
console.log(await response.json());<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.cometapi.com/runwayml/v1/video_to_video",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'model' => 'aleph2',
'videoUri' => 'https://example.com/source-video.mp4'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.cometapi.com/runwayml/v1/video_to_video"
payload := strings.NewReader("{\n \"model\": \"aleph2\",\n \"videoUri\": \"https://example.com/source-video.mp4\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.cometapi.com/runwayml/v1/video_to_video")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"model\": \"aleph2\",\n \"videoUri\": \"https://example.com/source-video.mp4\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.cometapi.com/runwayml/v1/video_to_video")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"model\": \"aleph2\",\n \"videoUri\": \"https://example.com/source-video.mp4\"\n}"
response = http.request(request)
puts response.read_body{
"id": "00000000-0000-4000-8000-000000000000"
}{
"code": "<string>",
"message": "<string>",
"data": "<unknown>"
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>"
}
}