Create a 4-second-long video using text and/or image prompts
August 8, 2024
Table of contents
Runway AI Tools » Audio tools » Text/Image to Video » Gen-2.
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/gen2/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
{
"email": "Optional Runway API account email",
"text_prompt": "Optional text prompt",
"image_assetId": "Optional assetId of image asset",
"image_preview": "Optional image URL generated by GET /text_to_image_preview",
"upscale": true,
"interpolate": true,
"style": "pixel_art",
"aspect_ratio": "3:4",
"motion": 10,
"horizontal": -10,
"vertical": -5,
"roll": -1,
"zoom": 2,
"pan": 5,
"tilt": 10,
"seed": 12345678,
"exploreMode": true,
"replyUrl": "Place your call back URL here",
"replyRef": "Place your reference id here",
"maxJobs": 5,
}
-
email
is optional, if not provided and parameterimage_assetId
is not specified API will randomly select available account. -
text_prompt
is optional. Describe your shot. Gen-2 prompt tips. -
image_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.
Specifyimage_assetId
orimage_preview
but not both. -
image_preview
is optional. Specify the image you want to be present in the first frame. The image URL must be generated using the GET /text_to_image_preview.
Specifyimage_preview
orimage_assetId
but not both. -
upscale
is optional. Set totrue
for 2K upscaling, default isfalse
is for 720p output.
Supported values:true
,false
(default). -
interpolate
is optional.
Supported values:true
(default),false
. -
style
is optional. If not providedcinematic
will be used by default.
Supported values:cinematic
,abandoned
,abstract_sculpture
,advertising
,anime
,architectural
,cartoon
,cine_lens
,claymation
,concept_art
,digital_art
,duotone_artistic_photo
,forestpunk
,frost
,graphic_novel
,graphite
,impressionist_painting
,isometric_3d
,low_poly_3d
,macro_photography
,marker_drawing
,moody_film
,pixel_art
,retro_photography
,sci-fi_art
,stickers
,storyboard
,actor_casting
,thriller
,35mm
,3d_cartoon
,3d_render
,80s_vaporwave
.
This parameter can not be used withimage_preview
orimage_assetId
, your output will match the style of your image. -
aspect_ratio
is optional. If not provided16:9
will be used by default.
Supported values:21:9
,1:1
,9:16
,16:9
,4:3
,3:4
This parameter can not be used withimage_preview
orimage_assetId
, your output will match the aspect ratio of your image. -
motion
is optional. Increase or decrease the intensity of motion in your video. Higher values result in more motion. This parameter is not compatible with other motion parameters below.
Supported values: 1…10. -
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. -
seed
is optional.
Valid range 1…4294967294. -
exploreMode
is optional. Set totrue
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 providedreplyUrl
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
-
Use returned
taskId
to retrieve task status and results using GET /tasks/taskId
. The generated videourl
can be found in theartifacts
array of the task with the statusSUCCEEDED
.If you specify the optional parameter
replyUrl
the API will call the providedreplyUrl
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": "gen2", "options": { "name": "<name>", "seconds": 4, "gen2Options": { "mode": "gen2", "text_prompt": "<name>", "seed": 45678, "interpolate": true, "upscale": true, "watermark": false, "motion_score": 6, "use_motion_score": true, "use_motion_vectors": false, "init_image": "<asset image url>", "width": 1366, "height": 768 }, "exploreMode": true, "assetGroupName": "Generative Video", "recordingEnabled": true }, "status": "PENDING", "error": null, "progressText": null, "progressRatio": null, "estimatedTimeToStartSeconds": 0.1, "artifacts": [], "sharedAsset": null, "features": { "storageGB": 500, "numPlanCredits_permitted": 2250, "numPlanCredits_used": 1315 }, "replyUrl": "https://webhook.site/abc", "replyRef": "<your optional reference id>", "code": 200 }
-
{ "error": "<Error message>", "code": 400 }
-
{ "error": "Unauthorized", "code": 401 }
-
{ "error": "Unable to retrieve assetId <uuid> (Not found.)", "code": 404 }
-
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 gen2/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." }
- API query is full and can not accept new gen2/create requests. Size of query defined by
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,
gen2Options: {
mode: string,
text_prompt: string,
seed: number,
interpolate: boolean,
upscale: boolean,
watermark: boolean,
use_motion_score: boolean,
use_motion_vectors: boolean,
motion_vector: {
x: number,
y: number,
r: number,
z: number,
bg_x_pan: number,
bg_y_pan: number
},
motion_score: number,
init_image: string,
image_prompt: string,
style: string,
width: number,
height: number
},
exploreMode: boolean,
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/gen2/create" \ -d '{"image_assetId": "…", "text_prompt": "…"}'
-
const image_assetId = "assetId of image asset"; const text_prompt = "text prompt"; const apiUrl = `https://api.useapi.net/v1/runwayml/gen2/create`; const token = "API token"; const data = { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' } }; data.body = JSON.stringify({ image_assetId, text_prompt }); const response = await fetch(apiUrl, data); const result = await response.json(); console.log("response", {response, result});
-
import requests image_assetId = "assetId of image asset" text_prompt = "text prompt" apiUrl = f"https://api.useapi.net/v1/runwayml/gen2/create" token = "API token" headers = { "Content-Type": "application/json", "Authorization" : f"Bearer {token}" } body = { "image_assetId": f"{image_assetId}", "text_prompt": f"{text_prompt}" } response = requests.post(apiUrl, headers=headers, json=body) print(response, response.json())