API Reference

Start generating

These endpoints all kick off tasks to create generations.

Image to video

POST/v1/image_to_video

This endpoint will start a new task to generate a video from an image.

Authentication

Authorization: Use the HTTP Authorization header with the Bearer scheme along with an API key.

Headers

X-Runway-VersionRequiredstring: The version of the RunwayML API being used. You can read more about versioning here.

This field must be set to the exact value 2024-11-06.

Request body

modelRequiredstring Accepted values:"gen4.5", "gen4_turbo", "gen3a_turbo", "veo3.1", "veo3.1_fast", "veo3": Fields change based on which value is passed. Select which value to show documentation for.

promptTextRequiredstring[ 1 .. 1000 ] characters

A non-empty string up to 1000 characters (measured in UTF-16 code units). This should describe in detail what should appear in the output.

promptImageRequiredstring or Array of PromptImages (objects)

One of the following shapes:

string

A HTTPS URL, Runway or data URI containing an encoded image. See our docs on image inputs for more information.

One of the following shapes:

string[ 13 .. 2048 ] characters^https:\/\/.*

A HTTPS URL.

string[ 13 .. 5000 ] characters^runway:\/\/.*

A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.

string[ 13 .. 5242880 ] characters^data:image\/.*

A data URI containing encoded media.

PromptImagesArray of objects= 1 items

uriRequiredstring: A HTTPS URL, Runway or data URI containing an encoded image. See our docs on image inputs for more information.

One of the following shapes:
string[ 13 .. 2048 ] characters^https:\/\/.*

A HTTPS URL.

string[ 13 .. 5000 ] characters^runway:\/\/.*

A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.

string[ 13 .. 5242880 ] characters^data:image\/.*

A data URI containing encoded media.
positionRequiredstring: The position of the image in the output video. "first" will use the image as the first frame of the video.

This field must be set to the exact value first.

ratioRequiredstring

Accepted values:"1280:720", "720:1280", "1104:832", "960:960", "832:1104", "1584:672"

The resolution of the output video.

durationRequiredinteger[ 2 .. 10 ]

The number of seconds of duration for the output video. Must be an integer from 2 to 10.

seedinteger[ 0 .. 4294967295 ]

If unspecified, a random number is chosen. Varying the seed integer is a way to get different results for the same other request parameters. Using the same seed integer for an identical request will produce similar results.

contentModerationobject

Settings that affect the behavior of the content moderation system.

publicFigureThresholdstring: Accepted values:"auto", "low"

When set to low, the content moderation system will be less strict about preventing generations that include recognizable public figures.

Responses

// npm install --save @runwayml/sdk
import RunwayML from '@runwayml/sdk';

// The env var RUNWAYML_API_SECRET is expected to contain your API key.
const client = new RunwayML();

const task = await client.imageToVideo
  .create({
    model: 'gen4_turbo',
    promptImage: 'https://example.com/bunny.jpg',
    promptText: 'A cute bunny hopping in a meadow',
    duration: 10,
  })
  .waitForTaskOutput();

console.log(task);

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Text to video

POST/v1/text_to_video

This endpoint will start a new task to generate a video from a text prompt.

Authentication

Authorization: Use the HTTP Authorization header with the Bearer scheme along with an API key.

Headers

X-Runway-VersionRequiredstring: The version of the RunwayML API being used. You can read more about versioning here.

This field must be set to the exact value 2024-11-06.

Request body

modelRequiredstring Accepted values:"gen4.5", "veo3.1", "veo3.1_fast", "veo3": Fields change based on which value is passed. Select which value to show documentation for.

promptTextRequiredstring[ 1 .. 1000 ] characters

A non-empty string up to 1000 characters (measured in UTF-16 code units). This should describe in detail what should appear in the output.

ratioRequiredstring

Accepted values:"1280:720", "720:1280"

The resolution of the output video.

durationRequiredinteger[ 2 .. 10 ]

The number of seconds of duration for the output video. Must be an integer from 2 to 10.

seedinteger[ 0 .. 4294967295 ]

contentModerationobject

Settings that affect the behavior of the content moderation system.

publicFigureThresholdstring: Accepted values:"auto", "low"

When set to low, the content moderation system will be less strict about preventing generations that include recognizable public figures.

Responses

// npm install --save @runwayml/sdk
import RunwayML from '@runwayml/sdk';

// The env var RUNWAYML_API_SECRET is expected to contain your API key.
const client = new RunwayML();

const task = await client.textToVideo
  .create({
    model: 'veo3.1',
    promptText: 'A cute bunny hopping in a meadow',
    ratio: '1280:720',
    duration: 8,
  })
  .waitForTaskOutput();

console.log(task);

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Video to video

POST/v1/video_to_video

This endpoint will start a new task to generate a video from a video.

Authentication

Authorization: Use the HTTP Authorization header with the Bearer scheme along with an API key.

Headers

X-Runway-VersionRequiredstring: The version of the RunwayML API being used. You can read more about versioning here.

This field must be set to the exact value 2024-11-06.

Request body

modelRequiredstring: This field must be set to the exact value gen4_aleph.

videoUriRequiredstring

A HTTPS URL, Runway or data URI containing an encoded video. See our docs on video inputs for more information.

One of the following shapes:

string[ 13 .. 2048 ] characters^https:\/\/.*

A HTTPS URL.

string[ 13 .. 5000 ] characters^runway:\/\/.*

A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.

string[ 13 .. 16777216 ] characters^data:video\/.*

A data URI containing encoded media.

promptTextRequiredstring[ 1 .. 1000 ] characters

A non-empty string up to 1000 characters (measured in UTF-16 code units). This should describe in detail what should appear in the output.

seedinteger[ 0 .. 4294967295 ]

referencesArray of ImageReference (object)

An array of references. Currently up to one reference is supported. See our docs on image inputs for more information.

ImageReferenceobject

Passing an image reference allows the model to emulate the style or content of the reference in the output.

typeRequiredstring: This field must be set to the exact value image.
uriRequiredstring: A HTTPS URL, Runway or data URI containing an encoded image. See our docs on image inputs for more information.

One of the following shapes:
string[ 13 .. 2048 ] characters^https:\/\/.*

A HTTPS URL.

string[ 13 .. 5000 ] characters^runway:\/\/.*

A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.

string[ 13 .. 5242880 ] characters^data:image\/.*

A data URI containing encoded media.

contentModerationobject

Settings that affect the behavior of the content moderation system.

publicFigureThresholdstring: Accepted values:"auto", "low"

When set to low, the content moderation system will be less strict about preventing generations that include recognizable public figures.

ratiostring

Deprecated

Accepted values:"1280:720", "720:1280", "1104:832", "960:960", "832:1104", "1584:672", "848:480", "640:480"

