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

# Image to video

`POST /v1/image_to_video`

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

## Headers

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

## Request body

- union
  - object
    - `promptText` string, required — A non-empty string up to 1000 characters (measured in UTF-16 code units). This should describe in detail what should appear in the output.
    - `promptImage` union, required
      - 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.
      - object[] — An array of objects representing images to be used in the output video. Only a `first` frame is supported.
        - `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.
        - `position` 'first', required — The position of the image in the output video. "first" will use the image as the first frame of the video.
    - `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` '1280:720' | '720:1280' | '1104:832' | '960:960' | '832:1104' | '1584:672', required — The resolution of the output video.
    - `duration` integer, required — The number of seconds of duration for the output video. Must be an integer from 2 to 10.
    - `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.
    - `model` 'gen4.5', required
  - object
    - `promptText` string — A non-empty string up to 1000 characters (measured in UTF-16 code units). This should describe in detail what should appear in the output.
    - `promptImage` union, required
      - 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.
      - object[] — An array of objects representing images to be used in the output video. Only a `first` frame is supported.
        - `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.
        - `position` 'first', required — The position of the image in the output video. "first" will use the image as the first frame of the video.
    - `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` '1280:720' | '720:1280' | '1104:832' | '832:1104' | '960:960' | '1584:672', required — The resolution of the output video.
    - `duration` integer — The number of seconds of duration for the output video.
    - `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.
    - `model` 'gen4_turbo', required
  - object
    - `promptText` string — A non-empty string up to 1000 characters (measured in UTF-16 code units). This should describe in detail what should appear in the output.
    - `promptImage` union, required — You may specify an image to use as the first frame of the output video, or an array with a first frame and optionally a last frame. This model does not support generating with only a last frame.
      - 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.
      - object[] — An array of objects representing images to be used in the output video. No two provided images may have the same `position` value.
        - `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.
        - `position` 'first' | 'last', required — The position of the image in the output video. "first" will use the image as the first frame of the video, "last" will use the image as the last frame of the video.
    - `ratio` '1280:720' | '720:1280' | '1080:1920' | '1920:1080', required — The resolution of the output video.
    - `audio` boolean — Whether to generate audio for the video. Audio inclusion affects pricing.
    - `negativePrompt` string — Text describing what should not appear in the output video.
    - `duration` 4 | 6 | 8 — The number of seconds of duration for the output video.
    - `model` 'veo3.1', required
  - object
    - `promptText` string — A non-empty string up to 1000 characters (measured in UTF-16 code units). This should describe in detail what should appear in the output.
    - `promptImage` union, required — You may specify an image to use as the first frame of the output video, or an array with a first frame and optionally a last frame. This model does not support generating with only a last frame.
      - 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.
      - object[] — An array of objects representing images to be used in the output video. No two provided images may have the same `position` value.
        - `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.
        - `position` 'first' | 'last', required — The position of the image in the output video. "first" will use the image as the first frame of the video, "last" will use the image as the last frame of the video.
    - `ratio` '1280:720' | '720:1280' | '1080:1920' | '1920:1080', required — The resolution of the output video.
    - `audio` boolean — Whether to generate audio for the video. Audio inclusion affects pricing.
    - `negativePrompt` string — Text describing what should not appear in the output video.
    - `duration` 4 | 6 | 8 — The number of seconds of duration for the output video.
    - `model` 'veo3.1_fast', required
  - object
    - `promptText` string — A string up to 2500 characters (measured in UTF-16 code units) describing motion or changes in the output video.
    - `promptImage` union, required
      - 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.
      - object[] — An array of objects representing images to be used in the output video. Only a `first` frame is supported.
        - `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.
        - `position` 'first', required — The position of the image in the output video. "first" will use the image as the first frame of the video.
    - `resolution` '720P' | '1080P' — Output quality tier. Output aspect ratio follows the input image.
    - `duration` integer — The number of seconds of duration for the output video.
    - `model` 'happyhorse_1_0', required
  - object
    - `promptImage` union, required — An image or array of images. Use position `first`/`last` for keyframe mode, or omit position for reference images. The two modes cannot be mixed.
      - 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.
      - object[] — An array of image objects. Use position "first"/"last" for keyframe mode, or omit position for reference images. The two modes cannot be mixed.
        - `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.
        - `position` 'first' | 'last' — The position of the image in the output video. "first" will use the image as the first frame, "last" as the last frame. Omit for a reference image.
    - `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.
    - `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` 'seedance2', required
  - object
    - `promptImage` union, required — An image or array of images. Use position `first`/`last` for keyframe mode, or omit position for reference images. The two modes cannot be mixed.
      - 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.
      - object[] — An array of image objects. Use position "first"/"last" for keyframe mode, or omit position for reference images. The two modes cannot be mixed.
        - `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.
        - `position` 'first' | 'last' — The position of the image in the output video. "first" will use the image as the first frame, "last" as the last frame. Omit for a reference image.
    - `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.
    - `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` 'seedance2_fast', required
  - object
    - `promptImage` union, required — An image or array of images. Use position `first`/`last` for keyframe mode, or omit position for reference images. The two modes cannot be mixed.
      - 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.
      - object[] — An array of image objects. Use position "first"/"last" for keyframe mode, or omit position for reference images. The two modes cannot be mixed.
        - `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.
        - `position` 'first' | 'last' — The position of the image in the output video. "first" will use the image as the first frame, "last" as the last frame. Omit for a reference image.
    - `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.
    - `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` 'seedance2_mini', required
  - object
    - `promptImage` union, required — An image to use as the first frame of the output video. Gemini Omni Flash only supports a first frame.
      - 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.
      - object[] — An array of objects representing images to be used in the output video. Only a `first` frame is supported.
        - `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.
        - `position` 'first', required — The position of the image in the output video. "first" will use the image as the first frame of the video.
    - `promptText` string — An optional text prompt describing how the video should evolve from the first frame.
    - `ratio` '1280:720' | '720:1280' — The aspect ratio of the output video: `1280:720` (landscape) or `720:1280` (portrait).
    - `duration` integer — The duration of the output video in seconds, as a whole number from 3 to 10.
    - `model` 'gemini_omni_flash', required
  - object
    - `promptText` string — A non-empty string up to 1000 characters (measured in UTF-16 code units). This should describe in detail what should appear in the output.
    - `promptImage` union, required
      - 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.
      - object[] — An array of objects representing images to be used in the output video. Only a `first` frame is supported.
        - `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.
        - `position` 'first', required — The position of the image in the output video. "first" will use the image as the first frame of the video.
    - `duration` 8, required — The number of seconds of duration for the output video.
    - `ratio` '1280:720' | '720:1280' | '1080:1920' | '1920:1080', required — The resolution of the output video.
    - `negativePrompt` string — Text describing what should not appear in the output video.
    - `model` 'veo3', 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.

## Other responses

- `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/e7d9a59ac7b0/schema)