POST gen4_5/create

Create a video using text prompt or image

December 15, 2025 (January 23, 2026)

Request Headers
Request Body
Responses
Model
Examples
Try It

Gen-4.5 supports two modes:

Text-to-Video (T2V): Generate 720p 16:9 videos from text prompts
Image-to-Video (I2V): Generate videos from a first image with optional text prompt, supporting multiple aspect ratios

Please be aware that Runway’s moderation system analyzes your image and text prompts and may fail task with moderation message if the prompt is determined to be offensive. Runway monitors the rate and the number of moderated tasks, which may result in your account being suspended when the internal threshold is exceeded.

The account you use to upload asset(s) via POST /assets will also be used to execute the generation. Uploading an asset to a specific account ensures that generation with that asset will occur under the same account.

https://api.useapi.net/v1/runwayml/gen4_5/create

Request Headers

Authorization: Bearer {API token}
Content-Type: application/json
# Alternatively you can use multipart/form-data
# Content-Type: multipart/form-data

API token is required, see Setup useapi.net for details.

Request Body

Text-to-Video (T2V)

{
    "email": "Optional Runway account email",
    "text_prompt": "Required text prompt for T2V",
    "seconds": 5,
    "seed": 12345678,
    "exploreMode": true,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 5
}

Image-to-Video (I2V)

{
    "firstImage_assetId": "Required assetId of first image asset",
    "text_prompt": "Optional text prompt",
    "aspect_ratio": "9:16",
    "seconds": 5,
    "seed": 12345678,
    "exploreMode": true,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 5
}

email is optional. If not specified, the API will randomly select an available account with capacity for load balancing. Use GET /accounts to see the list of linked Runway accounts. Not used when firstImage_assetId is provided (account is determined by the asset).
firstImage_assetId is optional. When provided, enables Image-to-Video mode. Specify the image assetId you want to be present in the first frame. Use GET /assets/?mediaType=image to see the list of image assets. To upload a new image asset use POST /assets.
text_prompt is required for T2V, optional for I2V. Describe your video scene. Maximum length: 5000 characters.
aspect_ratio is optional, I2V only. Ignored for T2V which is always 16:9. Supported values: 16:9 (default), 9:16, 1:1, 4:3, 3:4, 21:9.
seconds is optional. Specify desired length of the video in seconds. Supported values: 5 (default), 8, 10.
seed is optional. Valid range 1…4294967294.
exploreMode is optional. Set to true if you have a Runway Unlimited plan and wish to execute relaxed generation. You are not charged credits for Explore mode generations.
replyUrl is optional, if not provided value from useapi.net account will be used. Place here your callback URL. API will call the provided replyUrl once Runway task completed or failed. Maximum length 1024 characters. We recommend using sites like webhook.site to test callback URL functionality.
replyRef is optional, place here your reference id which will be stored and returned along with this Runway task response / result. Maximum length 1024 characters.
maxJobs is optional, if not provided value for specified account will be used. Valid range: 1…10. Runway has dynamic query capacity and guarantees that, for a given account, at least one job will run — often two, and very rarely, three. If you have a single account linked, keep adding new jobs until you receive a 429 response. Once you get a 429, wait for xx seconds or until at least one job completes, then try again. If you need to run more jobs in parallel, simply add more Runway accounts.

Responses

200 OK

Use returned taskId to retrieve task status and results using GET /tasks/taskId. The generated video url can be found in the artifacts array of the task with the status SUCCEEDED.

If you specify the optional parameter replyUrl the API will call the provided replyUrl with task progress updates until the task is complete or fails.

Text-to-Video Response

{
  "task": {
    "taskId": "user:user_id-runwayml:account_email-task:task_uuid",
    "id": "<uuid>",
    "name": "<name>",
    "image": null,
    "createdAt": "2026-01-23T01:02:03.456Z",
    "updatedAt": "2026-01-23T01:02:03.456Z",
    "taskType": "gen4.5",
    "options": {
        "name": "<name>",
        "route": "t2v",
        "seconds": 5,
        "text_prompt": "<your text prompt>",
        "seed": 12345789,
        "exploreMode": false,
        "watermark": false,
        "width": 1280,
        "height": 720
    },
    "status": "PENDING",
    "error": null,
    "progressText": null,
    "progressRatio": null,
    "estimatedTimeToStartSeconds": 0,
    "artifacts": [],
    "sharedAsset": null,
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "code": 200
  }
}

Image-to-Video Response