Deprecated. This field is ignored. The resolution of the output video is determined by the input video.

Responses

// npm install --save @runwayml/sdk
import RunwayML from '@runwayml/sdk';

// The env var RUNWAYML_API_SECRET is expected to contain your API key.
const client = new RunwayML();

const task = await client.videoToVideo
  .create({
    model: 'gen4_aleph',
    videoUri: 'https://example.com/bunny.mp4',
    promptText: 'string',
    references: [
      {
        type: 'image',
        uri: 'https://example.com/easter-scene.jpg',
      },
    ],
    ratio: '1280:720',
  })
  .waitForTaskOutput();

console.log(task);

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Text/Image to Image

POST/v1/text_to_image

This endpoint will start a new task to generate images from text and/or image(s)

Authentication

Authorization: Use the HTTP Authorization header with the Bearer scheme along with an API key.

Headers

X-Runway-VersionRequiredstring: The version of the RunwayML API being used. You can read more about versioning here.

This field must be set to the exact value 2024-11-06.

Request body

modelRequiredstring Accepted values:"gen4_image_turbo", "gen4_image", "gemini_2.5_flash": Fields change based on which value is passed. Select which value to show documentation for.

promptTextRequiredstring[ 1 .. 1000 ] characters

A non-empty string up to 1000 characters (measured in UTF-16 code units). This should describe in detail what should appear in the output.

ratioRequiredstring

Accepted values:"1024:1024", "1080:1080", "1168:880", "1360:768", "1440:1080", "1080:1440", "1808:768", "1920:1080", "1080:1920", "2112:912", "1280:720", "720:1280", "720:720", "960:720", "720:960", "1680:720"

The resolution of the output image.

referenceImagesRequiredArray of objects[ 1 .. 3 ] items

An array of one to three images to be used as references for the generated image output.

uriRequiredstring: A HTTPS URL, Runway or data URI containing an encoded image. See our docs on image inputs for more information.

One of the following shapes:
string[ 13 .. 2048 ] characters^https:\/\/.*

A HTTPS URL.

string[ 13 .. 5000 ] characters^runway:\/\/.*

A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.

string[ 13 .. 5242880 ] characters^data:image\/.*

A data URI containing encoded media.
tagstring[ 3 .. 16 ] characters^[a-z][a-z0-9_]+$: A tag to identify the reference image. This is used to reference the image in prompt text.

seedinteger[ 0 .. 4294967295 ]

contentModerationobject

Settings that affect the behavior of the content moderation system.

publicFigureThresholdstring: Accepted values:"auto", "low"

When set to low, the content moderation system will be less strict about preventing generations that include recognizable public figures.

Responses

// npm install --save @runwayml/sdk
import RunwayML from '@runwayml/sdk';

// The env var RUNWAYML_API_SECRET is expected to contain your API key.
const client = new RunwayML();

const task = await client.textToImage
  .create({
    model: 'gen4_image',
    promptText: 'A serene landscape with mountains',
    ratio: '1360:768',
  })
  .waitForTaskOutput();

console.log(task);

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Control a character

POST/v1/character_performance

This endpoint will start a new task to control a character's facial expressions and body movements using a reference video.

Authentication

Authorization: Use the HTTP Authorization header with the Bearer scheme along with an API key.

Headers

X-Runway-VersionRequiredstring: The version of the RunwayML API being used. You can read more about versioning here.

This field must be set to the exact value 2024-11-06.

Request body

modelRequiredstring: This field must be set to the exact value act_two.

characterRequiredCharacterImage (object) or CharacterVideo (object)

The character to control. You can either provide a video or an image. A visually recognizable face must be visible and stay within the frame.

One of the following shapes:

CharacterImageobject

An image of your character. In the output, the character will use the reference video performance in its original static environment.

typeRequiredstring: This field must be set to the exact value image.
uriRequiredstring: A HTTPS URL, Runway or data URI containing an encoded image. See our docs on image inputs for more information.

One of the following shapes:
string[ 13 .. 2048 ] characters^https:\/\/.*

A HTTPS URL.

string[ 13 .. 5000 ] characters^runway:\/\/.*

A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.

string[ 13 .. 5242880 ] characters^data:image\/.*

A data URI containing encoded media.

CharacterVideoobject

A video of your character. In the output, the character will use the reference video performance in its original animated environment and some of the character's own movements.

typeRequiredstring: This field must be set to the exact value video.
uriRequiredstring: A HTTPS URL, Runway or data URI containing an encoded video. See our docs on video inputs for more information.

One of the following shapes:
string[ 13 .. 2048 ] characters^https:\/\/.*

A HTTPS URL.

string[ 13 .. 5000 ] characters^runway:\/\/.*

A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.

string[ 13 .. 16777216 ] characters^data:video\/.*

A data URI containing encoded media.

referenceRequiredCharacterReferenceVideo (object)

The reference video containing the performance to apply to the character.

CharacterReferenceVideoobject

A video of a person performing in the manner that you would like your character to perform. The video must be between 3 and 30 seconds in duration.

typeRequiredstring: This field must be set to the exact value video.
uriRequiredstring: A video of a person performing in the manner that you would like your character to perform. The video must be between 3 and 30 seconds in duration. See our docs on video inputs for more information.

One of the following shapes:
string[ 13 .. 2048 ] characters^https:\/\/.*

A HTTPS URL.

string[ 13 .. 5000 ] characters^runway:\/\/.*

A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.

string[ 13 .. 16777216 ] characters^data:video\/.*

A data URI containing encoded media.

seedinteger[ 0 .. 4294967295 ]

bodyControlboolean

A boolean indicating whether to enable body control. When enabled, non-facial movements and gestures will be applied to the character in addition to facial expressions.

expressionIntensityinteger[ 1 .. 5 ]

Default:3

An integer between 1 and 5 (inclusive). A larger value increases the intensity of the character's expression.

ratiostring

Accepted values:"1280:720", "720:1280", "960:960", "1104:832", "832:1104", "1584:672"

The resolution of the output video.

contentModerationobject

Settings that affect the behavior of the content moderation system.

publicFigureThresholdstring: Accepted values:"auto", "low"

When set to low, the content moderation system will be less strict about preventing generations that include recognizable public figures.

Responses

// npm install --save @runwayml/sdk
import RunwayML from '@runwayml/sdk';

// The env var RUNWAYML_API_SECRET is expected to contain your API key.
const client = new RunwayML();

const task = await client.characterPerformance
  .create({
    model: 'act_two',
    character: {
      type: 'video',
      uri: 'https://example.com/posedCharacter.mp4',
    },
    reference: {
      type: 'video',
      uri: 'https://example.com/actorPerformance.mp4',
    },
    ratio: '1280:720',
  })
  .waitForTaskOutput();
