---
title: "Video to video"
method: POST
path: "/v1/video_to_video"
tags: ["Start generating"]
---

# Video to video

`POST /v1/video_to_video`

This endpoint will start a new task to generate a video from a video.

## Headers

- `X-Runway-Version` '2024-11-06', required

## Request body

- union
  - object
    - `promptText` string — A non-empty and optional string describing what should appear in the output.
    - `keyframes` union[] — Timed guidance images placed at specific points in the input video. Up to 5 keyframes.
      - union
        - object
          - `uri` union, required — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.
            - string — A HTTPS URL, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.
            - string — A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.
            - string — A data URI containing encoded media.
          - `seconds` number, required — Absolute timestamp in seconds from the start of the input video when this guidance image should apply.
          - `range` object — Optional edit window. When set, the edit applies only to this time range and the keyframe timestamp must fall within it. All keyframes must either set a range or none may.
            - `start_seconds` integer, required — Start of the edit window in whole seconds from the start of the input video.
            - `end_seconds` integer, required — End of the edit window (exclusive) in whole seconds from the start of the input video.
        - object
          - `uri` union, required — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.
            - string — A HTTPS URL, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.
            - string — A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.
            - string — A data URI containing encoded media.
          - `at` number, required — Position as a fraction [0.0, 1.0] of the input video duration when this guidance image should apply.
          - `range` object — Optional edit window. When set, the edit applies only to this time range and the keyframe timestamp must fall within it. All keyframes must either set a range or none may.
            - `start_seconds` integer, required — Start of the edit window in whole seconds from the start of the input video.
            - `end_seconds` integer, required — End of the edit window (exclusive) in whole seconds from the start of the input video.
    - `videoUri` union, required — The input video to edit. Must be 30 seconds or shorter.
      - string — A HTTPS URL, Runway upload URI, or base64 data URI (e.g. `data:video/mp4;base64,...`, up to 16MB) containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information.
      - string — A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.
      - string — A data URI containing encoded media.
    - `seed` integer — If unspecified, a random number is chosen. Varying the seed integer is a way to get different results for the same other request parameters. Using the same seed integer for an identical request will produce similar results.
    - `ratio` string
    - `targetAspectRatio` '16:9' | '4:3' | '3:2' | '1:1' | '2:3' | '3:4' | '9:16' | '21:9' — Target aspect ratio for expand/outpaint. Letterboxes the input video and keyframes before generation.
    - `contentModeration` object — Settings that affect the behavior of the content moderation system.
      - `publicFigureThreshold` 'auto' | 'low' — When set to `low`, the content moderation system will be less strict about preventing generations that include recognizable public figures.
    - `outputFormat` 'mp4' | 'prores' | 'png_sequence' — The container/encoding of the output. `mp4` (default) returns an H.264 .mp4. `prores` returns a ProRes .mov. `png_sequence` returns a .zip of PNG frames (plus a separate .wav artifact when the output has audio). Non-mp4 formats incur an additional surcharge of 5 credits per second of output.
    - `proresProfile` '422' | '4444' | '422 Proxy' | '422 LT' | '422 HQ' | '4444 XQ' — The ProRes profile to use. Only valid when `outputFormat` is `prores`. Defaults to `4444`.
    - `model` 'aleph2', required
  - object
    - `promptVideo` union, required — The input video to use as a reference for the output video. If additional video references are provided, the combined duration across all video references must not exceed 15 seconds.
      - string — A HTTPS URL, Runway upload URI, or base64 data URI (e.g. `data:video/mp4;base64,...`, up to 16MB) containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information.
      - string — A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.
      - string — A data URI containing encoded media.
    - `promptText` string, required — A non-empty text prompt describing what should appear in the output.
    - `resolution` '2K' | '768P' — The output resolution. Hailuo 3.0 supports 768P and 2K.
    - `duration` integer — The number of seconds of duration for the output video.
    - `ratio` 'adaptive' | '21:9' | '16:9' | '4:3' | '1:1' | '3:4' | '9:16' — The aspect ratio of the output video. Use adaptive only when image or video references are provided; text-only requests require a concrete ratio.
    - `references` object[] — An optional array of image references (up to 9). See [our docs](/assets/inputs#images) on image inputs for more information.
      - `uri` union, required — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.
        - string — A HTTPS URL, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.
        - string — A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.
        - string — A data URI containing encoded media.
    - `referenceVideos` object[] — An optional array of video references. The combined duration across all video references must not exceed 15 seconds. See [our docs](/assets/inputs#videos) on video inputs for more information.
      - `type` 'video', required
      - `uri` union, required — A HTTPS URL, Runway or data URI containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information.
        - string — A HTTPS URL, Runway upload URI, or base64 data URI (e.g. `data:video/mp4;base64,...`, up to 16MB) containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information.
        - string — A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.
        - string — A data URI containing encoded media.
    - `referenceAudio` object[] — An optional array of audio references. Audio references require a text prompt, and the total combined duration must not exceed 15 seconds.
      - `type` 'audio', required
      - `uri` union, required — A HTTPS URL, Runway or data URI containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information.
        - string — A HTTPS URL, Runway upload URI, or base64 data URI (e.g. `data:audio/mp3;base64,...`, up to 16MB) containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information.
        - string — A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.
        - string — A data URI containing encoded media.
    - `model` 'hailuo3', required
  - object
    - `promptVideo` union, required — The input video to use as a reference for the output video. If additional video references are provided, the combined duration across all video references must not exceed 15 seconds.
      - string — A HTTPS URL, Runway upload URI, or base64 data URI (e.g. `data:video/mp4;base64,...`, up to 16MB) containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information.
      - string — A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.
      - string — A data URI containing encoded media.
    - `promptText` string — An optional text prompt up to 3500 characters describing what should appear in the output.
    - `audio` boolean — Whether to generate audio for the video.
    - `duration` integer — The number of seconds of duration for the output video.
    - `ratio` '992:432' | '864:496' | '752:560' | '640:640' | '560:752' | '496:864' | '1470:630' | '1280:720' | '1112:834' | '960:960' | '834:1112' | '720:1280' | '2206:946' | '1920:1080' | '1664:1248' | '1440:1440' | '1248:1664' | '1080:1920' | '3840:1646' | '3840:2160' | '3840:2880' | '3840:3840' | '2880:3840' | '2160:3840' — The resolution of the output video.
    - `references` object[] — An optional array of image references (up to 9). See [our docs](/assets/inputs#images) on image inputs for more information.
      - `uri` union, required — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.
        - string — A HTTPS URL, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.
        - string — A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.
        - string — A data URI containing encoded media.
    - `referenceVideos` object[] — An optional array of video references. The combined duration across all video references must not exceed 15 seconds. See [our docs](/assets/inputs#videos) on video inputs for more information.
      - `type` 'video', required
      - `uri` union, required — A HTTPS URL, Runway or data URI containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information.
        - string — A HTTPS URL, Runway upload URI, or base64 data URI (e.g. `data:video/mp4;base64,...`, up to 16MB) containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information.
        - string — A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.
        - string — A data URI containing encoded media.
    - `referenceAudio` object[] — An optional array of audio references. The total combined duration must not exceed 15 seconds.
      - `type` 'audio', required
      - `uri` union, required — A HTTPS URL, Runway or data URI containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information.
        - string — A HTTPS URL, Runway upload URI, or base64 data URI (e.g. `data:audio/mp3;base64,...`, up to 16MB) containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information.
        - string — A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.
        - string — A data URI containing encoded media.
    - `model` 'seedance2', required
  - object
    - `promptVideo` union, required — The input video to use as a reference for the output video. If additional video references are provided, the combined duration across all video references must not exceed 15 seconds.
      - string — A HTTPS URL, Runway upload URI, or base64 data URI (e.g. `data:video/mp4;base64,...`, up to 16MB) containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information.
      - string — A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.
      - string — A data URI containing encoded media.
    - `promptText` string — An optional text prompt up to 3500 characters describing what should appear in the output.
    - `audio` boolean — Whether to generate audio for the video.
    - `duration` integer — The number of seconds of duration for the output video.
    - `ratio` '992:432' | '864:496' | '752:560' | '640:640' | '560:752' | '496:864' | '1470:630' | '1280:720' | '1112:834' | '960:960' | '834:1112' | '720:1280' — The resolution of the output video. Seedance 2.0 Fast supports 480p and 720p only.
    - `references` object[] — An optional array of image references (up to 9). See [our docs](/assets/inputs#images) on image inputs for more information.
      - `uri` union, required — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.
        - string — A HTTPS URL, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.
        - string — A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.
        - string — A data URI containing encoded media.
    - `referenceVideos` object[] — An optional array of video references. The combined duration across all video references must not exceed 15 seconds. See [our docs](/assets/inputs#videos) on video inputs for more information.
      - `type` 'video', required
      - `uri` union, required — A HTTPS URL, Runway or data URI containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information.
        - string — A HTTPS URL, Runway upload URI, or base64 data URI (e.g. `data:video/mp4;base64,...`, up to 16MB) containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information.
        - string — A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.
        - string — A data URI containing encoded media.
    - `referenceAudio` object[] — An optional array of audio references. The total combined duration must not exceed 15 seconds.
      - `type` 'audio', required
      - `uri` union, required — A HTTPS URL, Runway or data URI containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information.
        - string — A HTTPS URL, Runway upload URI, or base64 data URI (e.g. `data:audio/mp3;base64,...`, up to 16MB) containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information.
        - string — A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.
        - string — A data URI containing encoded media.
    - `model` 'seedance2_fast', required
  - object
    - `promptVideo` union, required — The input video to use as a reference for the output video. If additional video references are provided, the combined duration across all video references must not exceed 15 seconds.
      - string — A HTTPS URL, Runway upload URI, or base64 data URI (e.g. `data:video/mp4;base64,...`, up to 16MB) containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information.
      - string — A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.
      - string — A data URI containing encoded media.
    - `promptText` string — An optional text prompt up to 3500 characters describing what should appear in the output.
    - `audio` boolean — Whether to generate audio for the video.
    - `duration` integer — The number of seconds of duration for the output video.
    - `ratio` '992:432' | '864:496' | '752:560' | '640:640' | '560:752' | '496:864' | '1470:630' | '1280:720' | '1112:834' | '960:960' | '834:1112' | '720:1280' — The resolution of the output video. Seedance 2.0 Mini supports 480p and 720p only.
    - `references` object[] — An optional array of image references (up to 9). See [our docs](/assets/inputs#images) on image inputs for more information.
      - `uri` union, required — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.
        - string — A HTTPS URL, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.
        - string — A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.
        - string — A data URI containing encoded media.
    - `referenceVideos` object[] — An optional array of video references. The combined duration across all video references must not exceed 15 seconds. See [our docs](/assets/inputs#videos) on video inputs for more information.
      - `type` 'video', required
      - `uri` union, required — A HTTPS URL, Runway or data URI containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information.
        - string — A HTTPS URL, Runway upload URI, or base64 data URI (e.g. `data:video/mp4;base64,...`, up to 16MB) containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information.
        - string — A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.
        - string — A data URI containing encoded media.
    - `referenceAudio` object[] — An optional array of audio references. The total combined duration must not exceed 15 seconds.
      - `type` 'audio', required
      - `uri` union, required — A HTTPS URL, Runway or data URI containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information.
        - string — A HTTPS URL, Runway upload URI, or base64 data URI (e.g. `data:audio/mp3;base64,...`, up to 16MB) containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information.
        - string — A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.
        - string — A data URI containing encoded media.
    - `model` 'seedance2_mini', required
  - object
    - `videoUri` union, required — The input video to edit. The output is 720p, with the orientation (landscape or portrait) matched to the input. The output duration matches the input, up to 10 seconds. The input must be at most 10 seconds.
      - string — A HTTPS URL, Runway upload URI, or base64 data URI (e.g. `data:video/mp4;base64,...`, up to 16MB) containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information.
      - string — A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.
      - string — A data URI containing encoded media.
    - `promptText` string, required — A non-empty instruction describing the edit to apply.
    - `references` object[] — An optional array of image references to guide the edit.
      - `uri` union, required — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.
        - string — A HTTPS URL, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.
        - string — A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.
        - string — A data URI containing encoded media.
    - `model` 'gemini_omni_flash', required
  - object
    - `promptVideo` union, required — The input video to use as a reference for the output video. If additional video references are provided, the combined duration across all video references must not exceed 30 seconds.
      - string — A HTTPS URL, Runway upload URI, or base64 data URI (e.g. `data:video/mp4;base64,...`, up to 16MB) containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information.
      - string — A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.
      - string — A data URI containing encoded media.
    - `promptText` string — An optional text prompt up to 15000 characters describing what should appear in the output.
    - `audio` boolean — Whether to generate audio for the video.
    - `mode` 'reference' | 'extend' — How the input video is used. `reference` (the default) generates a new video conditioned on the input video and accepts `duration` and `ratio`. `extend` continues the input video, requires `promptText`, and matches the input aspect ratio, so `ratio` may not be provided.
    - `duration` integer — The number of seconds of duration for the output video. Defaults to 5.
    - `ratio` '992:432' | '854:480' | '752:560' | '640:640' | '560:752' | '480:854' | '1470:630' | '1280:720' | '1112:834' | '960:960' | '834:1112' | '720:1280' | '2206:946' | '1920:1080' | '1664:1248' | '1440:1440' | '1248:1664' | '1080:1920' — The resolution of the output video. Seedance 2.5 supports 480p, 720p, and 1080p.
    - `references` object[] — An optional array of image references (up to 30). See [our docs](/assets/inputs#images) on image inputs for more information.
      - `uri` union, required — A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.
        - string — A HTTPS URL, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.
        - string — A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.
        - string — A data URI containing encoded media.
    - `referenceVideos` object[] — An optional array of video references. The combined duration across all video references must not exceed 30 seconds. See [our docs](/assets/inputs#videos) on video inputs for more information.
      - `type` 'video', required
      - `uri` union, required — A HTTPS URL, Runway or data URI containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information.
        - string — A HTTPS URL, Runway upload URI, or base64 data URI (e.g. `data:video/mp4;base64,...`, up to 16MB) containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information.
        - string — A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.
        - string — A data URI containing encoded media.
    - `referenceAudio` object[] — An optional array of audio references. The total combined duration must be less than 30 seconds.
      - `type` 'audio', required
      - `uri` union, required — A HTTPS URL, Runway or data URI containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information.
        - string — A HTTPS URL, Runway upload URI, or base64 data URI (e.g. `data:audio/mp3;base64,...`, up to 16MB) containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information.
        - string — A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.
        - string — A data URI containing encoded media.
    - `model` 'seedance2_5', required

## Response `200`

The task that was created.

- object
  - `id` string, uuid, required — The ID of the task that was created. Use this to retrieve the task later.
  - `estimatedCost` object, required — The maximum credits this task may charge. The final amount may be lower after the task completes.
    - `credits` number, required — Estimated cost of the generation in credits.

## Other responses

- `400` — The request was rejected. Inspect `error` or `issues` (when present) and retry with a corrected request.
- `429` — You have exceeded the rate limit for this endpoint.

---

[API](https://skmtc.net/runwayml/apis/runwayml-api.md) · [All operations](https://skmtc.net/runwayml/apis/runwayml-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/runwayml/runwayml-api/revisions/3f3a4647d82f/schema)