Skip to main content
POST
/
runwayml
/
v1
/
text_to_image
cURL
curl https://api.cometapi.com/runwayml/v1/text_to_image \
  -H "Authorization: Bearer $COMETAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "promptText": "A paper boat floating on calm water at sunrise.",
      "ratio": "1280:720",
      "model": "gen4_image",
      "referenceImages": [
        {
          "uri": "https://your-image-host/reference.jpg",
          "tag": "ref"
        }
      ]
    }'
{
  "id": "31f9c5b2-ea5c-421c-8044-75a6bb53211d"
}
Use this endpoint to create a Runway image-generation task.

​
Usage notes

  • Send the required X-Runway-Version header, for example 2024-11-06
  • Use model: gen4_image
  • This route requires at least one referenceImages item — a text-only request returns reference_images_empty

​
Task flow

1

Submit the generation request

Send promptText, ratio, model, and at least one referenceImages object.
2

Store the returned id

Keep the returned id, because this route is asynchronous.
3

Poll the task

Use Get a Runway task. If an immediate poll returns task_not_exist, wait a few seconds and retry.

Authorizations

​
Authorization
string
header
required

Bearer token authentication. Use your CometAPI key.

Headers

​
X-Runway-Version
string
required

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

Body

application/json
​
promptText
string
default:A paper boat floating on calm water at sunrise.
required

A non-empty string up to 1000 characters.

​
ratio
string
default:1280:720
required

Aspect ratio of the output image, e.g. 1280:720.

​
seed
integer
default:1
required

Random seed for reproducible results.

​
model
string
default:gen4_image
required

The model variant to use.

​
referenceImages
object[]
required

An array of up to three images to be used as references. At least one item is required. referenceImages is required.

​
contentModeration
object
required

Response

200 - application/json

Task accepted.

​
id
string
required