console.log(task);

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Generate sound effects

POST/v1/sound_effect

This endpoint will start a new task to generate sound effects from a text description.

Authentication

Authorization: Use the HTTP Authorization header with the Bearer scheme along with an API key.

Headers

X-Runway-VersionRequiredstring: The version of the RunwayML API being used. You can read more about versioning here.

This field must be set to the exact value 2024-11-06.

Request body

modelRequiredstring: This field must be set to the exact value eleven_text_to_sound_v2.

promptTextRequiredstring[ 1 .. 3000 ] characters: A text description of the sound effect to generate.
durationnumber[ 0.5 .. 30 ]: The duration of the sound effect in seconds, between 0.5 and 30 seconds. If not provided, the duration will be determined automatically based on the text description.
loopboolean: Default:false

Whether the output sound effect should be designed to loop seamlessly.

Responses

// npm install --save @runwayml/sdk
import RunwayML from '@runwayml/sdk';

// The env var RUNWAYML_API_SECRET is expected to contain your API key.
const client = new RunwayML();

const task = await client.soundEffect
  .create({
    model: 'eleven_text_to_sound_v2',
    promptText: 'A thunderstorm with heavy rain',
    duration: 10,
    loop: true,
  })
  .waitForTaskOutput();
console.log(task);

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Speech to speech

POST/v1/speech_to_speech

This endpoint will start a new task to convert speech from one voice to another in audio or video.

Authentication

Authorization: Use the HTTP Authorization header with the Bearer scheme along with an API key.

Headers

X-Runway-VersionRequiredstring: The version of the RunwayML API being used. You can read more about versioning here.

This field must be set to the exact value 2024-11-06.

Request body

modelRequiredstring: This field must be set to the exact value eleven_multilingual_sts_v2.

mediaRequiredSpeechToSpeechAudio (object) or SpeechToSpeechVideo (object)

One of the following shapes:

SpeechToSpeechAudioobject

An audio file containing dialogue to be processed.

typeRequiredstring: This field must be set to the exact value audio.
uriRequiredstring: A HTTPS URL, Runway or data URI containing an encoded audio. See our docs on audio inputs for more information.

One of the following shapes:
string[ 13 .. 2048 ] characters^https:\/\/.*

A HTTPS URL.

string[ 13 .. 5000 ] characters^runway:\/\/.*

A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.

string[ 13 .. 16777216 ] characters^data:audio\/.*

A data URI containing encoded media.

SpeechToSpeechVideoobject

A video file containing dialogue to be processed.

typeRequiredstring: This field must be set to the exact value video.
uriRequiredstring: A HTTPS URL, Runway or data URI containing an encoded video. See our docs on video inputs for more information.

One of the following shapes:
string[ 13 .. 2048 ] characters^https:\/\/.*

A HTTPS URL.

string[ 13 .. 5000 ] characters^runway:\/\/.*

A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.

string[ 13 .. 16777216 ] characters^data:video\/.*

A data URI containing encoded media.

voiceRequiredRunwayPresetVoice (object)

The voice to use for the generated speech.

RunwayPresetVoiceobject

A voice preset from the RunwayML API.

typeRequiredstring: This field must be set to the exact value runway-preset.
presetIdRequiredstring: Accepted values:"Maya", "Arjun", "Serene", "Bernard", "Billy", "Mark", "Clint", "Mabel", "Chad", "Leslie", "Eleanor", "Elias", "Elliot", "Grungle", "Brodie", "Sandra", "Kirk", "Kylie", "Lara", "Lisa", "Malachi", "Marlene", "Martin", "Miriam", "Monster", "Paula", "Pip", "Rusty", "Ragnar", "Xylar", "Maggie", "Jack", "Katie", "Noah", "James", "Rina", "Ella", "Mariah", "Frank", "Claudia", "Niki", "Vincent", "Kendrick", "Myrna", "Tom", "Wanda", "Benjamin", "Kiana", "Rachel"

The preset voice ID to use for the generated speech.

removeBackgroundNoiseboolean

Whether to remove background noise from the generated speech.

Responses

// npm install --save @runwayml/sdk
import RunwayML from '@runwayml/sdk';

// The env var RUNWAYML_API_SECRET is expected to contain your API key.
const client = new RunwayML();

const audioTask = await client.speechToSpeech
  .create({
    model: 'eleven_multilingual_sts_v2',
    media: {
      type: 'audio',
      uri: 'https://example.com/audio.mp3',
    },
    voice: {
      type: 'runway-preset',
      presetId: 'Maggie',
    },
  })
  .waitForTaskOutput();
console.log(audioTask);

const videoTask = await client.speechToSpeech
  .create({
    model: 'eleven_multilingual_sts_v2',
    media: {
      type: 'video',
      uri: 'https://example.com/video.mp4',
    },
    voice: {
      type: 'runway-preset',
      presetId: 'Noah',
    },
  })
  .waitForTaskOutput();
console.log(videoTask);

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Text to speech

POST/v1/text_to_speech

This endpoint will start a new task to generate speech from text.

Authentication

Authorization: Use the HTTP Authorization header with the Bearer scheme along with an API key.

Headers

X-Runway-VersionRequiredstring: The version of the RunwayML API being used. You can read more about versioning here.

This field must be set to the exact value 2024-11-06.

Request body

modelRequiredstring: This field must be set to the exact value eleven_multilingual_v2.

promptTextRequiredstring[ 1 .. 1000 ] characters

A non-empty string up to 1000 characters (measured in UTF-16 code units). This should describe in detail what should appear in the output.

voiceRequiredRunwayPresetVoice (object)

The voice to use for the generated speech.

RunwayPresetVoiceobject

A voice preset from the RunwayML API.

typeRequiredstring: This field must be set to the exact value runway-preset.
presetIdRequiredstring: Accepted values:"Maya", "Arjun", "Serene", "Bernard", "Billy", "Mark", "Clint", "Mabel", "Chad", "Leslie", "Eleanor", "Elias", "Elliot", "Grungle", "Brodie", "Sandra", "Kirk", "Kylie", "Lara", "Lisa", "Malachi", "Marlene", "Martin", "Miriam", "Monster", "Paula", "Pip", "Rusty", "Ragnar", "Xylar", "Maggie", "Jack", "Katie", "Noah", "James", "Rina", "Ella", "Mariah", "Frank", "Claudia", "Niki", "Vincent", "Kendrick", "Myrna", "Tom", "Wanda", "Benjamin", "Kiana", "Rachel"

The preset voice ID to use for the generated speech.

Responses

