---
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.
    - `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` '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
    - `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.
      - unknown[]
        - unknown
    - `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.
    - `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
    - `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. 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. 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. 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
    - `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 15000 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' | '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.
    - `referenceAudio` object[] — An optional array of audio references. The total combined duration must not exceed 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
  - object
    - `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` '480p' | '720p' | '1080p' — The output resolution. Output aspect ratio follows the input image.
    - `promptText` string — An optional text prompt describing motion or changes in the output video.
    - `duration` integer — The number of seconds of duration for the output video.
    - `model` 'grok_imagine_1_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)