POST gen3turbo/create

Create a video using the first and/or last images with a text prompt and a camera control

August 16, 2024 (November 4, 2024)

Request Headers
Request Body
Responses
Model
Examples
Try It

Runway AI Tools » Audio tools » Text/Image to Video » Gen-3 Alpha Turbo.

Gen-3 Alpha Turbo provides significantly faster generation times with 50% cost reduction, at 5 credits per second of video generation.

You can provide both first and last image inputs in horizontal or vertical aspect ratios.

Gen-3 Alpha Turbo is supported with free accounts and is the only way to experience Runway Gen-3 Alpha if you have a free account.

Please take a look at the code provided in the article Create Runway videos like a Pro as it covers all aspects of video generation and downloading of generated videos along with proper handling of corner cases.

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.

https://api.useapi.net/v1/runwayml/gen3turbo/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

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

firstImage_assetId is optional. 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. Currently Runway only supports image sizes up to 1280x768 or 768x1280 maximum. All other images will be cropped to fit supported sizes. You may want to upscale/downscale your image using image_upscaler to achieve the best results.
lastImage_assetId is optional. Specify the image assetId you want to be present in the last frame. Use GET /assets/?mediaType=image to see the list of image assets. To upload a new image asset use POST /assets. Currently Runway only supports image sizes up to 1280x768 or 768x1280 maximum. All other images will be cropped to fit supported sizes. You may want to upscale/downscale your image using image_upscaler to achieve the best results.
text_prompt is optional. Describe your shot. Gen-3 Alpha Prompting Guide.
aspect_ratio is optional.
Supported values: landscape (default), portrait.
horizontal is optional. Specify horizontal motion.
Supported values: -10…10.
vertical is optional. Specify vertical motion.
Supported values: -10…10.
roll is optional. Specify roll motion.
Supported values: -10…10.
zoom is optional. Specify zoom motion.
Supported values: -10…10.
pan is optional. Specify pan motion.
Supported values: -10…10.
tilt is optional. Specify tilt motion.
Supported values: -10…10.
seconds is optional. Specify desired length of the video in seconds.
Supported values: 5 (default), 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 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 image assetId account will be used.
Valid range: 1…10.

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.

{
    "taskId": "user:user_id-runwayml:account_email-task:task_uuid",
    "id": "<uuid>",
    "name": "<name>",
    "image": null,
    "createdAt": "2024-08-01T01:02:03.456Z",
    "updatedAt": "2024-08-01T01:02:03.456Z",
    "taskType": "gen3a_turbo",
    "options": {
        "name": "<name>",
        "seconds": 10,
        "text_prompt": "<your text prompt>",
        "seed": 12345789,
        "exploreMode": true,
        "watermark": false,
        "enhance_prompt": true,
        "flip": true,
        "keyframes": [
            {
                "image": "<first image url>",
                "timestamp": 0
            },
            {
                "image": "<last image url>",
                "timestamp": 1
            }
        ],
        "assetGroupName": "Generative Video",
        "init_image": "<image url>",
        "recordingEnabled": true
    },
    "status": "PENDING",
    "error": null,
    "progressText": null,
    "progressRatio": null,
    "estimatedTimeToStartSeconds": 0,
    "artifacts": [],
    "sharedAsset": null,
    "features": {
        "storageGB": 500,
        "numPlanCredits_permitted": 2250,
        "numPlanCredits_used": 1315
    },    
    "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
}

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 gen3turbo/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
  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,
        enhance_prompt: boolean,
        keyframes: { image: string, timestamp: number }[],
        flip: boolean,
        camera: {
            x: number,
            y: number,
            r: number,
            z: number,
            bg_x_pan: number,
            bg_y_pan: number
        },        
        assetGroupName: string,
        recordingEnabled: boolean
  },
  status: string,
  progressText: string,
  progressRatio: number,
  estimatedTimeToStartSeconds: number,
  artifacts: any[],
  sharedAsset: any,
  features: {
    storageGB: number,
    numPlanCredits_permitted: number,
    numPlanCredits_used: number
  },    
  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/gen3turbo/create" \
     -d '{"firstImage_assetId": "…", "text_prompt": "…"}'

const firstImage_assetId = "assetId of image asset";      
const text_prompt = "text prompt";      
const apiUrl = `https://api.useapi.net/v1/runwayml/gen3turbo/create`; 
const token = "API token";
const data = { 
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
data.body = JSON.stringify({ 
  firstImage_assetId, text_prompt
});
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});

import requests
firstImage_assetId = "assetId of image asset"      
text_prompt = "text prompt"      
apiUrl = f"https://api.useapi.net/v1/runwayml/gen3turbo/create" 
token = "API token"
headers = {
    "Content-Type": "application/json", 
    "Authorization" : f"Bearer {token}"
}
body = {
    "firstImage_assetId": f"{firstImage_assetId}",
    "text_prompt": f"{text_prompt}"
}
response = requests.post(apiUrl, headers=headers, json=body)
print(response, response.json())