// npm install --save @runwayml/sdk
import RunwayML from '@runwayml/sdk';

// The env var RUNWAYML_API_SECRET is expected to contain your API key.
const client = new RunwayML();

const task = await client.textToSpeech
  .create({
    model: 'eleven_multilingual_v2',
    promptText: 'The quick brown fox jumps over the lazy dog',
    voice: {
      type: 'runway-preset',
      presetId: 'Leslie',
    },
  })
  .waitForTaskOutput();
console.log(task);

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Voice dubbing

POST/v1/voice_dubbing

This endpoint will start a new task to dub audio content to a target language.

Authentication

Authorization: Use the HTTP Authorization header with the Bearer scheme along with an API key.

Headers

X-Runway-VersionRequiredstring: The version of the RunwayML API being used. You can read more about versioning here.

This field must be set to the exact value 2024-11-06.

Request body

modelRequiredstring: This field must be set to the exact value eleven_voice_dubbing.

audioUriRequiredstring: A HTTPS URL, Runway or data URI containing an encoded audio. See our docs on audio inputs for more information.

One of the following shapes:
string[ 13 .. 2048 ] characters^https:\/\/.*

A HTTPS URL.

string[ 13 .. 5000 ] characters^runway:\/\/.*

A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.

string[ 13 .. 16777216 ] characters^data:audio\/.*

A data URI containing encoded media.
targetLangRequiredstring: Accepted values:"en", "hi", "pt", "zh", "es", "fr", "de", "ja", "ar", "ru", "ko", "id", "it", "nl", "tr", "pl", "sv", "fil", "ms", "ro", "uk", "el", "cs", "da", "fi", "bg", "hr", "sk", "ta"

The target language code to dub the audio to (e.g., "es" for Spanish, "fr" for French).
disableVoiceCloningboolean: Whether to disable voice cloning and use a generic voice instead.
dropBackgroundAudioboolean: Whether to remove background audio from the dubbed output.
numSpeakersinteger( 0 .. 9007199254740991 ]: The number of speakers in the audio. If not provided, it will be detected automatically.

Responses

// npm install --save @runwayml/sdk
import RunwayML from '@runwayml/sdk';

// The env var RUNWAYML_API_SECRET is expected to contain your API key.
const client = new RunwayML();

const task = await client.voiceDubbing
  .create({
    model: 'eleven_voice_dubbing',
    audioUri: 'https://example.com/audio.mp3',
    targetLang: 'es',
  })
  .waitForTaskOutput();
console.log(task);

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Voice isolation

POST/v1/voice_isolation

This endpoint will start a new task to isolate the voice from the background audio. Audio duration must be greater than 4.6 seconds and less than 3600 seconds.

Authentication

Authorization: Use the HTTP Authorization header with the Bearer scheme along with an API key.

Headers

X-Runway-VersionRequiredstring: The version of the RunwayML API being used. You can read more about versioning here.

This field must be set to the exact value 2024-11-06.

Request body

modelRequiredstring: This field must be set to the exact value eleven_voice_isolation.

audioUriRequiredstring: A HTTPS URL, Runway or data URI containing an encoded audio. See our docs on audio inputs for more information.

One of the following shapes:
string[ 13 .. 2048 ] characters^https:\/\/.*

A HTTPS URL.

string[ 13 .. 5000 ] characters^runway:\/\/.*

A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.

string[ 13 .. 16777216 ] characters^data:audio\/.*

A data URI containing encoded media.

Responses

// npm install --save @runwayml/sdk
import RunwayML from '@runwayml/sdk';

// The env var RUNWAYML_API_SECRET is expected to contain your API key.
const client = new RunwayML();

const task = await client.voiceIsolation
  .create({
    model: 'eleven_voice_isolation',
    audioUrl: 'https://example.com/audio.mp3',
  })
  .waitForTaskOutput();
console.log(task);

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Task management

Endpoints for managing tasks that have been submitted.

Get task detail

GET/v1/tasks/{id}

Return details about a task. Consumers of this API should not expect updates more frequent than once every five seconds for a given task.

Authentication

Authorization: Use the HTTP Authorization header with the Bearer scheme along with an API key.

Path parameters

idRequiredstring <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{...: The ID of a previously-submitted task that has not been canceled or deleted.

Headers

X-Runway-VersionRequiredstring: The version of the RunwayML API being used. You can read more about versioning here.

This field must be set to the exact value 2024-11-06.

Responses

// npm install --save @runwayml/sdk
import RunwayML from '@runwayml/sdk';

// The env var RUNWAYML_API_SECRET is expected to contain your API key.
const client = new RunwayML();

// Fetch the current state of the task:
const task = await client.tasks.retrieve(
  '17f20503-6c24-4c16-946b-35dbbce2af2f'
);

// Or, wait for the task to succeed or fail:
const task = await client.tasks
  .retrieve('17f20503-6c24-4c16-946b-35dbbce2af2f')
  .waitForTaskOutput();

{"id": "17f20503-6c24-4c16-946b-35dbbce2af2f",
"status": "PENDING",
"createdAt": "2024-06-27T19:49:32.334Z"
}

Cancel or delete a task

DELETE/v1/tasks/{id}

Tasks that are running, pending, or throttled can be canceled by invoking this method. Invoking this method for other tasks will delete them.

The output data associated with a deleted task will be deleted from persistent storage in accordance with our data retention policy. Aborted and deleted tasks will not be able to be fetched again in the future.

Authentication

Authorization: Use the HTTP Authorization header with the Bearer scheme along with an API key.

Path parameters

idRequiredstring <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{...: The ID of a previously-submitted task that has not been canceled or deleted.

Headers

X-Runway-VersionRequiredstring: The version of the RunwayML API being used. You can read more about versioning here.

This field must be set to the exact value 2024-11-06.

Responses

// npm install --save @runwayml/sdk
import RunwayML from '@runwayml/sdk';

// The env var RUNWAYML_API_SECRET is expected to contain your API key.
const client = new RunwayML();

await client.tasks.delete('17f20503-6c24-4c16-946b-35dbbce2af2f');

Uploads

Endpoints for uploading media files.

Upload a file

POST/v1/uploads

Uploads a temporary media file that can be referenced in API generation requests. The uploaded files will be automatically expired and deleted after a period of time. It is strongly recommended to use our SDKs for this which have a simplified interface that directly accepts file objects.

Authentication

Authorization: Use the HTTP Authorization header with the Bearer scheme along with an API key.

Headers

X-Runway-VersionRequiredstring: The version of the RunwayML API being used. You can read more about versioning here.

This field must be set to the exact value 2024-11-06.

Request body

filenameRequiredstring[ 3 .. 255 ] characters: The filename of the file to upload. Must have a valid extension and be a supported media type (image, video, or audio).
typeRequiredstring: Accepted value:"ephemeral"

The type of upload to create

Responses

// npm install --save @runwayml/sdk
import RunwayML from '@runwayml/sdk';
import fs from 'node:fs';

// The env var RUNWAYML_API_SECRET is expected to contain your API key.
const client = new RunwayML();

filename = './funny-cats.mp4';
const uploadUri = await client.uploads.createEphemeral(
  fs.createReadStream(filename),
);

// Use the runwayUri in generation requests
const task = await client.videoToVideo
  .create({
    model: 'gen4_aleph',
    videoUri: uploadUri,
    promptText: 'Add the easter elements to the cat video',
    references: [
      {
        type: 'image',
        uri: 'https://example.com/easter-scene.jpg',
      },
    ],
    ratio: '1280:720',
  })
  .waitForTaskOutput();

console.log(task);

{"uploadUrl": "http://example.com",
"fields": {"property1": "string",
"property2": "string"
},
"runwayUri": "string"
}

Avatars

List avatars

GET/v1/avatars

List avatars for the authenticated user with cursor-based pagination.

Authentication

Authorization: Use the HTTP Authorization header with the Bearer scheme along with an API key.

Query parameters

limitRequiredinteger[ 1 .. 100 ]: Default:50

The maximum number of items to return per page.
cursorstring[ 1 .. 1000 ] characters: Cursor from a previous response for fetching the next page of results.

Headers

X-Runway-VersionRequiredstring: The version of the RunwayML API being used. You can read more about versioning here.

This field must be set to the exact value 2024-11-06.

Responses

// npm install --save @runwayml/sdk
import RunwayML from '@runwayml/sdk';

// The env var RUNWAYML_API_SECRET is expected to contain your API key.
const client = new RunwayML();

const avatars = await client.avatars.list();
for await (const avatar of avatars) {
  console.log(avatar);
}

{"data": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"personality": "string",
"startScript": "string",
"voice": {"type": "runway-live-preset",
"presetId": "victoria",
"name": "string",
"description": "string"
},
"referenceImageUri": "string",
"processedImageUri": "string",
"documentIds": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"status": "PROCESSING"
}
],
"hasMore": true,
"nextCursor": "string"
}

