Skip to main content
POST
/
runwayml
/
v1
/
video_to_video
cURL
curl https://api.cometapi.com/runwayml/v1/video_to_video \
  -H "Authorization: Bearer $COMETAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "videoUri": "https://your-video-host/source.mp4",
      "promptText": "Make the motion feel cinematic.",
      "model": "gen4_aleph",
      "references": [
        {
          "type": "image",
          "uri": "https://your-image-host/style.jpg"
        }
      ]
    }'
{
  "id": "12a01a5e-ab55-4aa7-b002-7b873546cf76"
}
Use this endpoint to transform an existing source clip with Runway’s video-to-video workflow. It starts an async task instead of returning the final output immediately.

​
Before you call it

  • Prepare a source video that matches the provider’s input requirements
  • Include the required X-Runway-Version header for the feature set you want
  • Start with one short prompt that describes the change, not a full storyboard

​
Output ratio

SettingSupported valuesDefault starting pointBoundary behavior
ratio1280:720, 720:1280, or another ratio accepted by the selected Runway model/version1280:720Match the source clip orientation where possible.
This endpoint expects colon-separated ratio values. Use 1280:720 for 1280x720 output and 720:1280 for 720x1280; 1280x720 is not accepted on every Runway video-to-video route.

​
Task flow

1

Submit the source clip and prompt

Start the task from this endpoint and save the returned task id.
2

Poll task details

Use Get a Runway task until the task reaches a terminal state.
3

Store the transformed result

Download or persist the finished asset through your normal media pipeline.

Authorizations

​
Authorization
string
header
required

Bearer token authentication. Use your CometAPI key.

Headers

​
X-Runway-Version
string
required

Runway API version header, for example 2024-11-06.

Body

application/json
​
videoUri
string
default:https://your-video-host/source.mp4
required

HTTPS URL of the source video, or a base64 data URI containing the video.

​
promptText
string
default:A cat yawning in slow motion.
required

Text prompt describing the desired output. Maximum 1000 characters.

​
seed
integer
default:1
required

Random seed for reproducible results. Range: 0–4294967295.

​
model
string
default:gen4_aleph
required

Model variant to use.

​
references
object[]
required

Optional reference images to guide generation. Each item must include type (e.g. image) and uri (HTTPS URL).

​
ratio
string
default:1280:720
required

Requested output frame shape. Use colon-separated values such as 1280:720 or 720:1280; read them as 1280x720 and 720x1280 targets. Do not assume every Runway video-to-video route accepts 1280x720 with an x separator.

​
contentModeration
object
required

Response

200 - application/json

success

​
id
string
required

The ID of the task that was created. Use this to retrieve the task later.