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

# Text/Image to Image

`POST /v1/text_to_image`

This endpoint will start a new task to generate images from text and/or image(s)

## 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.
    - `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` '1024:1024' | '1080:1080' | '1168:880' | '1360:768' | '1440:1080' | '1080:1440' | '1808:768' | '1920:1080' | '1080:1920' | '2112:912' | '1280:720' | '720:1280' | '720:720' | '960:720' | '720:960' | '1680:720', required — The resolution of the output image.
    - `referenceImages` object[], required — An array of one to three images to be used as references for the generated image output.
      - `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.
      - `tag` string — A tag to identify the reference image. This is used to reference the image in prompt text. Must be 3-16 characters, start with a letter, and use only letters, digits, and underscores (no hyphens or other punctuation).
    - `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_image_turbo', required
  - 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.
    - `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` '1024:1024' | '1080:1080' | '1168:880' | '1360:768' | '1440:1080' | '1080:1440' | '1808:768' | '1920:1080' | '1080:1920' | '2112:912' | '1280:720' | '720:1280' | '720:720' | '960:720' | '720:960' | '1680:720', required — The resolution of the output image.
    - `referenceImages` object[] — An array of up to three images to be used as references for the generated image output.
      - `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.
      - `tag` string — A tag to identify the reference image. This is used to reference the image in prompt text. Must be 3-16 characters, start with a letter, and use only letters, digits, and underscores (no hyphens or other punctuation).
    - `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_image', required
  - object
    - `promptText` string, required — A non-empty string up to 32,000 characters describing the desired image.
    - `ratio` '2048:880' | '1920:1088' | '1920:1280' | '1920:1440' | '1920:1536' | '1920:1920' | '1536:1920' | '1440:1920' | '1280:1920' | '1088:1920' | '2912:1248' | '2560:1440' | '2560:1712' | '2560:1920' | '2560:2048' | '2560:2560' | '2048:2560' | '1920:2560' | '1712:2560' | '1440:2560' | '3840:1648' | '3840:2160' | '3504:2336' | '3264:2448' | '3200:2560' | '2880:2880' | '2560:3200' | '2448:3264' | '2336:3504' | '2160:3840' | 'auto', required — The resolution of the output image, expressed as `<width>:<height>`. Use `auto` to let the model choose.
    - `quality` 'low' | 'medium' | 'high' | 'auto' — Rendering quality. Higher qualities consume more credits. Defaults to `high`.
    - `background` 'opaque' | 'auto' — Background treatment. Defaults to `auto`, which lets the model pick. `transparent` is not supported by this model.
    - `referenceImages` object[] — An array of up to 16 images to be used as references for the generated image output.
      - `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.
      - `tag` string — A tag to identify the reference image. This may be used to reference the image in prompt text. Must be 3-16 characters, start with a letter, and use only letters, digits, and underscores (no hyphens or other punctuation).
    - `outputCount` integer — The number of images to generate (1-10). Increasing this number will affect the number of credits consumed by the generation.
    - `model` 'gpt_image_2', required
  - object
    - `promptText` string, required — This should describe in detail what should appear in the output.
    - `ratio` '1344:768' | '768:1344' | '1024:1024' | '1184:864' | '864:1184' | '1536:672' | '832:1248' | '1248:832' | '896:1152' | '1152:896' | '2048:2048' | '1696:2528' | '2528:1696' | '1792:2400' | '2400:1792' | '1856:2304' | '2304:1856' | '1536:2752' | '2752:1536' | '3168:1344' | '4096:4096' | '3392:5056' | '5056:3392' | '3584:4800' | '4800:3584' | '3712:4608' | '4608:3712' | '3072:5504' | '5504:3072' | '6336:2688', required — The resolution of the output image.
    - `referenceImages` object[] — An array of up to 14 images to be used as references for the generated image output. Up to five of those images can pass `subject: "human"` to maintain character consistency, and up to nine of those images can pass `subject: "object"` with high-fidelity images of objects to include in the output.
      - `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.
      - `tag` string — A tag to identify the reference image. This is used to reference the image in prompt text. Must be 3-16 characters, start with a letter, and use only letters, digits, and underscores (no hyphens or other punctuation).
      - `subject` 'object' | 'human' — Whether this is a reference of a human subject (for character consistency) or an object that appears in the output.
    - `outputCount` 1 | 4 — The number of images to generate. Increasing this number will affect the number of credits consumed by the generation. Up to four images can be generated at once.
    - `model` 'gemini_image3_pro', required
  - object
    - `promptText` string, required — This should describe in detail what should appear in the output.
    - `ratio` '512:512' | '416:624' | '624:416' | '432:592' | '592:432' | '448:576' | '576:448' | '384:672' | '672:384' | '768:336' | '256:1024' | '1024:256' | '176:1408' | '1408:176' | '1024:1024' | '832:1248' | '1248:832' | '864:1184' | '1184:864' | '896:1152' | '1152:896' | '768:1344' | '1344:768' | '1536:672' | '512:2048' | '2048:512' | '352:2816' | '2816:352' | '2048:2048' | '1696:2528' | '2528:1696' | '1792:2400' | '2400:1792' | '1856:2304' | '2304:1856' | '1536:2752' | '2752:1536' | '3168:1344' | '1024:4096' | '4096:1024' | '704:5632' | '5632:704' | '4096:4096' | '3392:5056' | '5056:3392' | '3584:4800' | '4800:3584' | '3712:4608' | '4608:3712' | '3072:5504' | '5504:3072' | '6336:2688' | '2048:8192' | '8192:2048' | '1408:11264' | '11264:1408', required — The resolution of the output image.
    - `referenceImages` object[] — An array of up to 14 images to be used as references for the generated image output. Up to five of those images can pass `subject: "human"` to maintain character consistency, and up to nine of those images can pass `subject: "object"` with high-fidelity images of objects to include in the output.
      - `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.
      - `tag` string — A tag to identify the reference image. This is used to reference the image in prompt text. Must be 3-16 characters, start with a letter, and use only letters, digits, and underscores (no hyphens or other punctuation).
      - `subject` 'object' | 'human' — Whether this is a reference of a human subject (for character consistency) or an object that appears in the output.
    - `outputCount` 1 | 4 — The number of images to generate. Increasing this number will affect the number of credits consumed by the generation. Up to four images can be generated at once.
    - `model` 'gemini_image3.1_flash', required
  - object
    - `promptText` string, required — A non-empty string up to 4,000 characters describing the desired image.
    - `ratio` '1024:1024' | '1184:896' | '896:1184' | '1376:768' | '768:1376' | '1296:864' | '864:1296' | '2048:2048' | '2304:1728' | '1728:2304' | '2720:1530' | '1530:2720' | '2496:1664' | '1664:2496' | 'auto_1k' | 'auto_2k', required — The resolution of the output image, expressed as `<width>:<height>`. Use `auto_1k` or `auto_2k` to let the model pick aspect ratio at a fixed resolution tier.
    - `outputFormat` 'png' | 'jpeg' — The file format of the output image. Defaults to png.
    - `referenceImages` object[] — An array of reference images for multi-image fusion and interactive editing. Reference by upload order in prompt text (Figure 1, Figure 2, etc.).
      - `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.
    - `outputCount` integer — The number of images to generate. Increasing this number will affect the number of credits consumed by the generation.
    - `grounding` boolean — When true, enable live web search so the model can use current brand, trend, or event context. Default false for deterministic output.
    - `model` 'seedream5_pro', required
  - object
    - `promptText` string, required — A non-empty string up to 4,000 characters describing the desired image.
    - `ratio` '2048:2048' | '2304:1728' | '1728:2304' | '2848:1600' | '1600:2848' | '2496:1664' | '1664:2496' | '3136:1344' | '3072:3072' | '3456:2592' | '2592:3456' | '4096:2304' | '2304:4096' | '3744:2496' | '2496:3744' | '4704:2016', required — The resolution of the output image, expressed as `<width>:<height>`.
    - `outputFormat` 'png' | 'jpeg' — The file format of the output image. Defaults to png.
    - `referenceImages` object[] — An array of reference images for multi-image fusion and interactive editing. Reference by upload order in prompt text (Figure 1, Figure 2, etc.).
      - `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.
    - `outputCount` integer — The number of images to generate. Increasing this number will affect the number of credits consumed by the generation.
    - `grounding` boolean — When true, enable live web search so the model can use current brand, trend, or event context. Default false for deterministic output.
    - `model` 'seedream5_lite', required
  - object
    - `promptText` string, required — A non-empty text prompt describing what should appear in the output image.
    - `ratio` '1024:1024' | '1280:720' | '720:1280' | '1152:864' | '864:1152' | '1248:832' | '832:1248' | '1248:576' | '576:1248' | '1280:576' | '576:1280' | '1408:704' | '704:1408' | '2048:2048' | '2816:1584' | '1584:2816' | '2368:1776' | '1776:2368' | '2496:1664' | '1664:2496' | '2912:1344' | '1344:2912' | '3200:1440' | '1440:3200' | '2912:1456' | '1456:2912' | 'auto_1k' | 'auto_2k', required — The resolution of the output image, expressed as `<width>:<height>`. 2K ratios cost 2 additional credits per image. Use `auto_1k` or `auto_2k` to pick a resolution tier and let the model choose the framing from the prompt.
    - `quality` 'low' | 'medium' — How much rendering effort the model spends on the output. Defaults to `medium`; `low` is faster and costs 2 fewer credits per image.
    - `edit` boolean — When true with exactly one reference image, edit that image directly instead of using it as a loose visual reference. With several reference images the prompt describes how they should be edited or combined. Requires at least one reference image.
    - `referenceImages` object[] — Up to 3 images to guide the generation. Reference them from `promptText` to describe how each should be used. Each adds 1 credit to the generation.
      - `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.
    - `outputCount` integer — The number of images to generate. Increasing this number will affect the number of credits consumed by the generation.
    - `model` 'grok_imagine_image_2', required
  - object
    - `promptText` string, required — This should describe in detail what should appear in the output.
    - `ratio` '1344:768' | '768:1344' | '1024:1024' | '1184:864' | '864:1184' | '1536:672' | '832:1248' | '1248:832' | '896:1152' | '1152:896', required — The resolution of the output image.
    - `referenceImages` object[] — An array of up to three images to be used as references for the generated image output.
      - `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.
      - `tag` string — A tag to identify the reference image. This is used to reference the image in prompt text. Must be 3-16 characters, start with a letter, and use only letters, digits, and underscores (no hyphens or other punctuation).
    - `model` 'gemini_2.5_flash', 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)