Create avatar

POST/v1/avatars

Create a new avatar with a reference image and voice.

Authentication

Authorization: Use the HTTP Authorization header with the Bearer scheme along with an API key.

Headers

X-Runway-VersionRequiredstring: The version of the RunwayML API being used. You can read more about versioning here.

This field must be set to the exact value 2024-11-06.

Request body

nameRequiredstring[ 1 .. 50 ] characters

The character name for the avatar.

referenceImageRequiredstring

A HTTPS URL, Runway URI, or data URI containing the avatar reference image. See our docs for supported formats.

One of the following shapes:

string[ 13 .. 2048 ] characters^https:\/\/.*

A HTTPS URL.

string[ 13 .. 5000 ] characters^runway:\/\/.*

A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.

string[ 13 .. 5242880 ] characters^data:image\/.*

A data URI containing encoded media.

personalityRequiredstring[ 1 .. 2000 ] characters

System prompt defining how the avatar should behave in conversations.

voiceRequiredRunwayLivePresetVoice (object) or CustomVoice (object)

The voice configuration for the avatar.

One of the following shapes:

RunwayLivePresetVoiceobject

A preset voice from the Runway API.

typeRequiredstring: This field must be set to the exact value runway-live-preset.
presetIdRequiredstring: Accepted values:"victoria", "vincent", "clara", "drew", "skye", "max", "morgan", "felix", "mia", "marcus", "summer", "ruby", "aurora", "jasper", "leo", "adrian", "nina", "emma", "blake", "david", "maya", "nathan", "sam", "georgia", "petra", "adam", "zach", "violet", "roman", "luna"

The ID of a preset voice. Available voices: victoria (Victoria), vincent (Vincent), clara (Clara), drew (Drew), skye (Skye), max (Max), morgan (Morgan), felix (Felix), mia (Mia), marcus (Marcus), summer (Summer), ruby (Ruby), aurora (Aurora), jasper (Jasper), leo (Leo), adrian (Adrian), nina (Nina), emma (Emma), blake (Blake), david (David), maya (Maya), nathan (Nathan), sam (Sam), georgia (Georgia), petra (Petra), adam (Adam), zach (Zach), violet (Violet), roman (Roman), luna (Luna).

CustomVoiceobject

A custom voice created via the Voices API.

