POST gen4/act-two

Create Act-Two videos using Gen-4 with driving video and character reference.

July 22, 2025

Request Headers
Request Body
Responses
Model
Examples
Try It

Runway Generate Video » Gen-4 or Gen-4 Turbo » Act-Two.

Please be aware that Runway’s moderation system analyzes your image and video assets and may fail task with moderation message if the content 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.

https://api.useapi.net/v1/runwayml/gen4/act-two

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

{
    "driving_assetId": "Required assetId of the video asset (3-30 seconds) to drive performance",
    "character_assetId": "Required assetId of the image or video asset for character reference",
    "aspect_ratio": "16:9",
    "body_control": true,
    "expression_intensity": 3,
    "seed": 12345,
    "exploreMode": true,
    "replyUrl": "Place your call back URL here",
    "replyRef": "Place your reference id here",
    "maxJobs": 5
}

driving_assetId is required. Specify the video asset (3-30 seconds duration) you want to use to drive performance. Use GET /assets/?mediaType=video to see the list of video assets. To upload a new video asset use POST /assets.
character_assetId is required. Specify the image or video asset for your character reference. Use GET /assets/?mediaType=image to see the list of image or video assets. To upload a new image or video asset use POST /assets.
aspect_ratio is optional. Controls the output video dimensions.
Supported values: 16:9 (default), 9:16, 1:1, 4:3, 3:4, 21:9.
body_control is optional. Controls body movement tracking.
Default: true.
expression_intensity is optional. Controls the intensity of facial expressions.
Valid range: 1…5, default: 3.
seed is optional. Use the same seed to get reproducible results. If not provided, a random seed will be generated.
Valid range: 1…2147483647.
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 referenced by video assetId 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.

{
  "task": {
    "id": "<uuid>",
    "name": "Act-Two <driving_video_name>_<character_asset_name>",
    "image": null,
    "createdAt": "2025-07-22T06:52:26.378Z",
    "updatedAt": "2025-07-22T06:52:26.468Z",
    "taskType": "act_two",
    "options": {
        "name": "Act-Two <driving_video_name>_<character_asset_name>",
        "driving_video": "<driving video url>",
        "character_image": "<character image url>",
        "character_video": "<character video url>",
        "seconds": 6,
        "exploreMode": false,
        "height": 720,
        "width": 1280,
        "seed": 2830268783,
        "watermark": false,
        "body_control": true,
        "expression_intensity": 1,
        "assetGroupId": "<uuid>",
        "recordingEnabled": true
    },  
    "status": "PENDING",
    "error": null,
    "progressText": null,
    "progressRatio": "0",
    "estimatedTimeToStartSeconds": 0,
    "artifacts": [],
    "sharedAsset": null,
    "sourceAssetId": null,
    "taskId": "user:user_id-runwayml:account_email-task:task_uuid",
    "code": 200
  }
}

400 Bad Request

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

401 Unauthorized

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

404 Not Found

{
    "error": "Unable to retrieve assetId <uuid> (Not found.)",
    "code": 404
}

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/act-two 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: any
    createdAt: string
    updatedAt: string
    taskType: string
    options: {
        name: string
        driving_video: string
        character_image: string
        character_video: string
        seconds: number
        exploreMode: boolean
        height: number
        width: number
        seed: number
        watermark: boolean
        body_control: boolean
        expression_intensity: number
        assetGroupId: string
        recordingEnabled: boolean
    }
    status: string
    progressText: any
    progressRatio: string
    estimatedTimeToStartSeconds: number
    artifacts: any[]
    sharedAsset: any
    sourceAssetId: any
    error: {
      errorMessage: string
      reason: string
      message: string
      moderation_category: string
      tally_asimov: boolean
    }
    code: number
  }
}

Examples

curl -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer …" \
     -X POST "https://api.useapi.net/v1/runwayml/gen4/act-two" \
     -d '{"driving_assetId": "…", "character_assetId": "…"}'

const driving_assetId = "video asset (3-30 seconds) to drive performance";      
const character_assetId = "image or video asset for character reference";      
const apiUrl = `https://api.useapi.net/v1/runwayml/gen4/act-two`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  driving_assetId, character_assetId
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});

import requests
driving_assetId = "video asset (3-30 seconds) to drive performance"
character_assetId = "image or video asset for character reference"
apiUrl = f"https://api.useapi.net/v1/runwayml/gen4/act-two" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "driving_assetId": f"{driving_assetId}",
    "character_assetId": f"{character_assetId}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())