{
  "task": {
    "taskId": "user:user_id-runwayml:account_email-task:task_uuid",
    "id": "<uuid>",
    "name": "<name>",
    "image": null,
    "createdAt": "2026-01-23T01:02:03.456Z",
    "updatedAt": "2026-01-23T01:02:03.456Z",
    "taskType": "gen4.5",
    "options": {
        "name": "<name>",
        "route": "k2v",
        "seconds": 8,
        "text_prompt": "<your optional text prompt>",
        "seed": 12345789,
        "exploreMode": false,
        "watermark": false,
        "keyframes": [
            {
                "image": "<image url>",
                "timestamp": 0
            }
        ],
        "width": 720,
        "height": 1280
    },
    "status": "PENDING",
    "error": null,
    "progressText": null,
    "progressRatio": null,
    "estimatedTimeToStartSeconds": 0,
    "artifacts": [],
    "sharedAsset": null,
    "replyUrl": "https://webhook.site/abc",
    "replyRef": "<your optional reference id>",
    "code": 200
  }
}

400 Bad Request

{
  "error": "<Error message>",
  "code": 400
}

401 Unauthorized

{
  "error": "Unauthorized",
  "code": 401
}

412 Insufficient credits

You do not have enough credits to run this task.

{
    "error": "You do not have enough credits to run this task."
}

429 Too Many Requests

Wait in a loop for at least 10..30 seconds and retry again.

There are two possible cases for API response 429:

API query is full and can not accept new gen4_5/create requests. Size of query defined by maxJobs optional parameter.

{
    "error": "Account <Runway account email> is busy executing <Account maxJobs> tasks",
    "runningTasks": {
        "<Runway account email>": [
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#1_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            },
            {
                "email": "<Runway account email>",
                "taskId": "user:user_id-runwayml:account_email-task:task_#N_uuid",
                "id": "<uuid>",
                "replyUrl": "<replyUrl if provided>",
                "replyRef": "<replyRef if provided>"
            }
        ]
    },
    "code": 429
}

The API received an HTTP response status 429 from Runway. Runway has dynamic query management and may limit the number of simultaneously executed tasks based on internal service load and policies.

{
    "error": "You have too many tasks running or pending. Please wait for some of them to finish before starting more."
}

Model

{ // TypeScript, all fields are optional
  task: {
    taskId: string,
    id: string,
    name: string,
    image: string,
    createdAt: string,
    updatedAt: string,
    taskType: string,
    options: {
          name: string,
          seconds: number,
          text_prompt: string,
          seed: number,
          exploreMode: boolean,
          watermark: boolean,
          route: string,  // "t2v" for text-to-video, "k2v" for image-to-video
          keyframes: [{   // I2V only
            image: string,
            timestamp: number
          }],
          width: number,
          height: number,
          assetGroupId: string
    },
    status: string,
    progressText: string,
    progressRatio: number,
    estimatedTimeToStartSeconds: number,
    artifacts: any[],
    sharedAsset: any,
    error: {
      errorMessage: string,
      reason: string,
      message: string,
      moderation_category: string,
      tally_asimov: boolean
    },
    code: number,
    replyUrl: string,
    replyRef: string
  }
}

Examples

curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/runwayml/gen4_5/create" \
     -d '{"text_prompt": "A cinematic shot of a sunset over the ocean"}'

curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/runwayml/gen4_5/create" \
     -d '{"firstImage_assetId": "user:123-runwayml:[email protected]:uuid", "text_prompt": "Camera slowly zooms out", "aspect_ratio": "9:16"}'

// Text-to-Video
const text_prompt = "A cinematic shot of a sunset over the ocean";
const apiUrl = `https://api.useapi.net/v1/runwayml/gen4_5/create`;
const token = "API token";
const data = {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ text_prompt });
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});

// Image-to-Video
const firstImage_assetId = "user:123-runwayml:[email protected]:uuid";
data.body = JSON.stringify({
  firstImage_assetId,
  text_prompt: "Camera slowly zooms out",
  aspect_ratio: "9:16"
});
const i2vResponse = await fetch(apiUrl, data);
const i2vResult = await i2vResponse.json();
console.log("i2v response", {i2vResponse, i2vResult});

import requests

apiUrl = "https://api.useapi.net/v1/runwayml/gen4_5/create"
token = "API token"
headers = {
    "Content-Type": "application/json",
    "Authorization" : f"Bearer {token}"
}

# Text-to-Video
body_t2v = {
    "text_prompt": "A cinematic shot of a sunset over the ocean"
}
response = requests.post(apiUrl, headers=headers, json=body_t2v)
print("T2V:", response, response.json())

# Image-to-Video
body_i2v = {
    "firstImage_assetId": "user:123-runwayml:[email protected]:uuid",
    "text_prompt": "Camera slowly zooms out",
    "aspect_ratio": "9:16"
}
response = requests.post(apiUrl, headers=headers, json=body_i2v)
print("I2V:", response, response.json())