typeRequiredstring: This field must be set to the exact value custom.
idRequiredstring <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{...: The ID of a custom voice created via the Voices API.

startScriptstring<= 2000 characters

Optional opening message that the avatar will say when a session starts.

documentIdsArray of strings <uuid> <= 50 items[^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{...]

Optional list of knowledge document IDs to attach to this avatar. Documents provide additional context during conversations.

imageProcessingstring

Default:"optimize"

Accepted values:"optimize", "none"

Controls image preprocessing. optimize improves the image for better avatar results. none uses the image as-is; quality not guaranteed.

Responses

// npm install --save @runwayml/sdk
import RunwayML from '@runwayml/sdk';

// The env var RUNWAYML_API_SECRET is expected to contain your API key.
const client = new RunwayML();

const avatar = await client.avatars.create({
  name: 'Customer Support Agent',
  referenceImage: 'https://example.com/reference.jpg',
  personality: 'You are a helpful customer support agent. Be friendly and concise.',
  voice: { type: 'runway-live-preset', presetId: 'adrian' },
});
console.log(avatar);

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"personality": "string",
"startScript": "string",
"voice": {"type": "runway-live-preset",
"presetId": "victoria",
"name": "string",
"description": "string"
},
"referenceImageUri": "string",
"processedImageUri": "string",
"documentIds": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"status": "AvatarProcessing"
}

Get avatar

GET/v1/avatars/{id}

Get details of a specific avatar.

Authentication

Authorization: Use the HTTP Authorization header with the Bearer scheme along with an API key.

Path parameters

idRequiredstring <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{...

Headers

X-Runway-VersionRequiredstring: The version of the RunwayML API being used. You can read more about versioning here.

This field must be set to the exact value 2024-11-06.

Responses

// npm install --save @runwayml/sdk
import RunwayML from '@runwayml/sdk';

// The env var RUNWAYML_API_SECRET is expected to contain your API key.
const client = new RunwayML();

const avatar = await client.avatars.retrieve(
  '550e8400-e29b-41d4-a716-446655440000'
);
console.log(avatar);

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"personality": "string",
"startScript": "string",
"voice": {"type": "runway-live-preset",
"presetId": "victoria",
"name": "string",
"description": "string"
},
"referenceImageUri": "string",
"processedImageUri": "string",
"documentIds": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"status": "AvatarProcessing"
}

Update avatar

PATCH/v1/avatars/{id}

Update an existing avatar. At least one field must be provided.

Authentication

Authorization: Use the HTTP Authorization header with the Bearer scheme along with an API key.

Path parameters

idRequiredstring <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{...

Headers

X-Runway-VersionRequiredstring: The version of the RunwayML API being used. You can read more about versioning here.

This field must be set to the exact value 2024-11-06.

Request body

namestring[ 1 .. 50 ] characters

The character name for the avatar.

referenceImagestring

A HTTPS URL, Runway URI, or data URI containing the avatar reference image. See our docs for supported formats.

One of the following shapes:

string[ 13 .. 2048 ] characters^https:\/\/.*

A HTTPS URL.

string[ 13 .. 5000 ] characters^runway:\/\/.*

A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.

string[ 13 .. 5242880 ] characters^data:image\/.*

A data URI containing encoded media.

personalitystring[ 1 .. 2000 ] characters

System prompt defining how the avatar should behave in conversations.

startScriptstring or null

Optional opening message that the avatar will say when a session starts. Set to null to clear.

One of the following shapes:

string<= 2000 characters

Optional opening message that the avatar will say when a session starts. Set to null to clear.

null

Optional opening message that the avatar will say when a session starts. Set to null to clear.

voiceRunwayLivePresetVoice (object) or CustomVoice (object)

The voice configuration for the avatar.

One of the following shapes:

RunwayLivePresetVoiceobject

A preset voice from the Runway API.

typeRequiredstring: This field must be set to the exact value runway-live-preset.
presetIdRequiredstring: Accepted values:"victoria", "vincent", "clara", "drew", "skye", "max", "morgan", "felix", "mia", "marcus", "summer", "ruby", "aurora", "jasper", "leo", "adrian", "nina", "emma", "blake", "david", "maya", "nathan", "sam", "georgia", "petra", "adam", "zach", "violet", "roman", "luna"

The ID of a preset voice. Available voices: victoria (Victoria), vincent (Vincent), clara (Clara), drew (Drew), skye (Skye), max (Max), morgan (Morgan), felix (Felix), mia (Mia), marcus (Marcus), summer (Summer), ruby (Ruby), aurora (Aurora), jasper (Jasper), leo (Leo), adrian (Adrian), nina (Nina), emma (Emma), blake (Blake), david (David), maya (Maya), nathan (Nathan), sam (Sam), georgia (Georgia), petra (Petra), adam (Adam), zach (Zach), violet (Violet), roman (Roman), luna (Luna).

CustomVoiceobject

A custom voice created via the Voices API.

typeRequiredstring: This field must be set to the exact value custom.
idRequiredstring <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{...: The ID of a custom voice created via the Voices API.

documentIdsArray of strings <uuid> <= 50 items[^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{...]

List of knowledge document IDs to attach to this avatar. Replaces all current attachments. Documents provide additional context during conversations.

imageProcessingstring

Default:"optimize"

Accepted values:"optimize", "none"

Controls image preprocessing. optimize improves the image for better avatar results. none uses the image as-is; quality not guaranteed.

Responses

// npm install --save @runwayml/sdk
import RunwayML from '@runwayml/sdk';

// The env var RUNWAYML_API_SECRET is expected to contain your API key.
const client = new RunwayML();

const avatar = await client.avatars.update(
  '550e8400-e29b-41d4-a716-446655440000',
  { name: 'Updated Avatar Name' }
);
console.log(avatar);

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"personality": "string",
"startScript": "string",
"voice": {"type": "runway-live-preset",
"presetId": "victoria",
"name": "string",
"description": "string"
},
"referenceImageUri": "string",
"processedImageUri": "string",
"documentIds": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"
],
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"status": "AvatarProcessing"
}

Delete avatar

DELETE/v1/avatars/{id}

Delete an avatar.

Authentication

Authorization: Use the HTTP Authorization header with the Bearer scheme along with an API key.

Path parameters

idRequiredstring <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{...

Headers

X-Runway-VersionRequiredstring: The version of the RunwayML API being used. You can read more about versioning here.

This field must be set to the exact value 2024-11-06.

Responses

// npm install --save @runwayml/sdk
import RunwayML from '@runwayml/sdk';

// The env var RUNWAYML_API_SECRET is expected to contain your API key.
const client = new RunwayML();

await client.avatars.delete('550e8400-e29b-41d4-a716-446655440000');

Knowledge

Create document

POST/v1/documents

Create a new knowledge document. Documents can be attached to avatars to provide additional context during conversations.

Authentication

Authorization: Use the HTTP Authorization header with the Bearer scheme along with an API key.

Headers

X-Runway-VersionRequiredstring: The version of the RunwayML API being used. You can read more about versioning here.

This field must be set to the exact value 2024-11-06.

Request body

nameRequiredstring[ 1 .. 255 ] characters: A descriptive name for the document.
contentRequiredstring[ 1 .. 200000 ] characters: The markdown or plain text content of the document.

Responses

// npm install --save @runwayml/sdk
import RunwayML from '@runwayml/sdk';

// The env var RUNWAYML_API_SECRET is expected to contain your API key.
const client = new RunwayML();

const document = await client.documents.create({
  name: 'Product FAQ',
  content: '# Product FAQ\n\n## What is your return policy?\n...',
});
console.log(document);

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"type": "text",
"usedBy": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"imageUrl": "http://example.com"
}
],
"content": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

List documents

GET/v1/documents

List knowledge documents for the authenticated user with cursor-based pagination.

Authentication

Authorization: Use the HTTP Authorization header with the Bearer scheme along with an API key.

Query parameters

limitRequiredinteger[ 1 .. 100 ]: Default:50

The maximum number of items to return per page.
cursorstring[ 1 .. 1000 ] characters: Cursor from a previous response for fetching the next page of results.

Headers

X-Runway-VersionRequiredstring: The version of the RunwayML API being used. You can read more about versioning here.

This field must be set to the exact value 2024-11-06.

Responses

// npm install --save @runwayml/sdk
import RunwayML from '@runwayml/sdk';

// The env var RUNWAYML_API_SECRET is expected to contain your API key.
const client = new RunwayML();

const documents = await client.documents.list();
for await (const document of documents) {
  console.log(document);
}

{"data": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"type": "text",
"usedBy": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"imageUrl": "http://example.com"
}
],
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
],
"hasMore": true,
"nextCursor": "string"
}

Get document

GET/v1/documents/{id}

Get details of a specific knowledge document.

Authentication

Authorization: Use the HTTP Authorization header with the Bearer scheme along with an API key.

