Create a Runway image-to-video task

POST

runwayml

image_to_video

curl "https://api.cometapi.com/runwayml/v1/image_to_video" \
  --request POST \
  --header "Authorization: Bearer $COMETAPI_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "gen4.5",
  "promptImage": "https://upload.wikimedia.org/wikipedia/commons/3/3a/Cat03.jpg",
  "promptText": "The cat turns toward the camera.",
  "ratio": "1280:720",
  "duration": 5
}'

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

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

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

Use this endpoint to animate a source image. Send your CometAPI API key with Bearer authentication and a JSON request body.

Choose a model

Model	Required fields	Motion prompt
`gen4.5`	`model`, `promptImage`, `promptText`, `ratio`, `duration`	Describe the motion in `promptText`.
`gen4_turbo`	`model`, `promptImage`, `ratio`	Optionally describe the motion in `promptText`, using 1 to 1,000 UTF-16 code units.

For a text-only request, use Create a Runway text-to-video task.

Provide the first frame

Set promptImage to an accessible HTTPS image URL or a Base64 image data URI. You can also supply a one-item array containing uri and position: "first". This interface accepts one starting frame; do not add a last-frame entry. HTTPS images must be directly accessible without redirects and have valid image content headers. Encoded image data URIs can be up to 5 MB. See the Runway media input requirements for image formats and dimensions.

Set duration and dimensions

Use a whole-number duration from 2 through 10 seconds. It is required for gen4.5 and optional for gen4_turbo. Set ratio to 1280:720, 720:1280, 1104:832, 960:960, 832:1104, or 1584:672. These are colon-separated width and height values. 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.

Choose an output format

gen4.5 accepts outputFormat for MP4, ProRes, PNG sequences, and the HDR formats listed in the request schema. Omit the field for H.264 MP4. proresProfile applies only to prores and hdr_prores; its allowed values depend on the selected format. Omit both fields with gen4_turbo.

Retrieve the result

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

Authorizations

Authorization

string

header

required

Use your CometAPI API key.

Body

application/json

gen4.5
gen4_turbo

Request parameters for gen4.5.

model

enum<string>

required

Model ID for this request variant.

Available options:

gen4.5

Allowed value: "gen4.5"

promptText

string

required

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

Required string length: 1 - 1000

promptImage

required

Image to use as the first frame. Supply a media URI or a one-item array with position set to first.

Maximum string length: 2048

Pattern: ^https://

ratio

enum<string>

required

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

Available options:

1280:720,

720:1280,

1104:832,

960:960,

832:1104,

1584:672

duration

integer

required

Requested video duration in whole seconds, from 2 through 10.

Required range: 2 <= x <= 10

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

contentModeration

object

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

Show child attributes

outputFormat

enum<string>

Output encoding. Omit for mp4 (H.264). prores returns MOV; png_sequence returns a PNG ZIP; sdr_rec709_10bit returns 10-bit Rec.709 HEVC. hdr10 and hlg return 10-bit HDR MP4; hdr_pq_12bit_master returns 12-bit HEVC MOV; hdr_prores returns HDR ProRes MOV. The HDR PNG/EXR sequence formats return ZIP archives; the ACEScg variants target the named ACES version.

Available options:

mp4,

prores,

png_sequence,

hdr10,

hlg,

sdr_rec709_10bit,

hdr_pq_12bit_master,

hdr_prores,

hdr_png_sequence,

hdr_exr_sequence,

hdr_exr_acescg_sequence_1_3,

hdr_exr_acescg_sequence_2_0

proresProfile

enum<string>

Profile for outputFormat prores or hdr_prores. Omit for 4444 with prores, or 422 HQ with hdr_prores. hdr_prores accepts only 422, 422 HQ, or 4444. Omit this field for other formats.

Available options:

422,

4444,

422 Proxy,

422 LT,

422 HQ,

4444 XQ

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 22, 2026

curl "https://api.cometapi.com/runwayml/v1/image_to_video" \
  --request POST \
  --header "Authorization: Bearer $COMETAPI_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "model": "gen4.5",
  "promptImage": "https://upload.wikimedia.org/wikipedia/commons/3/3a/Cat03.jpg",
  "promptText": "The cat turns toward the camera.",
  "ratio": "1280:720",
  "duration": 5
}'

{
  "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

Provide the first frame

Set duration and dimensions

Choose an output format

Retrieve the result

Authorizations

Body

Response

​Choose a model

​Provide the first frame

​Set duration and dimensions

​Choose an output format

​Retrieve the result

Authorizations

Body

Response

Choose a model

Provide the first frame

Set duration and dimensions

Choose an output format

Retrieve the result