Create a Runway image

POST

runwayml

text_to_image

curl "https://api.cometapi.com/runwayml/v1/text_to_image" \
  --request POST \
  --header "Authorization: Bearer $COMETAPI_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "gen4_image",
  "promptText": "A watercolor portrait of @cat_ref.",
  "ratio": "1024:1024",
  "referenceImages": [
    {
      "uri": "https://upload.wikimedia.org/wikipedia/commons/3/3a/Cat03.jpg",
      "tag": "cat_ref"
    }
  ]
}'

{
  "id": "00000000-0000-4000-8000-000000000001"
}

{
  "code": "<string>",
  "message": "<string>",
  "data": "<unknown>"
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>"
  }
}

Use this endpoint to generate an image from a prompt, with optional reference images for gen4_image. Send your CometAPI API key with Bearer authentication and a JSON request body.

Choose a model and references

Every request requires model, promptText, and ratio.

Model	`referenceImages`
`gen4_image`	Optional. Omit it or use `[]` for text-only generation, or supply up to three images.
`gen4_image_turbo`	Supply one to three images.

For gen4_image_turbo, referenceImages is required and must contain one to three images. Each reference object contains an image uri and an optional tag. Use a tag of 3 to 16 lowercase letters, digits, or underscores, starting with a letter. Reference it in promptText as @tag, such as @cat_ref. Image URIs accept accessible HTTPS URLs or Base64 image data URIs of up to 5 MB. The prompt accepts 1 to 1,000 UTF-16 code units.

Choose dimensions

Set ratio to one of the exact dimension pairs in the schema. For example, 1024:1024 requests a square image, 1280:720 a landscape image, and 720:1280 a portrait image. Use ratio to select dimensions; do not send resolution or size with these models. For an explicit sampling seed, use 1 through 4294967295. Omission or 0 selects a random seed. If you include contentModeration, set its publicFigureThreshold to auto or low; otherwise omit the object.

Retrieve the result

Save the returned id and use Get a Runway task. When status is SUCCEEDED, read the generated image URLs in output.

Authorizations

Authorization

string

header

required

Use your CometAPI API key.

Body

application/json

gen4_image
gen4_image_turbo

Request parameters for gen4_image.

model

enum<string>

required

Model ID for this request variant.

Available options:

gen4_image

Allowed value: "gen4_image"

promptText

string

required

Describe the requested scene or motion in 1 to 1,000 UTF-16 code units.

Required string length: 1 - 1000

ratio

enum<string>

required

Requested output dimensions, expressed as width:height. Choose a value listed for this model and endpoint.

Available options:

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

seed

integer

Optional sampling seed. Use a positive integer for an explicit seed. Omission or 0 selects a random seed.

Required range: 0 <= x <= 4294967295

referenceImages

object[]

Optional array of up to three reference images. Omit it or use an empty array for text-only generation.

Maximum array length: 3

Show child attributes

contentModeration

object

Optional content moderation settings. Omit the object to use standard moderation.

Show child attributes

Response

Task submitted. Save its id to retrieve task status.

string

required

Task ID for GET /runwayml/v1/tasks/{id}.

status

string

Task state, when returned.

createdAt

string<date-time>

Task submission timestamp, when returned.

output

string<uri>[]

Result URLs, when returned.

failure

string

Failure explanation, when returned.

failureCode

string

Machine-readable failure code, when returned.

estimatedCost

object

Task estimate metadata, when returned.

Show child attributes

cost

object

Task cost metadata, when returned.

Show child attributes

Last modified on September 18, 2026

curl "https://api.cometapi.com/runwayml/v1/text_to_image" \
  --request POST \
  --header "Authorization: Bearer $COMETAPI_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "gen4_image",
  "promptText": "A watercolor portrait of @cat_ref.",
  "ratio": "1024:1024",
  "referenceImages": [
    {
      "uri": "https://upload.wikimedia.org/wikipedia/commons/3/3a/Cat03.jpg",
      "tag": "cat_ref"
    }
  ]
}'

{
  "id": "00000000-0000-4000-8000-000000000001"
}

{
  "code": "<string>",
  "message": "<string>",
  "data": "<unknown>"
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "code": "<string>"
  }
}

Content moderation

API keys

Choose a model and references

Choose dimensions

Retrieve the result

Authorizations

Body

Response

​Choose a model and references

​Choose dimensions

​Retrieve the result

Authorizations

Body

Response

Choose a model and references

Choose dimensions

Retrieve the result