Path parameters

idRequiredstring <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{...: The document ID.

Headers

X-Runway-VersionRequiredstring: The version of the RunwayML API being used. You can read more about versioning here.

This field must be set to the exact value 2024-11-06.

Responses

// npm install --save @runwayml/sdk
import RunwayML from '@runwayml/sdk';

// The env var RUNWAYML_API_SECRET is expected to contain your API key.
const client = new RunwayML();

const document = await client.documents.retrieve(
  '550e8400-e29b-41d4-a716-446655440000'
);
console.log(document);

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"type": "text",
"usedBy": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"imageUrl": "http://example.com"
}
],
"content": "string",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}

Update document

PATCH/v1/documents/{id}

Update a knowledge document. At least one of name or content must be provided.

Authentication

Authorization: Use the HTTP Authorization header with the Bearer scheme along with an API key.

Path parameters

idRequiredstring <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{...: The document ID.

Headers

X-Runway-VersionRequiredstring: The version of the RunwayML API being used. You can read more about versioning here.

This field must be set to the exact value 2024-11-06.

Request body

namestring[ 1 .. 255 ] characters: A new name for the document.
contentstring[ 1 .. 200000 ] characters: New markdown or plain text content for the document.

Responses

// npm install --save @runwayml/sdk
import RunwayML from '@runwayml/sdk';

// The env var RUNWAYML_API_SECRET is expected to contain your API key.
const client = new RunwayML();

await client.documents.update(
  '550e8400-e29b-41d4-a716-446655440000',
  { name: 'Updated Product FAQ' }
);

Delete document

DELETE/v1/documents/{id}

Delete a knowledge document. This also removes it from all avatars it was attached to.

Authentication

Authorization: Use the HTTP Authorization header with the Bearer scheme along with an API key.

Path parameters

idRequiredstring <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{...: The document ID.

Headers

X-Runway-VersionRequiredstring: The version of the RunwayML API being used. You can read more about versioning here.

This field must be set to the exact value 2024-11-06.

Responses

// npm install --save @runwayml/sdk
import RunwayML from '@runwayml/sdk';

// The env var RUNWAYML_API_SECRET is expected to contain your API key.
const client = new RunwayML();

await client.documents.delete('550e8400-e29b-41d4-a716-446655440000');

Realtime Sessions

Create realtime session

POST/v1/realtime_sessions

Create a new realtime session with the specified model configuration.

Authentication

Authorization: Use the HTTP Authorization header with the Bearer scheme along with an API key.

Headers

X-Runway-VersionRequiredstring: The version of the RunwayML API being used. You can read more about versioning here.

This field must be set to the exact value 2024-11-06.

Request body

modelRequiredstring

The realtime session model type.

This field must be set to the exact value gwm1_avatars.

avatarRequiredRunwayPresetAvatar (object) or CustomAvatar (object)

The avatar configuration for the session.

One of the following shapes:

RunwayPresetAvatarobject

A preset avatar from Runway.

typeRequiredstring: This field must be set to the exact value runway-preset.
presetIdRequiredstring: Accepted values:"game-character", "music-superstar", "game-character-man", "cat-character", "influencer", "tennis-coach", "human-resource", "fashion-designer", "cooking-teacher"

ID of a preset avatar.

CustomAvatarobject

A user-created avatar.

typeRequiredstring: This field must be set to the exact value custom.
avatarIdRequiredstring <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{...: ID of a user-created avatar.

maxDurationinteger[ 10 .. 300 ]

Default:300

Maximum session duration in seconds.

personalitystring[ 1 .. 2000 ] characters

Override the avatar personality for this session. If not provided, uses the avatar default.

startScriptstring[ 1 .. 2000 ] characters

Override the avatar start script for this session. If not provided, uses the avatar default.

Responses

// npm install --save @runwayml/sdk
import RunwayML from '@runwayml/sdk';

// The env var RUNWAYML_API_SECRET is expected to contain your API key.
const client = new RunwayML();

const session = await client.realtimeSessions.create({
  model: 'gwm1_avatars',
  avatar: {
    type: 'custom',
    avatarId: '550e8400-e29b-41d4-a716-446655440000',
  },
});
console.log(session.id);

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Get realtime session

GET/v1/realtime_sessions/{id}

Get the status of a realtime session.

Authentication

Authorization: Use the HTTP Authorization header with the Bearer scheme along with an API key.

Path parameters

idRequiredstring <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{...: The realtime session ID.

Headers

X-Runway-VersionRequiredstring: The version of the RunwayML API being used. You can read more about versioning here.

This field must be set to the exact value 2024-11-06.

Responses

// npm install --save @runwayml/sdk
import RunwayML from '@runwayml/sdk';

// The env var RUNWAYML_API_SECRET is expected to contain your API key.
const client = new RunwayML();

const session = await client.realtimeSessions.retrieve(
  '550e8400-e29b-41d4-a716-446655440000'
);
console.log(session.status);

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"createdAt": "2019-08-24T14:15:22Z",
"status": "SessionNotReady",
"queued": true
}

Cancel realtime session

DELETE/v1/realtime_sessions/{id}

Cancel an active realtime session.

Authentication

Authorization: Use the HTTP Authorization header with the Bearer scheme along with an API key.

Path parameters

idRequiredstring <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{...: The realtime session ID.

Headers

X-Runway-VersionRequiredstring: The version of the RunwayML API being used. You can read more about versioning here.

This field must be set to the exact value 2024-11-06.

Responses

// npm install --save @runwayml/sdk
import RunwayML from '@runwayml/sdk';

// The env var RUNWAYML_API_SECRET is expected to contain your API key.
const client = new RunwayML();

await client.realtimeSessions.delete(
  '550e8400-e29b-41d4-a716-446655440000'
);

Organization

Get organization information

GET/v1/organization

Get usage tier and credit balance information about the organization associated with the API key used to make the request.

Authentication

Authorization: Use the HTTP Authorization header with the Bearer scheme along with an API key.

Headers

X-Runway-VersionRequiredstring: The version of the RunwayML API being used. You can read more about versioning here.

This field must be set to the exact value 2024-11-06.

Responses

// npm install --save @runwayml/sdk
import RunwayML from '@runwayml/sdk';

// The env var RUNWAYML_API_SECRET is expected to contain your API key.
const client = new RunwayML();

const details = await client.organization.retrieve();
console.log(details.creditBalance);

{"tier": {"maxMonthlyCreditSpend": 9007199254740991,
"models": {"property1": {"maxConcurrentGenerations": 9007199254740991,
"maxDailyGenerations": 9007199254740991
},
"property2": {"maxConcurrentGenerations": 9007199254740991,
"maxDailyGenerations": 9007199254740991
}
}
},
"creditBalance": 9007199254740991,
"usage": {"models": {"property1": {"dailyGenerations": 9007199254740991
},
"property2": {"dailyGenerations": 9007199254740991
}
}
}
}

Query credit usage

POST/v1/organization/usage

Fetch credit usage data broken down by model and day for the organization associated with the API key used to make the request. Up to 90 days of data can be queried at a time.

Authentication

Authorization: Use the HTTP Authorization header with the Bearer scheme along with an API key.

Headers

X-Runway-VersionRequiredstring: The version of the RunwayML API being used. You can read more about versioning here.

This field must be set to the exact value 2024-11-06.

Request body

startDatestring <date> ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[...: The start date of the usage data in ISO-8601 format (YYYY-MM-DD). If unspecified, it will default to 30 days before the current date. All dates are in UTC.
beforeDatestring <date> ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[...: The end date of the usage data in ISO-8601 format (YYYY-MM-DD), not inclusive. If unspecified, it will default to thirty days after the start date. Must be less than or equal to 90 days after the start date. All dates are in UTC.

Responses

// npm install --save @runwayml/sdk
import RunwayML from '@runwayml/sdk';

// The env var RUNWAYML_API_SECRET is expected to contain your API key.
const client = new RunwayML();

const usage = await client.organization.retrieveUsage();
console.log(usage);

{"results": [{"date": "2019-08-24",
"usedCredits": [{"model": "gen4.5",
"amount": 9007199254740991
}
]
}
],
"models": ["gen4.5"
]
}

Voices

List voices

GET/v1/voices

List custom voices for the authenticated organization with cursor-based pagination.

Authentication

Authorization: Use the HTTP Authorization header with the Bearer scheme along with an API key.

Query parameters

limitRequiredinteger[ 1 .. 100 ]: Default:50

The maximum number of items to return per page.
cursorstring[ 1 .. 1000 ] characters: Cursor from a previous response for fetching the next page of results.

Headers

X-Runway-VersionRequiredstring: The version of the RunwayML API being used. You can read more about versioning here.

This field must be set to the exact value 2024-11-06.

Responses

// npm install --save @runwayml/sdk
import RunwayML from '@runwayml/sdk';

// The env var RUNWAYML_API_SECRET is expected to contain your API key.
const client = new RunwayML();

const voices = await client.voices.list();

for await (const voice of voices) {
  console.log(voice);
}

{"data": [{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"description": "string",
"createdAt": "2019-08-24T14:15:22Z",
"status": "PROCESSING"
}
],
"hasMore": true,
"nextCursor": "string"
}

Create a voice

POST/v1/voices

Create a custom voice from a text description.

Authentication

Authorization: Use the HTTP Authorization header with the Bearer scheme along with an API key.

Headers

X-Runway-VersionRequiredstring: The version of the RunwayML API being used. You can read more about versioning here.

This field must be set to the exact value 2024-11-06.

Request body

nameRequiredstring[ 1 .. 100 ] characters

A name for the voice.

fromRequiredobject

The source configuration for creating the voice.

typeRequiredstring: This field must be set to the exact value text.
promptRequiredstring[ 20 .. 1000 ] characters: A text description of the desired voice characteristics. Must be at least 20 characters.
modelRequiredstring: Accepted values:"eleven_multilingual_ttv_v2", "eleven_ttv_v3"

The voice design model to use.

descriptionstring or null

An optional description of the voice.

One of the following shapes:

string[ 1 .. 512 ] characters

An optional description of the voice.

null

An optional description of the voice.

Responses

// npm install --save @runwayml/sdk
import RunwayML from '@runwayml/sdk';

// The env var RUNWAYML_API_SECRET is expected to contain your API key.
const client = new RunwayML();

const voice = await client.voices.create({
  name: 'My Custom Voice',
  from: {
    type: 'text',
    prompt: 'A warm, friendly voice with a slight British accent',
    model: 'eleven_multilingual_ttv_v2',
  },
});
console.log(voice.id);

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}

Get a voice

GET/v1/voices/{id}

Get details about a specific custom voice.

Authentication

Authorization: Use the HTTP Authorization header with the Bearer scheme along with an API key.

Path parameters

idRequiredstring <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{...: The ID of the voice to retrieve.

Headers

X-Runway-VersionRequiredstring: The version of the RunwayML API being used. You can read more about versioning here.

This field must be set to the exact value 2024-11-06.

Responses

// npm install --save @runwayml/sdk
import RunwayML from '@runwayml/sdk';

// The env var RUNWAYML_API_SECRET is expected to contain your API key.
const client = new RunwayML();

const voice = await client.voices.retrieve('550e8400-e29b-41d4-a716-446655440000');
console.log(voice);

{"id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
"name": "string",
"description": "string",
"createdAt": "2019-08-24T14:15:22Z",
"status": "VoiceProcessing"
}

Delete a voice

DELETE/v1/voices/{id}

Delete a custom voice.

Authentication

Authorization: Use the HTTP Authorization header with the Bearer scheme along with an API key.

Path parameters

idRequiredstring <uuid> ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{...: The ID of the voice to delete.

Headers

X-Runway-VersionRequiredstring: The version of the RunwayML API being used. You can read more about versioning here.

This field must be set to the exact value 2024-11-06.

Responses

// npm install --save @runwayml/sdk
import RunwayML from '@runwayml/sdk';

// The env var RUNWAYML_API_SECRET is expected to contain your API key.
const client = new RunwayML();

await client.voices.delete('550e8400-e29b-41d4-a716-446655440000');

Preview a voice

POST/v1/voices/preview

Generate a short audio preview of a voice from a text description. Use this to audition a voice before creating it.

Authentication

Authorization: Use the HTTP Authorization header with the Bearer scheme along with an API key.

Headers

X-Runway-VersionRequiredstring: The version of the RunwayML API being used. You can read more about versioning here.

This field must be set to the exact value 2024-11-06.

Request body

promptRequiredstring[ 20 .. 1000 ] characters: A text description of the desired voice characteristics. Must be at least 20 characters.
modelRequiredstring: Accepted values:"eleven_multilingual_ttv_v2", "eleven_ttv_v3"

The voice design model to use.

Responses

// npm install --save @runwayml/sdk
import RunwayML from '@runwayml/sdk';

// The env var RUNWAYML_API_SECRET is expected to contain your API key.
const client = new RunwayML();

const preview = await client.voices.preview({
  prompt: 'A warm, friendly voice with a slight British accent',
  model: 'eleven_multilingual_ttv_v2',
});
console.log(preview.url, preview.durationSecs);

{"url": "http://example.com",
"durationSecs": 0
}