{ "openapi": "3.1.0", "info": { "title": "RunwayML API", "version": "2024-11-06", "description": "The API makes generative AI models available, at the same credits prices listed here ($0.01 per credit): https://help.runwayml.com/hc/en-us/articles/15124877443219-How-do-credits-work" }, "paths": { "/v1/avatars": { "get": { "tags": ["Avatars"], "summary": "List avatars", "description": "List avatars for the authenticated user with cursor-based pagination.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nconst avatars = await client.avatars.list();\nfor await (const avatar of avatars) {\n console.log(avatar);\n}" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\nfor avatar in client.avatars.list():\n print(avatar)" } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1000 }, "description": "Cursor from a previous response for fetching the next page of results." }, { "name": "limit", "in": "query", "required": true, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "The maximum number of items to return per page." }, { "$ref": "#/components/parameters/X-Runway-Version" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "The list of items for the current page.", "type": "array", "items": { "oneOf": [ { "title": "AvatarProcessing", "description": "An avatar that is still being processed.", "type": "object", "properties": { "id": { "description": "The unique identifier of the avatar.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "name": { "description": "The character name for the avatar.", "type": "string" }, "personality": { "description": "System prompt defining how the avatar should behave in conversations.", "type": "string" }, "startScript": { "description": "Opening message that the avatar will say when a session starts, or null if not set.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "voice": { "description": "The voice configured for this avatar.", "oneOf": [ { "title": "RunwayLivePresetVoiceResponse", "description": "A preset voice from the Runway API.", "type": "object", "properties": { "type": { "type": "string", "const": "runway-live-preset" }, "presetId": { "description": "The preset voice identifier.", "type": "string", "enum": [ "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" ] }, "name": { "description": "The display name of the voice.", "type": "string" }, "description": { "description": "A brief description of the voice characteristics.", "type": "string" } }, "required": [ "type", "presetId", "name", "description" ], "additionalProperties": false }, { "title": "CustomVoiceResponse", "description": "A custom voice created via the Voices API.", "type": "object", "properties": { "type": { "type": "string", "const": "custom" }, "id": { "description": "The unique identifier of the custom voice.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "deleted": { "description": "Whether the voice has been deleted. When true, name and description are omitted.", "type": "boolean" }, "name": { "description": "The display name of the voice.", "type": "string" }, "description": { "description": "A brief description of the voice characteristics.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["type", "id", "deleted"], "additionalProperties": false } ], "discriminator": { "propertyName": "type" } }, "referenceImageUri": { "description": "A URI pointing to a low-resolution preview of the avatar's reference image.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "processedImageUri": { "description": "A URI pointing to a low-resolution preview of the processed reference image.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "documentIds": { "description": "IDs of knowledge documents attached to this avatar.", "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" } }, "createdAt": { "description": "When the avatar was created.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "updatedAt": { "description": "When the avatar was last updated.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "status": { "type": "string", "const": "PROCESSING" } }, "required": [ "id", "name", "personality", "startScript", "voice", "referenceImageUri", "processedImageUri", "documentIds", "createdAt", "updatedAt", "status" ], "additionalProperties": false }, { "title": "AvatarReady", "description": "An avatar that is ready for use in sessions.", "type": "object", "properties": { "id": { "description": "The unique identifier of the avatar.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "name": { "description": "The character name for the avatar.", "type": "string" }, "personality": { "description": "System prompt defining how the avatar should behave in conversations.", "type": "string" }, "startScript": { "description": "Opening message that the avatar will say when a session starts, or null if not set.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "voice": { "description": "The voice configured for this avatar.", "oneOf": [ { "title": "RunwayLivePresetVoiceResponse", "description": "A preset voice from the Runway API.", "type": "object", "properties": { "type": { "type": "string", "const": "runway-live-preset" }, "presetId": { "description": "The preset voice identifier.", "type": "string", "enum": [ "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" ] }, "name": { "description": "The display name of the voice.", "type": "string" }, "description": { "description": "A brief description of the voice characteristics.", "type": "string" } }, "required": [ "type", "presetId", "name", "description" ], "additionalProperties": false }, { "title": "CustomVoiceResponse", "description": "A custom voice created via the Voices API.", "type": "object", "properties": { "type": { "type": "string", "const": "custom" }, "id": { "description": "The unique identifier of the custom voice.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "deleted": { "description": "Whether the voice has been deleted. When true, name and description are omitted.", "type": "boolean" }, "name": { "description": "The display name of the voice.", "type": "string" }, "description": { "description": "A brief description of the voice characteristics.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["type", "id", "deleted"], "additionalProperties": false } ], "discriminator": { "propertyName": "type" } }, "referenceImageUri": { "description": "A URI pointing to a low-resolution preview of the avatar's reference image.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "processedImageUri": { "description": "A URI pointing to a low-resolution preview of the processed reference image.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "documentIds": { "description": "IDs of knowledge documents attached to this avatar.", "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" } }, "createdAt": { "description": "When the avatar was created.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "updatedAt": { "description": "When the avatar was last updated.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "status": { "type": "string", "const": "READY" } }, "required": [ "id", "name", "personality", "startScript", "voice", "referenceImageUri", "processedImageUri", "documentIds", "createdAt", "updatedAt", "status" ], "additionalProperties": false }, { "title": "AvatarFailed", "description": "An avatar that failed to finish processing.", "type": "object", "properties": { "id": { "description": "The unique identifier of the avatar.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "name": { "description": "The character name for the avatar.", "type": "string" }, "personality": { "description": "System prompt defining how the avatar should behave in conversations.", "type": "string" }, "startScript": { "description": "Opening message that the avatar will say when a session starts, or null if not set.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "voice": { "description": "The voice configured for this avatar.", "oneOf": [ { "title": "RunwayLivePresetVoiceResponse", "description": "A preset voice from the Runway API.", "type": "object", "properties": { "type": { "type": "string", "const": "runway-live-preset" }, "presetId": { "description": "The preset voice identifier.", "type": "string", "enum": [ "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" ] }, "name": { "description": "The display name of the voice.", "type": "string" }, "description": { "description": "A brief description of the voice characteristics.", "type": "string" } }, "required": [ "type", "presetId", "name", "description" ], "additionalProperties": false }, { "title": "CustomVoiceResponse", "description": "A custom voice created via the Voices API.", "type": "object", "properties": { "type": { "type": "string", "const": "custom" }, "id": { "description": "The unique identifier of the custom voice.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "deleted": { "description": "Whether the voice has been deleted. When true, name and description are omitted.", "type": "boolean" }, "name": { "description": "The display name of the voice.", "type": "string" }, "description": { "description": "A brief description of the voice characteristics.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["type", "id", "deleted"], "additionalProperties": false } ], "discriminator": { "propertyName": "type" } }, "referenceImageUri": { "description": "A URI pointing to a low-resolution preview of the avatar's reference image.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "processedImageUri": { "description": "A URI pointing to a low-resolution preview of the processed reference image.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "documentIds": { "description": "IDs of knowledge documents attached to this avatar.", "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" } }, "createdAt": { "description": "When the avatar was created.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "updatedAt": { "description": "When the avatar was last updated.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "status": { "type": "string", "const": "FAILED" }, "failureReason": { "description": "A human-readable error message. This value is not stable and should not be matched against programmatically.", "type": "string" } }, "required": [ "id", "name", "personality", "startScript", "voice", "referenceImageUri", "processedImageUri", "documentIds", "createdAt", "updatedAt", "status", "failureReason" ], "additionalProperties": false } ], "discriminator": { "propertyName": "status" } } }, "hasMore": { "description": "Whether there are more items available after this page.", "type": "boolean" }, "nextCursor": { "description": "Cursor to use for fetching the next page, or null if there are no more pages.", "anyOf": [{ "type": "string" }, { "type": "null" }] } }, "required": ["data", "hasMore", "nextCursor"], "additionalProperties": false } } } } } }, "post": { "tags": ["Avatars"], "summary": "Create avatar", "description": "Create a new avatar with a reference image and voice.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nconst avatar = await client.avatars.create({\n name: 'Customer Support Agent',\n referenceImage: 'https://example.com/reference.jpg',\n personality: 'You are a helpful customer support agent. Be friendly and concise.',\n voice: { type: 'runway-live-preset', presetId: 'adrian' },\n});\nconsole.log(avatar);" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\navatar = client.avatars.create(\n name='Customer Support Agent',\n reference_image='https://example.com/reference.jpg',\n personality='You are a helpful customer support agent. Be friendly and concise.',\n voice={ 'type': 'runway-live-preset', 'preset_id': 'adrian' },\n)\nprint(avatar)" } ], "parameters": [{ "$ref": "#/components/parameters/X-Runway-Version" }], "requestBody": { "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "description": "The character name for the avatar.", "type": "string", "minLength": 1, "maxLength": 50 }, "referenceImage": { "description": "A HTTPS URL, Runway URI, or data URI containing the avatar reference image. See [our docs](/assets/inputs#images) for supported formats.", "example": "https://example.com/reference.jpg", "anyOf": [ { "description": "A HTTPS URL.", "example": "https://example.com/file", "type": "string", "minLength": 13, "maxLength": 2048, "pattern": "^https:\\/\\/.*" }, { "description": "A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.", "example": "runway://", "type": "string", "minLength": 13, "maxLength": 5000, "pattern": "^runway:\\/\\/.*" }, { "description": "A data URI containing encoded media.", "example": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "type": "string", "minLength": 13, "maxLength": 5242880, "pattern": "^data:image\\/.*" } ] }, "personality": { "description": "System prompt defining how the avatar should behave in conversations.", "example": "You are a helpful support agent assisting users with their account questions. Be friendly, patient, and provide clear step-by-step guidance.", "type": "string", "minLength": 1, "maxLength": 10000 }, "startScript": { "description": "Optional opening message that the avatar will say when a session starts.", "example": "Hello! How can I help you today?", "type": "string", "maxLength": 2000 }, "voice": { "description": "The voice configuration for the avatar.", "example": { "type": "runway-live-preset", "presetId": "adrian" }, "oneOf": [ { "title": "RunwayLivePresetVoice", "description": "A preset voice from the Runway API.", "type": "object", "properties": { "type": { "type": "string", "const": "runway-live-preset" }, "presetId": { "description": "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).", "type": "string", "enum": [ "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" ] } }, "required": ["type", "presetId"] }, { "title": "CustomVoice", "description": "A custom voice created via the Voices API.", "type": "object", "properties": { "type": { "type": "string", "const": "custom" }, "id": { "description": "The ID of a custom voice created via the Voices API.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" } }, "required": ["type", "id"] } ], "discriminator": { "propertyName": "type" } }, "documentIds": { "description": "Optional list of knowledge document IDs to attach to this avatar. Documents provide additional context during conversations.", "maxItems": 50, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" } }, "imageProcessing": { "description": "Controls image preprocessing. `optimize` improves the image for better avatar results. `none` uses the image as-is; quality not guaranteed.", "default": "optimize", "type": "string", "enum": ["optimize", "none"] } }, "required": ["name", "referenceImage", "personality", "voice"] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "oneOf": [ { "title": "AvatarProcessing", "description": "An avatar that is still being processed.", "type": "object", "properties": { "id": { "description": "The unique identifier of the avatar.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "name": { "description": "The character name for the avatar.", "type": "string" }, "personality": { "description": "System prompt defining how the avatar should behave in conversations.", "type": "string" }, "startScript": { "description": "Opening message that the avatar will say when a session starts, or null if not set.", "anyOf": [{ "type": "string" }, { "type": "null" }] }, "voice": { "description": "The voice configured for this avatar.", "oneOf": [ { "title": "RunwayLivePresetVoiceResponse", "description": "A preset voice from the Runway API.", "type": "object", "properties": { "type": { "type": "string", "const": "runway-live-preset" }, "presetId": { "description": "The preset voice identifier.", "type": "string", "enum": [ "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" ] }, "name": { "description": "The display name of the voice.", "type": "string" }, "description": { "description": "A brief description of the voice characteristics.", "type": "string" } }, "required": [ "type", "presetId", "name", "description" ], "additionalProperties": false }, { "title": "CustomVoiceResponse", "description": "A custom voice created via the Voices API.", "type": "object", "properties": { "type": { "type": "string", "const": "custom" }, "id": { "description": "The unique identifier of the custom voice.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "deleted": { "description": "Whether the voice has been deleted. When true, name and description are omitted.", "type": "boolean" }, "name": { "description": "The display name of the voice.", "type": "string" }, "description": { "description": "A brief description of the voice characteristics.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["type", "id", "deleted"], "additionalProperties": false } ], "discriminator": { "propertyName": "type" } }, "referenceImageUri": { "description": "A URI pointing to a low-resolution preview of the avatar's reference image.", "anyOf": [{ "type": "string" }, { "type": "null" }] }, "processedImageUri": { "description": "A URI pointing to a low-resolution preview of the processed reference image.", "anyOf": [{ "type": "string" }, { "type": "null" }] }, "documentIds": { "description": "IDs of knowledge documents attached to this avatar.", "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" } }, "createdAt": { "description": "When the avatar was created.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "updatedAt": { "description": "When the avatar was last updated.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "status": { "type": "string", "const": "PROCESSING" } }, "required": [ "id", "name", "personality", "startScript", "voice", "referenceImageUri", "processedImageUri", "documentIds", "createdAt", "updatedAt", "status" ], "additionalProperties": false }, { "title": "AvatarReady", "description": "An avatar that is ready for use in sessions.", "type": "object", "properties": { "id": { "description": "The unique identifier of the avatar.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "name": { "description": "The character name for the avatar.", "type": "string" }, "personality": { "description": "System prompt defining how the avatar should behave in conversations.", "type": "string" }, "startScript": { "description": "Opening message that the avatar will say when a session starts, or null if not set.", "anyOf": [{ "type": "string" }, { "type": "null" }] }, "voice": { "description": "The voice configured for this avatar.", "oneOf": [ { "title": "RunwayLivePresetVoiceResponse", "description": "A preset voice from the Runway API.", "type": "object", "properties": { "type": { "type": "string", "const": "runway-live-preset" }, "presetId": { "description": "The preset voice identifier.", "type": "string", "enum": [ "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" ] }, "name": { "description": "The display name of the voice.", "type": "string" }, "description": { "description": "A brief description of the voice characteristics.", "type": "string" } }, "required": [ "type", "presetId", "name", "description" ], "additionalProperties": false }, { "title": "CustomVoiceResponse", "description": "A custom voice created via the Voices API.", "type": "object", "properties": { "type": { "type": "string", "const": "custom" }, "id": { "description": "The unique identifier of the custom voice.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "deleted": { "description": "Whether the voice has been deleted. When true, name and description are omitted.", "type": "boolean" }, "name": { "description": "The display name of the voice.", "type": "string" }, "description": { "description": "A brief description of the voice characteristics.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["type", "id", "deleted"], "additionalProperties": false } ], "discriminator": { "propertyName": "type" } }, "referenceImageUri": { "description": "A URI pointing to a low-resolution preview of the avatar's reference image.", "anyOf": [{ "type": "string" }, { "type": "null" }] }, "processedImageUri": { "description": "A URI pointing to a low-resolution preview of the processed reference image.", "anyOf": [{ "type": "string" }, { "type": "null" }] }, "documentIds": { "description": "IDs of knowledge documents attached to this avatar.", "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" } }, "createdAt": { "description": "When the avatar was created.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "updatedAt": { "description": "When the avatar was last updated.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "status": { "type": "string", "const": "READY" } }, "required": [ "id", "name", "personality", "startScript", "voice", "referenceImageUri", "processedImageUri", "documentIds", "createdAt", "updatedAt", "status" ], "additionalProperties": false }, { "title": "AvatarFailed", "description": "An avatar that failed to finish processing.", "type": "object", "properties": { "id": { "description": "The unique identifier of the avatar.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "name": { "description": "The character name for the avatar.", "type": "string" }, "personality": { "description": "System prompt defining how the avatar should behave in conversations.", "type": "string" }, "startScript": { "description": "Opening message that the avatar will say when a session starts, or null if not set.", "anyOf": [{ "type": "string" }, { "type": "null" }] }, "voice": { "description": "The voice configured for this avatar.", "oneOf": [ { "title": "RunwayLivePresetVoiceResponse", "description": "A preset voice from the Runway API.", "type": "object", "properties": { "type": { "type": "string", "const": "runway-live-preset" }, "presetId": { "description": "The preset voice identifier.", "type": "string", "enum": [ "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" ] }, "name": { "description": "The display name of the voice.", "type": "string" }, "description": { "description": "A brief description of the voice characteristics.", "type": "string" } }, "required": [ "type", "presetId", "name", "description" ], "additionalProperties": false }, { "title": "CustomVoiceResponse", "description": "A custom voice created via the Voices API.", "type": "object", "properties": { "type": { "type": "string", "const": "custom" }, "id": { "description": "The unique identifier of the custom voice.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "deleted": { "description": "Whether the voice has been deleted. When true, name and description are omitted.", "type": "boolean" }, "name": { "description": "The display name of the voice.", "type": "string" }, "description": { "description": "A brief description of the voice characteristics.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["type", "id", "deleted"], "additionalProperties": false } ], "discriminator": { "propertyName": "type" } }, "referenceImageUri": { "description": "A URI pointing to a low-resolution preview of the avatar's reference image.", "anyOf": [{ "type": "string" }, { "type": "null" }] }, "processedImageUri": { "description": "A URI pointing to a low-resolution preview of the processed reference image.", "anyOf": [{ "type": "string" }, { "type": "null" }] }, "documentIds": { "description": "IDs of knowledge documents attached to this avatar.", "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" } }, "createdAt": { "description": "When the avatar was created.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "updatedAt": { "description": "When the avatar was last updated.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "status": { "type": "string", "const": "FAILED" }, "failureReason": { "description": "A human-readable error message. This value is not stable and should not be matched against programmatically.", "type": "string" } }, "required": [ "id", "name", "personality", "startScript", "voice", "referenceImageUri", "processedImageUri", "documentIds", "createdAt", "updatedAt", "status", "failureReason" ], "additionalProperties": false } ], "discriminator": { "propertyName": "status" } } } } } } } }, "/v1/avatar_conversations": { "get": { "tags": ["Avatars"], "summary": "List conversations", "description": "List realtime avatar conversations for the authenticated user with cursor-based pagination. Each conversation corresponds to a realtime session, and the conversation ID matches the realtime session ID. Pass `avatar` to restrict results to a single avatar.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nfor await (const conversation of client.avatarConversations.list()) {\n console.log(conversation.name, conversation.avatar?.name, conversation.status);\n}" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\nfor conversation in client.avatar_conversations.list():\n avatar_name = conversation.avatar.name if conversation.avatar else None\n print(conversation.name, avatar_name, conversation.status)" } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1000 }, "description": "Cursor from a previous response for fetching the next page of results." }, { "name": "limit", "in": "query", "required": true, "schema": { "default": 20, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "The maximum number of items to return per page." }, { "name": "avatar", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "description": "Filter to conversations that used the given custom avatar." }, { "name": "startDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "description": "Filter conversations created on or after this timestamp (inclusive)." }, { "name": "endDate", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "description": "Filter conversations created before this timestamp (exclusive)." }, { "$ref": "#/components/parameters/X-Runway-Version" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "Array of conversation summaries.", "type": "array", "items": { "title": "ConversationListItem", "description": "Summary of a conversation for list responses.", "type": "object", "properties": { "id": { "description": "Unique conversation identifier. This is the same value as the realtime session ID for the call.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "name": { "description": "Conversation name (auto-generated or user-provided).", "type": "string" }, "status": { "description": "The status of the conversation. `in_progress` means the session is active, `ended` means it completed successfully, `failed` means it ended due to an error.", "type": "string", "enum": ["in_progress", "ended", "failed"] }, "avatar": { "description": "The avatar used in this conversation, or null if unavailable.", "anyOf": [ { "description": "The avatar used in this conversation.", "oneOf": [ { "title": "PresetAvatarSummary", "description": "A preset avatar.", "type": "object", "properties": { "type": { "type": "string", "const": "runway-preset" }, "presetId": { "description": "The preset avatar ID.", "type": "string" }, "name": { "description": "The preset avatar's display name (e.g. \"Mina\").", "type": "string" } }, "required": ["type", "presetId", "name"], "additionalProperties": false }, { "title": "CustomAvatarSummary", "description": "A custom avatar created by the user.", "type": "object", "properties": { "type": { "type": "string", "const": "custom" }, "id": { "description": "The custom avatar ID, or null if deleted.", "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "name": { "description": "The avatar's configured name, or null if unavailable.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["type", "id", "name"], "additionalProperties": false } ], "discriminator": { "propertyName": "type" } }, { "type": "null" } ] }, "createdAt": { "description": "When the conversation was created.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "duration": { "description": "Duration of the conversation in seconds, or null if not started.", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hasTools": { "description": "Whether tools were configured for this conversation session.", "type": "boolean" } }, "required": [ "id", "name", "status", "avatar", "createdAt", "duration", "hasTools" ], "additionalProperties": false } }, "hasMore": { "description": "Whether there are more conversations to fetch.", "type": "boolean" }, "nextCursor": { "description": "Cursor to use for fetching the next page, or null if no more pages.", "anyOf": [{ "type": "string" }, { "type": "null" }] } }, "required": ["data", "hasMore", "nextCursor"], "additionalProperties": false } } } } } } }, "/v1/avatar_usage": { "get": { "tags": ["Avatars"], "summary": "Get avatar usage", "description": "Get aggregate usage statistics for avatar conversations, including total duration, session counts, average duration, and a per-day breakdown. Per-day buckets are keyed by UTC calendar date. The date range must not exceed 90 days.", "parameters": [ { "name": "startDate", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "description": "Start of the date range in UTC (inclusive). Required." }, { "name": "endDate", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "description": "End of the date range in UTC (exclusive). Required." }, { "$ref": "#/components/parameters/X-Runway-Version" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalSeconds": { "description": "Total seconds across conversations with a measured duration in the date range.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "totalSessions": { "description": "Number of conversations started in the date range. Includes unfinished and failed conversations.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "avgDurationSeconds": { "description": "Average duration in seconds across conversations with a measured duration, or 0 if none completed. May not equal `totalSeconds / totalSessions` because unfinished conversations contribute to the session count but not the duration.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "byDay": { "description": "Per-day usage across the date range. Days with no sessions are included with zeroes.", "type": "array", "items": { "type": "object", "properties": { "date": { "description": "The UTC calendar date (YYYY-MM-DD).", "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "sessions": { "description": "Number of conversations started on this date.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "seconds": { "description": "Total seconds of measured conversation duration on this date.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["date", "sessions", "seconds"], "additionalProperties": false } } }, "required": [ "totalSeconds", "totalSessions", "avgDurationSeconds", "byDay" ], "additionalProperties": false } } } } } } }, "/v1/avatar_conversations/{id}": { "get": { "tags": ["Avatars"], "summary": "Get conversation", "description": "Get detailed information about a specific conversation, including the transcript and recording download URL when available. The conversation ID is the same value returned when the realtime session was created.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nconst conversation = await client.avatarConversations.retrieve(\n '660e8400-e29b-41d4-a716-446655440001'\n);\nconsole.log(conversation.status, conversation.transcript);" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\nconversation = client.avatar_conversations.retrieve(\n id=\"660e8400-e29b-41d4-a716-446655440001\",\n)\nprint(conversation.status, conversation.transcript)" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "description": "The conversation ID. This is the same value as the realtime session ID for the call." }, { "$ref": "#/components/parameters/X-Runway-Version" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "oneOf": [ { "description": "A conversation that is currently active.", "type": "object", "properties": { "id": { "description": "Unique conversation identifier. This is the same value as the realtime session ID for the call.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "name": { "description": "Conversation name.", "type": "string" }, "avatar": { "description": "The avatar used in this conversation, or null if unavailable.", "anyOf": [ { "description": "The avatar used in this conversation.", "oneOf": [ { "title": "PresetAvatar", "description": "A preset avatar.", "type": "object", "properties": { "type": { "type": "string", "const": "runway-preset" }, "presetId": { "description": "The preset avatar ID.", "type": "string" } }, "required": ["type", "presetId"], "additionalProperties": false }, { "title": "CustomAvatar", "description": "A custom avatar created by the user.", "type": "object", "properties": { "type": { "type": "string", "const": "custom" }, "id": { "description": "The custom avatar ID, or null if deleted.", "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "name": { "description": "The avatar name, or null if unavailable.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "imageUrl": { "description": "URL to the avatar image, or null if unavailable.", "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, "required": [ "type", "id", "name", "imageUrl" ], "additionalProperties": false } ], "discriminator": { "propertyName": "type" } }, { "type": "null" } ] }, "createdAt": { "description": "When the conversation was created.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "maxDuration": { "description": "Maximum allowed duration in seconds, or null if not set.", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "transcript": { "description": "The conversation transcript.", "maxItems": 1000, "type": "array", "items": { "title": "TranscriptEntry", "description": "A single entry in the conversation transcript.", "type": "object", "properties": { "role": { "description": "Who produced this transcript entry.", "type": "string", "enum": ["user", "assistant"] }, "content": { "description": "The spoken text, or null for tool-only turns.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timestamp": { "description": "When this entry occurred, or null if unavailable.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "toolCalls": { "description": "Tool invocations made during this assistant turn. Only present on assistant entries.", "type": "array", "items": { "title": "ToolCall", "description": "A tool invocation by the assistant.", "type": "object", "properties": { "id": { "description": "Optional identifier linking this call to its result.", "type": "string" }, "name": { "description": "The name of the tool that was called.", "type": "string" }, "arguments": { "description": "The arguments passed to the tool.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": ["name", "arguments"], "additionalProperties": false } }, "toolResults": { "description": "Tool results received during this assistant turn. Only present on assistant entries.", "type": "array", "items": { "title": "ToolResult", "description": "The result of a tool invocation.", "type": "object", "properties": { "id": { "description": "Optional identifier linking this result to its call.", "type": "string" }, "name": { "description": "The name of the tool that returned a result.", "type": "string" }, "result": { "description": "The tool result (object, string, or null).", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "string" }, { "type": "null" } ] }, "error": { "description": "Error message if the tool call failed.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "durationMs": { "description": "How long the tool call took in milliseconds.", "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": ["name"], "additionalProperties": false } } }, "required": ["role", "content", "timestamp"], "additionalProperties": false } }, "recordingUrl": { "description": "A URL to download the conversation recording, or null if no recording is available. This URL will expire within 24-48 hours, fetch the conversation again to get a fresh download URL.", "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "tools": { "description": "The tools that were configured for this conversation session. Empty if no tools were used.", "type": "array", "items": { "title": "ConversationToolSummary", "description": "Summary of a tool configured for the session.", "type": "object", "properties": { "type": { "description": "The tool type.", "type": "string", "enum": ["client_event", "backend_rpc"] }, "name": { "description": "The tool name.", "type": "string" }, "description": { "description": "A description of when and how the tool should be used.", "type": "string" } }, "required": ["type", "name", "description"], "additionalProperties": false } }, "status": { "type": "string", "const": "in_progress" }, "startedAt": { "description": "When the conversation started, or null if not yet started.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "duration": { "description": "Elapsed duration in seconds, or null if not yet started.", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "name", "avatar", "createdAt", "maxDuration", "transcript", "recordingUrl", "tools", "status", "startedAt", "duration" ], "additionalProperties": false }, { "description": "A conversation that completed successfully.", "type": "object", "properties": { "id": { "description": "Unique conversation identifier. This is the same value as the realtime session ID for the call.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "name": { "description": "Conversation name.", "type": "string" }, "avatar": { "description": "The avatar used in this conversation, or null if unavailable.", "anyOf": [ { "description": "The avatar used in this conversation.", "oneOf": [ { "title": "PresetAvatar", "description": "A preset avatar.", "type": "object", "properties": { "type": { "type": "string", "const": "runway-preset" }, "presetId": { "description": "The preset avatar ID.", "type": "string" } }, "required": ["type", "presetId"], "additionalProperties": false }, { "title": "CustomAvatar", "description": "A custom avatar created by the user.", "type": "object", "properties": { "type": { "type": "string", "const": "custom" }, "id": { "description": "The custom avatar ID, or null if deleted.", "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "name": { "description": "The avatar name, or null if unavailable.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "imageUrl": { "description": "URL to the avatar image, or null if unavailable.", "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, "required": [ "type", "id", "name", "imageUrl" ], "additionalProperties": false } ], "discriminator": { "propertyName": "type" } }, { "type": "null" } ] }, "createdAt": { "description": "When the conversation was created.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "maxDuration": { "description": "Maximum allowed duration in seconds, or null if not set.", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "transcript": { "description": "The conversation transcript.", "maxItems": 1000, "type": "array", "items": { "title": "TranscriptEntry", "description": "A single entry in the conversation transcript.", "type": "object", "properties": { "role": { "description": "Who produced this transcript entry.", "type": "string", "enum": ["user", "assistant"] }, "content": { "description": "The spoken text, or null for tool-only turns.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timestamp": { "description": "When this entry occurred, or null if unavailable.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "toolCalls": { "description": "Tool invocations made during this assistant turn. Only present on assistant entries.", "type": "array", "items": { "title": "ToolCall", "description": "A tool invocation by the assistant.", "type": "object", "properties": { "id": { "description": "Optional identifier linking this call to its result.", "type": "string" }, "name": { "description": "The name of the tool that was called.", "type": "string" }, "arguments": { "description": "The arguments passed to the tool.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": ["name", "arguments"], "additionalProperties": false } }, "toolResults": { "description": "Tool results received during this assistant turn. Only present on assistant entries.", "type": "array", "items": { "title": "ToolResult", "description": "The result of a tool invocation.", "type": "object", "properties": { "id": { "description": "Optional identifier linking this result to its call.", "type": "string" }, "name": { "description": "The name of the tool that returned a result.", "type": "string" }, "result": { "description": "The tool result (object, string, or null).", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "string" }, { "type": "null" } ] }, "error": { "description": "Error message if the tool call failed.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "durationMs": { "description": "How long the tool call took in milliseconds.", "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": ["name"], "additionalProperties": false } } }, "required": ["role", "content", "timestamp"], "additionalProperties": false } }, "recordingUrl": { "description": "A URL to download the conversation recording, or null if no recording is available. This URL will expire within 24-48 hours, fetch the conversation again to get a fresh download URL.", "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "tools": { "description": "The tools that were configured for this conversation session. Empty if no tools were used.", "type": "array", "items": { "title": "ConversationToolSummary", "description": "Summary of a tool configured for the session.", "type": "object", "properties": { "type": { "description": "The tool type.", "type": "string", "enum": ["client_event", "backend_rpc"] }, "name": { "description": "The tool name.", "type": "string" }, "description": { "description": "A description of when and how the tool should be used.", "type": "string" } }, "required": ["type", "name", "description"], "additionalProperties": false } }, "status": { "type": "string", "const": "ended" }, "startedAt": { "description": "When the conversation started.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "endedAt": { "description": "When the conversation ended.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "duration": { "description": "Duration of the conversation in seconds.", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "name", "avatar", "createdAt", "maxDuration", "transcript", "recordingUrl", "tools", "status", "startedAt", "endedAt", "duration" ], "additionalProperties": false }, { "description": "A conversation that ended due to an error.", "type": "object", "properties": { "id": { "description": "Unique conversation identifier. This is the same value as the realtime session ID for the call.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "name": { "description": "Conversation name.", "type": "string" }, "avatar": { "description": "The avatar used in this conversation, or null if unavailable.", "anyOf": [ { "description": "The avatar used in this conversation.", "oneOf": [ { "title": "PresetAvatar", "description": "A preset avatar.", "type": "object", "properties": { "type": { "type": "string", "const": "runway-preset" }, "presetId": { "description": "The preset avatar ID.", "type": "string" } }, "required": ["type", "presetId"], "additionalProperties": false }, { "title": "CustomAvatar", "description": "A custom avatar created by the user.", "type": "object", "properties": { "type": { "type": "string", "const": "custom" }, "id": { "description": "The custom avatar ID, or null if deleted.", "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, { "type": "null" } ] }, "name": { "description": "The avatar name, or null if unavailable.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "imageUrl": { "description": "URL to the avatar image, or null if unavailable.", "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, "required": [ "type", "id", "name", "imageUrl" ], "additionalProperties": false } ], "discriminator": { "propertyName": "type" } }, { "type": "null" } ] }, "createdAt": { "description": "When the conversation was created.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "maxDuration": { "description": "Maximum allowed duration in seconds, or null if not set.", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "transcript": { "description": "The conversation transcript.", "maxItems": 1000, "type": "array", "items": { "title": "TranscriptEntry", "description": "A single entry in the conversation transcript.", "type": "object", "properties": { "role": { "description": "Who produced this transcript entry.", "type": "string", "enum": ["user", "assistant"] }, "content": { "description": "The spoken text, or null for tool-only turns.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timestamp": { "description": "When this entry occurred, or null if unavailable.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "toolCalls": { "description": "Tool invocations made during this assistant turn. Only present on assistant entries.", "type": "array", "items": { "title": "ToolCall", "description": "A tool invocation by the assistant.", "type": "object", "properties": { "id": { "description": "Optional identifier linking this call to its result.", "type": "string" }, "name": { "description": "The name of the tool that was called.", "type": "string" }, "arguments": { "description": "The arguments passed to the tool.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": ["name", "arguments"], "additionalProperties": false } }, "toolResults": { "description": "Tool results received during this assistant turn. Only present on assistant entries.", "type": "array", "items": { "title": "ToolResult", "description": "The result of a tool invocation.", "type": "object", "properties": { "id": { "description": "Optional identifier linking this result to its call.", "type": "string" }, "name": { "description": "The name of the tool that returned a result.", "type": "string" }, "result": { "description": "The tool result (object, string, or null).", "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "string" }, { "type": "null" } ] }, "error": { "description": "Error message if the tool call failed.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "durationMs": { "description": "How long the tool call took in milliseconds.", "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": ["name"], "additionalProperties": false } } }, "required": ["role", "content", "timestamp"], "additionalProperties": false } }, "recordingUrl": { "description": "A URL to download the conversation recording, or null if no recording is available. This URL will expire within 24-48 hours, fetch the conversation again to get a fresh download URL.", "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "tools": { "description": "The tools that were configured for this conversation session. Empty if no tools were used.", "type": "array", "items": { "title": "ConversationToolSummary", "description": "Summary of a tool configured for the session.", "type": "object", "properties": { "type": { "description": "The tool type.", "type": "string", "enum": ["client_event", "backend_rpc"] }, "name": { "description": "The tool name.", "type": "string" }, "description": { "description": "A description of when and how the tool should be used.", "type": "string" } }, "required": ["type", "name", "description"], "additionalProperties": false } }, "status": { "type": "string", "const": "failed" }, "startedAt": { "description": "When the conversation started, or null if it failed before starting.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "endedAt": { "description": "When the conversation ended, or null if it failed before starting.", "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] }, "duration": { "description": "Duration in seconds, or null if the conversation failed before starting.", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "failure": { "description": "A human-friendly reason for the failure. We do not recommend returning this to users directly without adding context.", "type": "string" }, "failureCode": { "description": "A machine-readable error code for the failure. See https://docs.dev.runwayml.com/errors/task-failures/ for more information.", "type": "string" } }, "required": [ "id", "name", "avatar", "createdAt", "maxDuration", "transcript", "recordingUrl", "tools", "status", "startedAt", "endedAt", "duration", "failure", "failureCode" ], "additionalProperties": false } ], "discriminator": { "propertyName": "status" } } } } } } }, "delete": { "tags": ["Avatars"], "summary": "Delete conversation", "description": "Delete a conversation and its associated data.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nawait client.avatarConversations.delete(\n '660e8400-e29b-41d4-a716-446655440001'\n);" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\nclient.avatar_conversations.delete(\n id=\"660e8400-e29b-41d4-a716-446655440001\",\n)" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "description": "The conversation ID." }, { "$ref": "#/components/parameters/X-Runway-Version" } ], "responses": { "204": { "description": "Success" } } } }, "/v1/avatars/{id}": { "get": { "tags": ["Avatars"], "summary": "Get avatar", "description": "Get details of a specific avatar.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nconst avatar = await client.avatars.retrieve(\n '550e8400-e29b-41d4-a716-446655440000'\n);\nconsole.log(avatar);" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\navatar = client.avatars.retrieve(\n id='550e8400-e29b-41d4-a716-446655440000'\n)\nprint(avatar)" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" } }, { "$ref": "#/components/parameters/X-Runway-Version" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "oneOf": [ { "title": "AvatarProcessing", "description": "An avatar that is still being processed.", "type": "object", "properties": { "id": { "description": "The unique identifier of the avatar.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "name": { "description": "The character name for the avatar.", "type": "string" }, "personality": { "description": "System prompt defining how the avatar should behave in conversations.", "type": "string" }, "startScript": { "description": "Opening message that the avatar will say when a session starts, or null if not set.", "anyOf": [{ "type": "string" }, { "type": "null" }] }, "voice": { "description": "The voice configured for this avatar.", "oneOf": [ { "title": "RunwayLivePresetVoiceResponse", "description": "A preset voice from the Runway API.", "type": "object", "properties": { "type": { "type": "string", "const": "runway-live-preset" }, "presetId": { "description": "The preset voice identifier.", "type": "string", "enum": [ "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" ] }, "name": { "description": "The display name of the voice.", "type": "string" }, "description": { "description": "A brief description of the voice characteristics.", "type": "string" } }, "required": [ "type", "presetId", "name", "description" ], "additionalProperties": false }, { "title": "CustomVoiceResponse", "description": "A custom voice created via the Voices API.", "type": "object", "properties": { "type": { "type": "string", "const": "custom" }, "id": { "description": "The unique identifier of the custom voice.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "deleted": { "description": "Whether the voice has been deleted. When true, name and description are omitted.", "type": "boolean" }, "name": { "description": "The display name of the voice.", "type": "string" }, "description": { "description": "A brief description of the voice characteristics.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["type", "id", "deleted"], "additionalProperties": false } ], "discriminator": { "propertyName": "type" } }, "referenceImageUri": { "description": "A URI pointing to a low-resolution preview of the avatar's reference image.", "anyOf": [{ "type": "string" }, { "type": "null" }] }, "processedImageUri": { "description": "A URI pointing to a low-resolution preview of the processed reference image.", "anyOf": [{ "type": "string" }, { "type": "null" }] }, "documentIds": { "description": "IDs of knowledge documents attached to this avatar.", "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" } }, "createdAt": { "description": "When the avatar was created.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "updatedAt": { "description": "When the avatar was last updated.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "status": { "type": "string", "const": "PROCESSING" } }, "required": [ "id", "name", "personality", "startScript", "voice", "referenceImageUri", "processedImageUri", "documentIds", "createdAt", "updatedAt", "status" ], "additionalProperties": false }, { "title": "AvatarReady", "description": "An avatar that is ready for use in sessions.", "type": "object", "properties": { "id": { "description": "The unique identifier of the avatar.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "name": { "description": "The character name for the avatar.", "type": "string" }, "personality": { "description": "System prompt defining how the avatar should behave in conversations.", "type": "string" }, "startScript": { "description": "Opening message that the avatar will say when a session starts, or null if not set.", "anyOf": [{ "type": "string" }, { "type": "null" }] }, "voice": { "description": "The voice configured for this avatar.", "oneOf": [ { "title": "RunwayLivePresetVoiceResponse", "description": "A preset voice from the Runway API.", "type": "object", "properties": { "type": { "type": "string", "const": "runway-live-preset" }, "presetId": { "description": "The preset voice identifier.", "type": "string", "enum": [ "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" ] }, "name": { "description": "The display name of the voice.", "type": "string" }, "description": { "description": "A brief description of the voice characteristics.", "type": "string" } }, "required": [ "type", "presetId", "name", "description" ], "additionalProperties": false }, { "title": "CustomVoiceResponse", "description": "A custom voice created via the Voices API.", "type": "object", "properties": { "type": { "type": "string", "const": "custom" }, "id": { "description": "The unique identifier of the custom voice.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "deleted": { "description": "Whether the voice has been deleted. When true, name and description are omitted.", "type": "boolean" }, "name": { "description": "The display name of the voice.", "type": "string" }, "description": { "description": "A brief description of the voice characteristics.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["type", "id", "deleted"], "additionalProperties": false } ], "discriminator": { "propertyName": "type" } }, "referenceImageUri": { "description": "A URI pointing to a low-resolution preview of the avatar's reference image.", "anyOf": [{ "type": "string" }, { "type": "null" }] }, "processedImageUri": { "description": "A URI pointing to a low-resolution preview of the processed reference image.", "anyOf": [{ "type": "string" }, { "type": "null" }] }, "documentIds": { "description": "IDs of knowledge documents attached to this avatar.", "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" } }, "createdAt": { "description": "When the avatar was created.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "updatedAt": { "description": "When the avatar was last updated.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "status": { "type": "string", "const": "READY" } }, "required": [ "id", "name", "personality", "startScript", "voice", "referenceImageUri", "processedImageUri", "documentIds", "createdAt", "updatedAt", "status" ], "additionalProperties": false }, { "title": "AvatarFailed", "description": "An avatar that failed to finish processing.", "type": "object", "properties": { "id": { "description": "The unique identifier of the avatar.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "name": { "description": "The character name for the avatar.", "type": "string" }, "personality": { "description": "System prompt defining how the avatar should behave in conversations.", "type": "string" }, "startScript": { "description": "Opening message that the avatar will say when a session starts, or null if not set.", "anyOf": [{ "type": "string" }, { "type": "null" }] }, "voice": { "description": "The voice configured for this avatar.", "oneOf": [ { "title": "RunwayLivePresetVoiceResponse", "description": "A preset voice from the Runway API.", "type": "object", "properties": { "type": { "type": "string", "const": "runway-live-preset" }, "presetId": { "description": "The preset voice identifier.", "type": "string", "enum": [ "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" ] }, "name": { "description": "The display name of the voice.", "type": "string" }, "description": { "description": "A brief description of the voice characteristics.", "type": "string" } }, "required": [ "type", "presetId", "name", "description" ], "additionalProperties": false }, { "title": "CustomVoiceResponse", "description": "A custom voice created via the Voices API.", "type": "object", "properties": { "type": { "type": "string", "const": "custom" }, "id": { "description": "The unique identifier of the custom voice.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "deleted": { "description": "Whether the voice has been deleted. When true, name and description are omitted.", "type": "boolean" }, "name": { "description": "The display name of the voice.", "type": "string" }, "description": { "description": "A brief description of the voice characteristics.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["type", "id", "deleted"], "additionalProperties": false } ], "discriminator": { "propertyName": "type" } }, "referenceImageUri": { "description": "A URI pointing to a low-resolution preview of the avatar's reference image.", "anyOf": [{ "type": "string" }, { "type": "null" }] }, "processedImageUri": { "description": "A URI pointing to a low-resolution preview of the processed reference image.", "anyOf": [{ "type": "string" }, { "type": "null" }] }, "documentIds": { "description": "IDs of knowledge documents attached to this avatar.", "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" } }, "createdAt": { "description": "When the avatar was created.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "updatedAt": { "description": "When the avatar was last updated.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "status": { "type": "string", "const": "FAILED" }, "failureReason": { "description": "A human-readable error message. This value is not stable and should not be matched against programmatically.", "type": "string" } }, "required": [ "id", "name", "personality", "startScript", "voice", "referenceImageUri", "processedImageUri", "documentIds", "createdAt", "updatedAt", "status", "failureReason" ], "additionalProperties": false } ], "discriminator": { "propertyName": "status" } } } } } } }, "patch": { "tags": ["Avatars"], "summary": "Update avatar", "description": "Update an existing avatar. At least one field must be provided.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nconst avatar = await client.avatars.update(\n '550e8400-e29b-41d4-a716-446655440000',\n { name: 'Updated Avatar Name' }\n);\nconsole.log(avatar);" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\navatar = client.avatars.update(\n id='550e8400-e29b-41d4-a716-446655440000',\n name='Updated Avatar Name',\n)\nprint(avatar)" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" } }, { "$ref": "#/components/parameters/X-Runway-Version" } ], "requestBody": { "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "description": "The character name for the avatar.", "type": "string", "minLength": 1, "maxLength": 50 }, "referenceImage": { "description": "A HTTPS URL, Runway URI, or data URI containing the avatar reference image. See [our docs](/assets/inputs#images) for supported formats.", "example": "https://example.com/reference.jpg", "anyOf": [ { "description": "A HTTPS URL.", "example": "https://example.com/file", "type": "string", "minLength": 13, "maxLength": 2048, "pattern": "^https:\\/\\/.*" }, { "description": "A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.", "example": "runway://", "type": "string", "minLength": 13, "maxLength": 5000, "pattern": "^runway:\\/\\/.*" }, { "description": "A data URI containing encoded media.", "example": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "type": "string", "minLength": 13, "maxLength": 5242880, "pattern": "^data:image\\/.*" } ] }, "personality": { "description": "System prompt defining how the avatar should behave in conversations.", "example": "You are a helpful support agent assisting users with their account questions. Be friendly, patient, and provide clear step-by-step guidance.", "type": "string", "minLength": 1, "maxLength": 10000 }, "startScript": { "description": "Optional opening message that the avatar will say when a session starts. Set to null to clear.", "example": "Hello! How can I help you today?", "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "voice": { "description": "The voice configuration for the avatar.", "example": { "type": "runway-live-preset", "presetId": "adrian" }, "oneOf": [ { "title": "RunwayLivePresetVoice", "description": "A preset voice from the Runway API.", "type": "object", "properties": { "type": { "type": "string", "const": "runway-live-preset" }, "presetId": { "description": "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).", "type": "string", "enum": [ "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" ] } }, "required": ["type", "presetId"] }, { "title": "CustomVoice", "description": "A custom voice created via the Voices API.", "type": "object", "properties": { "type": { "type": "string", "const": "custom" }, "id": { "description": "The ID of a custom voice created via the Voices API.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" } }, "required": ["type", "id"] } ], "discriminator": { "propertyName": "type" } }, "documentIds": { "description": "List of knowledge document IDs to attach to this avatar. Replaces all current attachments. Documents provide additional context during conversations.", "maxItems": 50, "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" } }, "imageProcessing": { "description": "Controls image preprocessing. `optimize` improves the image for better avatar results. `none` uses the image as-is; quality not guaranteed.", "default": "optimize", "type": "string", "enum": ["optimize", "none"] } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "oneOf": [ { "title": "AvatarProcessing", "description": "An avatar that is still being processed.", "type": "object", "properties": { "id": { "description": "The unique identifier of the avatar.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "name": { "description": "The character name for the avatar.", "type": "string" }, "personality": { "description": "System prompt defining how the avatar should behave in conversations.", "type": "string" }, "startScript": { "description": "Opening message that the avatar will say when a session starts, or null if not set.", "anyOf": [{ "type": "string" }, { "type": "null" }] }, "voice": { "description": "The voice configured for this avatar.", "oneOf": [ { "title": "RunwayLivePresetVoiceResponse", "description": "A preset voice from the Runway API.", "type": "object", "properties": { "type": { "type": "string", "const": "runway-live-preset" }, "presetId": { "description": "The preset voice identifier.", "type": "string", "enum": [ "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" ] }, "name": { "description": "The display name of the voice.", "type": "string" }, "description": { "description": "A brief description of the voice characteristics.", "type": "string" } }, "required": [ "type", "presetId", "name", "description" ], "additionalProperties": false }, { "title": "CustomVoiceResponse", "description": "A custom voice created via the Voices API.", "type": "object", "properties": { "type": { "type": "string", "const": "custom" }, "id": { "description": "The unique identifier of the custom voice.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "deleted": { "description": "Whether the voice has been deleted. When true, name and description are omitted.", "type": "boolean" }, "name": { "description": "The display name of the voice.", "type": "string" }, "description": { "description": "A brief description of the voice characteristics.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["type", "id", "deleted"], "additionalProperties": false } ], "discriminator": { "propertyName": "type" } }, "referenceImageUri": { "description": "A URI pointing to a low-resolution preview of the avatar's reference image.", "anyOf": [{ "type": "string" }, { "type": "null" }] }, "processedImageUri": { "description": "A URI pointing to a low-resolution preview of the processed reference image.", "anyOf": [{ "type": "string" }, { "type": "null" }] }, "documentIds": { "description": "IDs of knowledge documents attached to this avatar.", "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" } }, "createdAt": { "description": "When the avatar was created.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "updatedAt": { "description": "When the avatar was last updated.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "status": { "type": "string", "const": "PROCESSING" } }, "required": [ "id", "name", "personality", "startScript", "voice", "referenceImageUri", "processedImageUri", "documentIds", "createdAt", "updatedAt", "status" ], "additionalProperties": false }, { "title": "AvatarReady", "description": "An avatar that is ready for use in sessions.", "type": "object", "properties": { "id": { "description": "The unique identifier of the avatar.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "name": { "description": "The character name for the avatar.", "type": "string" }, "personality": { "description": "System prompt defining how the avatar should behave in conversations.", "type": "string" }, "startScript": { "description": "Opening message that the avatar will say when a session starts, or null if not set.", "anyOf": [{ "type": "string" }, { "type": "null" }] }, "voice": { "description": "The voice configured for this avatar.", "oneOf": [ { "title": "RunwayLivePresetVoiceResponse", "description": "A preset voice from the Runway API.", "type": "object", "properties": { "type": { "type": "string", "const": "runway-live-preset" }, "presetId": { "description": "The preset voice identifier.", "type": "string", "enum": [ "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" ] }, "name": { "description": "The display name of the voice.", "type": "string" }, "description": { "description": "A brief description of the voice characteristics.", "type": "string" } }, "required": [ "type", "presetId", "name", "description" ], "additionalProperties": false }, { "title": "CustomVoiceResponse", "description": "A custom voice created via the Voices API.", "type": "object", "properties": { "type": { "type": "string", "const": "custom" }, "id": { "description": "The unique identifier of the custom voice.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "deleted": { "description": "Whether the voice has been deleted. When true, name and description are omitted.", "type": "boolean" }, "name": { "description": "The display name of the voice.", "type": "string" }, "description": { "description": "A brief description of the voice characteristics.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["type", "id", "deleted"], "additionalProperties": false } ], "discriminator": { "propertyName": "type" } }, "referenceImageUri": { "description": "A URI pointing to a low-resolution preview of the avatar's reference image.", "anyOf": [{ "type": "string" }, { "type": "null" }] }, "processedImageUri": { "description": "A URI pointing to a low-resolution preview of the processed reference image.", "anyOf": [{ "type": "string" }, { "type": "null" }] }, "documentIds": { "description": "IDs of knowledge documents attached to this avatar.", "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" } }, "createdAt": { "description": "When the avatar was created.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "updatedAt": { "description": "When the avatar was last updated.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "status": { "type": "string", "const": "READY" } }, "required": [ "id", "name", "personality", "startScript", "voice", "referenceImageUri", "processedImageUri", "documentIds", "createdAt", "updatedAt", "status" ], "additionalProperties": false }, { "title": "AvatarFailed", "description": "An avatar that failed to finish processing.", "type": "object", "properties": { "id": { "description": "The unique identifier of the avatar.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "name": { "description": "The character name for the avatar.", "type": "string" }, "personality": { "description": "System prompt defining how the avatar should behave in conversations.", "type": "string" }, "startScript": { "description": "Opening message that the avatar will say when a session starts, or null if not set.", "anyOf": [{ "type": "string" }, { "type": "null" }] }, "voice": { "description": "The voice configured for this avatar.", "oneOf": [ { "title": "RunwayLivePresetVoiceResponse", "description": "A preset voice from the Runway API.", "type": "object", "properties": { "type": { "type": "string", "const": "runway-live-preset" }, "presetId": { "description": "The preset voice identifier.", "type": "string", "enum": [ "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" ] }, "name": { "description": "The display name of the voice.", "type": "string" }, "description": { "description": "A brief description of the voice characteristics.", "type": "string" } }, "required": [ "type", "presetId", "name", "description" ], "additionalProperties": false }, { "title": "CustomVoiceResponse", "description": "A custom voice created via the Voices API.", "type": "object", "properties": { "type": { "type": "string", "const": "custom" }, "id": { "description": "The unique identifier of the custom voice.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "deleted": { "description": "Whether the voice has been deleted. When true, name and description are omitted.", "type": "boolean" }, "name": { "description": "The display name of the voice.", "type": "string" }, "description": { "description": "A brief description of the voice characteristics.", "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": ["type", "id", "deleted"], "additionalProperties": false } ], "discriminator": { "propertyName": "type" } }, "referenceImageUri": { "description": "A URI pointing to a low-resolution preview of the avatar's reference image.", "anyOf": [{ "type": "string" }, { "type": "null" }] }, "processedImageUri": { "description": "A URI pointing to a low-resolution preview of the processed reference image.", "anyOf": [{ "type": "string" }, { "type": "null" }] }, "documentIds": { "description": "IDs of knowledge documents attached to this avatar.", "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" } }, "createdAt": { "description": "When the avatar was created.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "updatedAt": { "description": "When the avatar was last updated.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "status": { "type": "string", "const": "FAILED" }, "failureReason": { "description": "A human-readable error message. This value is not stable and should not be matched against programmatically.", "type": "string" } }, "required": [ "id", "name", "personality", "startScript", "voice", "referenceImageUri", "processedImageUri", "documentIds", "createdAt", "updatedAt", "status", "failureReason" ], "additionalProperties": false } ], "discriminator": { "propertyName": "status" } } } } }, "409": { "description": "The reference image cannot be updated while the avatar is processing.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "description": "A message explaining why the update was rejected.", "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } }, "delete": { "tags": ["Avatars"], "summary": "Delete avatar", "description": "Delete an avatar.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nawait client.avatars.delete('550e8400-e29b-41d4-a716-446655440000');" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\nclient.avatars.delete(id='550e8400-e29b-41d4-a716-446655440000')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" } }, { "$ref": "#/components/parameters/X-Runway-Version" } ], "responses": { "204": { "description": "Success" } } } }, "/v1/avatar_videos": { "post": { "tags": ["Avatar Videos"], "summary": "Generate avatar video from audio or text", "description": "Start an asynchronous task to generate a video of an avatar speaking. Provide `speech` with `type: \"audio\"` (audio file) or `type: \"text\"` (text script for TTS). Poll `GET /v1/tasks/:id` to check progress and retrieve the output video URL once complete.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nconst task = await client.avatarVideos\n .create({\n model: 'gwm1_avatars',\n avatar: {\n type: 'runway-preset',\n presetId: 'influencer',\n },\n speech: {\n type: 'text',\n text: 'Welcome to Runway! I can help you create amazing videos.',\n voice: { type: 'preset', presetId: 'clara' },\n },\n })\n .waitForTaskOutput();\n\nconsole.log(task);" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\ntask = client.avatar_videos.create(\n model='gwm1_avatars',\n avatar={\n 'type': 'runway-preset',\n 'preset_id': 'influencer',\n },\n speech={\n 'type': 'text',\n 'text': 'Welcome to Runway! I can help you create amazing videos.',\n 'voice': {'type': 'preset', 'preset_id': 'clara'},\n },\n).wait_for_task_output()\n\nprint(task)" } ], "parameters": [{ "$ref": "#/components/parameters/X-Runway-Version" }], "requestBody": { "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "model": { "description": "The model to use for avatar video generation.", "type": "string", "const": "gwm1_avatars" }, "avatar": { "description": "The avatar configuration for the session.", "oneOf": [ { "title": "RunwayPresetAvatar", "description": "A preset avatar from Runway.", "type": "object", "properties": { "type": { "type": "string", "const": "runway-preset" }, "presetId": { "description": "ID of a preset avatar.", "type": "string", "enum": [ "game-character", "music-superstar", "game-character-man", "cat-character", "influencer", "tennis-coach", "human-resource", "fashion-designer", "cooking-teacher" ] } }, "required": ["type", "presetId"] }, { "title": "CustomAvatar", "description": "A user-created avatar.", "type": "object", "properties": { "type": { "type": "string", "const": "custom" }, "avatarId": { "description": "ID of a user-created avatar.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" } }, "required": ["type", "avatarId"] } ], "discriminator": { "propertyName": "type" } }, "speech": { "description": "The speech source for avatar video generation. Either an audio file or text script.", "oneOf": [ { "title": "AudioInput", "description": "Provide an audio file for the avatar to speak.", "type": "object", "properties": { "type": { "type": "string", "const": "audio" }, "audio": { "description": "A HTTPS URL, Runway or data URI containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information.", "example": "https://example.com/audio.mp3", "anyOf": [ { "description": "A HTTPS URL.", "example": "https://example.com/file", "type": "string", "minLength": 13, "maxLength": 2048, "pattern": "^https:\\/\\/.*" }, { "description": "A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.", "example": "runway://", "type": "string", "minLength": 13, "maxLength": 5000, "pattern": "^runway:\\/\\/.*" }, { "description": "A data URI containing encoded media.", "example": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "type": "string", "minLength": 13, "maxLength": 16777216, "pattern": "^data:audio\\/.*" } ] } }, "required": ["type", "audio"] }, { "title": "TextInput", "description": "Provide text for the avatar to speak via TTS.", "type": "object", "properties": { "type": { "type": "string", "const": "text" }, "text": { "description": "Text script for speech-driven video generation.", "type": "string", "minLength": 1, "maxLength": 3000 }, "voice": { "description": "Optional voice override for TTS. If not provided, the avatar's configured voice is used.", "oneOf": [ { "title": "RunwayPresetVoice", "description": "A preset voice from the Runway API.", "type": "object", "properties": { "type": { "type": "string", "const": "preset" }, "presetId": { "type": "string", "enum": [ "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" ] } }, "required": ["type", "presetId"] }, { "title": "CustomVoice", "description": "A custom voice created via the Voices API.", "type": "object", "properties": { "type": { "type": "string", "const": "custom" }, "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" } }, "required": ["type", "id"] } ], "discriminator": { "propertyName": "type" } } }, "required": ["type", "text"] } ], "discriminator": { "propertyName": "type" } } }, "required": ["model", "avatar", "speech"], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "The ID of the avatar video task. Use `GET /v1/tasks/:id` to poll for status and output.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" } }, "required": ["id"], "additionalProperties": false } } } } } } }, "/v1/documents": { "post": { "tags": ["Knowledge"], "summary": "Create document", "description": "Create a new knowledge document. Documents can be attached to avatars to provide additional context during conversations.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nconst document = await client.documents.create({\n name: 'Product FAQ',\n content: '# Product FAQ\\n\\n## What is your return policy?\\n...',\n});\nconsole.log(document);" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\ndocument = client.documents.create(\n name='Product FAQ',\n content='# Product FAQ\\n\\n## What is your return policy?\\n...',\n)\nprint(document)" } ], "parameters": [{ "$ref": "#/components/parameters/X-Runway-Version" }], "requestBody": { "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "description": "A descriptive name for the document.", "example": "Product FAQ", "type": "string", "minLength": 1, "maxLength": 255 }, "content": { "description": "The markdown or plain text content of the document.", "example": "# Product FAQ\n\n## What is your return policy?\n\nWe offer a 30-day return policy...", "type": "string", "minLength": 1, "maxLength": 200000 } }, "required": ["name", "content"] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "The unique identifier of the document.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "name": { "description": "The name of the document.", "type": "string" }, "type": { "description": "The type of document.", "type": "string", "enum": ["text", "file"] }, "usedBy": { "description": "Avatars that use this document. Always empty for newly created documents.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "The avatar ID.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "name": { "description": "The avatar name.", "type": "string" }, "imageUrl": { "description": "URL to the avatar image, or null if not yet processed.", "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, "required": ["id", "name", "imageUrl"], "additionalProperties": false } }, "content": { "description": "The full content of the document.", "type": "string" }, "createdAt": { "description": "When the document was created.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "updatedAt": { "description": "When the document was last updated.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "id", "name", "type", "usedBy", "content", "createdAt", "updatedAt" ], "additionalProperties": false } } } } } }, "get": { "tags": ["Knowledge"], "summary": "List documents", "description": "List knowledge documents for the authenticated user with cursor-based pagination.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nconst documents = await client.documents.list();\nfor await (const document of documents) {\n console.log(document);\n}" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\nfor document in client.documents.list():\n print(document)" } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1000 }, "description": "Cursor from a previous response for fetching the next page of results." }, { "name": "limit", "in": "query", "required": true, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "The maximum number of items to return per page." }, { "name": "sort", "in": "query", "required": true, "schema": { "default": "createdAt", "type": "string", "enum": ["createdAt", "updatedAt"] }, "description": "Field to sort results by." }, { "name": "order", "in": "query", "required": true, "schema": { "default": "desc", "type": "string", "enum": ["asc", "desc"] }, "description": "Sort direction." }, { "$ref": "#/components/parameters/X-Runway-Version" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "The list of items for the current page.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "The unique identifier of the document.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "name": { "description": "The name of the document.", "type": "string" }, "type": { "description": "The type of document.", "type": "string", "enum": ["text", "file"] }, "usedBy": { "description": "Avatars that use this document.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "The avatar ID.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "name": { "description": "The avatar name.", "type": "string" }, "imageUrl": { "description": "URL to the avatar image, or null if not yet processed.", "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, "required": ["id", "name", "imageUrl"], "additionalProperties": false } }, "createdAt": { "description": "When the document was created.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "updatedAt": { "description": "When the document was last updated.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "id", "name", "type", "usedBy", "createdAt", "updatedAt" ], "additionalProperties": false } }, "hasMore": { "description": "Whether there are more items available after this page.", "type": "boolean" }, "nextCursor": { "description": "Cursor to use for fetching the next page, or null if there are no more pages.", "anyOf": [{ "type": "string" }, { "type": "null" }] } }, "required": ["data", "hasMore", "nextCursor"], "additionalProperties": false } } } } } } }, "/v1/documents/{id}": { "get": { "tags": ["Knowledge"], "summary": "Get document", "description": "Get details of a specific knowledge document.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nconst document = await client.documents.retrieve(\n '550e8400-e29b-41d4-a716-446655440000'\n);\nconsole.log(document);" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\ndocument = client.documents.retrieve(\n id='550e8400-e29b-41d4-a716-446655440000'\n)\nprint(document)" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "description": "The document ID." }, { "$ref": "#/components/parameters/X-Runway-Version" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "The unique identifier of the document.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "name": { "description": "The name of the document.", "type": "string" }, "type": { "description": "The type of document.", "type": "string", "enum": ["text", "file"] }, "usedBy": { "description": "Avatars that use this document.", "type": "array", "items": { "type": "object", "properties": { "id": { "description": "The avatar ID.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "name": { "description": "The avatar name.", "type": "string" }, "imageUrl": { "description": "URL to the avatar image, or null if not yet processed.", "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, "required": ["id", "name", "imageUrl"], "additionalProperties": false } }, "content": { "description": "The full content of the document.", "type": "string" }, "createdAt": { "description": "When the document was created.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "updatedAt": { "description": "When the document was last updated.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "id", "name", "type", "usedBy", "content", "createdAt", "updatedAt" ], "additionalProperties": false } } } } } }, "patch": { "tags": ["Knowledge"], "summary": "Update document", "description": "Update a knowledge document. At least one of `name` or `content` must be provided.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nawait client.documents.update(\n '550e8400-e29b-41d4-a716-446655440000',\n { name: 'Updated Product FAQ' }\n);" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\nclient.documents.update(\n id='550e8400-e29b-41d4-a716-446655440000',\n name='Updated Product FAQ',\n)" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "description": "The document ID." }, { "$ref": "#/components/parameters/X-Runway-Version" } ], "requestBody": { "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "description": "A new name for the document.", "example": "Updated Product FAQ", "type": "string", "minLength": 1, "maxLength": 255 }, "content": { "description": "New markdown or plain text content for the document.", "example": "# Updated FAQ\n\n...", "type": "string", "minLength": 1, "maxLength": 200000 } } } } } }, "responses": { "204": { "description": "Success" } } }, "delete": { "tags": ["Knowledge"], "summary": "Delete document", "description": "Delete a knowledge document. This also removes it from all avatars it was attached to.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nawait client.documents.delete('550e8400-e29b-41d4-a716-446655440000');" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\nclient.documents.delete(id='550e8400-e29b-41d4-a716-446655440000')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "description": "The document ID." }, { "$ref": "#/components/parameters/X-Runway-Version" } ], "responses": { "204": { "description": "Success" } } } }, "/v1/realtime_sessions": { "post": { "tags": ["Realtime Sessions"], "summary": "Create realtime session", "description": "Create a new realtime session with the specified model configuration. The returned ID is also the conversation ID used later to fetch transcripts and recordings from the avatar conversation endpoints.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nconst session = await client.realtimeSessions.create({\n model: 'gwm1_avatars',\n avatar: {\n type: 'custom',\n avatarId: '550e8400-e29b-41d4-a716-446655440000',\n },\n});\nconsole.log(session.id);" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\nsession = client.realtime_sessions.create(\n model='gwm1_avatars',\n avatar={\n 'type': 'custom',\n 'avatar_id': '550e8400-e29b-41d4-a716-446655440000',\n },\n)\nprint(session.id)" } ], "parameters": [{ "$ref": "#/components/parameters/X-Runway-Version" }], "requestBody": { "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "model": { "description": "The realtime session model type.", "type": "string", "const": "gwm1_avatars" }, "avatar": { "description": "The avatar configuration for the session.", "oneOf": [ { "title": "RunwayPresetAvatar", "description": "A preset avatar from Runway.", "type": "object", "properties": { "type": { "type": "string", "const": "runway-preset" }, "presetId": { "description": "ID of a preset avatar.", "type": "string", "enum": [ "game-character", "music-superstar", "game-character-man", "cat-character", "influencer", "tennis-coach", "human-resource", "fashion-designer", "cooking-teacher" ] } }, "required": ["type", "presetId"] }, { "title": "CustomAvatar", "description": "A user-created avatar.", "type": "object", "properties": { "type": { "type": "string", "const": "custom" }, "avatarId": { "description": "ID of a user-created avatar.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" } }, "required": ["type", "avatarId"] } ], "discriminator": { "propertyName": "type" } }, "maxDuration": { "description": "Maximum session duration in seconds.", "default": 300, "type": "integer", "minimum": 10, "maximum": 1800 }, "personality": { "description": "Override the avatar personality for this session. If not provided, uses the avatar default.", "type": "string", "minLength": 1, "maxLength": 10000 }, "startScript": { "description": "Override the avatar start script for this session. If not provided, uses the avatar default.", "type": "string", "minLength": 1, "maxLength": 2000 }, "tools": { "description": "Tools available to the avatar during the session.", "default": [], "maxItems": 20, "type": "array", "items": { "description": "A tool available to the avatar during the session.", "oneOf": [ { "title": "ClientEventTool", "description": "A fire-and-forget tool that sends arguments to the frontend client of the realtime session.", "type": "object", "properties": { "type": { "type": "string", "const": "client_event" }, "name": { "description": "The tool name. Must start with a letter or underscore, followed by alphanumeric characters or underscores.", "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$" }, "description": { "description": "A description of when and how the tool should be used. Be specific so the avatar understands the right context to invoke it.", "type": "string", "minLength": 1, "maxLength": 1024 }, "parameters": { "default": [], "maxItems": 20, "type": "array", "items": { "title": "ToolParameter", "oneOf": [ { "title": "StringParameter", "type": "object", "properties": { "name": { "description": "The parameter name.", "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$" }, "description": { "description": "A description of the parameter.", "type": "string", "minLength": 1, "maxLength": 1024 }, "required": { "description": "Whether the parameter is required.", "default": true, "type": "boolean" }, "type": { "type": "string", "const": "string" }, "enum": { "description": "Allowed values for the parameter.", "maxItems": 20, "type": "array", "items": { "type": "string", "maxLength": 64 } } }, "required": ["name", "description", "type"] }, { "title": "IntegerParameter", "type": "object", "properties": { "name": { "description": "The parameter name.", "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$" }, "description": { "description": "A description of the parameter.", "type": "string", "minLength": 1, "maxLength": 1024 }, "required": { "description": "Whether the parameter is required.", "default": true, "type": "boolean" }, "type": { "type": "string", "const": "integer" } }, "required": ["name", "description", "type"] }, { "title": "NumberParameter", "type": "object", "properties": { "name": { "description": "The parameter name.", "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$" }, "description": { "description": "A description of the parameter.", "type": "string", "minLength": 1, "maxLength": 1024 }, "required": { "description": "Whether the parameter is required.", "default": true, "type": "boolean" }, "type": { "type": "string", "const": "number" } }, "required": ["name", "description", "type"] }, { "title": "BooleanParameter", "type": "object", "properties": { "name": { "description": "The parameter name.", "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$" }, "description": { "description": "A description of the parameter.", "type": "string", "minLength": 1, "maxLength": 1024 }, "required": { "description": "Whether the parameter is required.", "default": true, "type": "boolean" }, "type": { "type": "string", "const": "boolean" } }, "required": ["name", "description", "type"] }, { "title": "ArrayParameter", "type": "object", "properties": { "name": { "description": "The parameter name.", "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$" }, "description": { "description": "A description of the parameter.", "type": "string", "minLength": 1, "maxLength": 1024 }, "required": { "description": "Whether the parameter is required.", "default": true, "type": "boolean" }, "type": { "type": "string", "const": "array" }, "items": { "description": "Item schema for array elements.", "type": "object", "properties": { "type": { "description": "The type of each element in the array.", "type": "string", "enum": [ "string", "integer", "number", "boolean" ] } }, "required": ["type"] } }, "required": [ "name", "description", "type", "items" ] }, { "title": "ObjectParameter", "type": "object", "properties": { "name": { "description": "The parameter name.", "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$" }, "description": { "description": "A description of the parameter.", "type": "string", "minLength": 1, "maxLength": 1024 }, "required": { "description": "Whether the parameter is required.", "default": true, "type": "boolean" }, "type": { "type": "string", "const": "object" }, "properties": { "description": "The properties of the object.", "maxItems": 20, "type": "array", "items": {} } }, "required": [ "name", "description", "type", "properties" ] } ], "discriminator": { "propertyName": "type" } } } }, "required": ["type", "name", "description"] }, { "title": "BackendRPCTool", "description": "A tool that makes a round-trip RPC call to your backend server during the session.", "type": "object", "properties": { "type": { "type": "string", "const": "backend_rpc" }, "name": { "description": "The tool name. Must start with a letter or underscore, followed by alphanumeric characters or underscores.", "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$" }, "description": { "description": "A description of when and how the tool should be used. Be specific so the avatar understands the right context to invoke it.", "type": "string", "minLength": 1, "maxLength": 1024 }, "parameters": { "default": [], "maxItems": 20, "type": "array", "items": { "title": "ToolParameter", "oneOf": [ { "title": "StringParameter", "type": "object", "properties": { "name": { "description": "The parameter name.", "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$" }, "description": { "description": "A description of the parameter.", "type": "string", "minLength": 1, "maxLength": 1024 }, "required": { "description": "Whether the parameter is required.", "default": true, "type": "boolean" }, "type": { "type": "string", "const": "string" }, "enum": { "description": "Allowed values for the parameter.", "maxItems": 20, "type": "array", "items": { "type": "string", "maxLength": 64 } } }, "required": ["name", "description", "type"] }, { "title": "IntegerParameter", "type": "object", "properties": { "name": { "description": "The parameter name.", "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$" }, "description": { "description": "A description of the parameter.", "type": "string", "minLength": 1, "maxLength": 1024 }, "required": { "description": "Whether the parameter is required.", "default": true, "type": "boolean" }, "type": { "type": "string", "const": "integer" } }, "required": ["name", "description", "type"] }, { "title": "NumberParameter", "type": "object", "properties": { "name": { "description": "The parameter name.", "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$" }, "description": { "description": "A description of the parameter.", "type": "string", "minLength": 1, "maxLength": 1024 }, "required": { "description": "Whether the parameter is required.", "default": true, "type": "boolean" }, "type": { "type": "string", "const": "number" } }, "required": ["name", "description", "type"] }, { "title": "BooleanParameter", "type": "object", "properties": { "name": { "description": "The parameter name.", "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$" }, "description": { "description": "A description of the parameter.", "type": "string", "minLength": 1, "maxLength": 1024 }, "required": { "description": "Whether the parameter is required.", "default": true, "type": "boolean" }, "type": { "type": "string", "const": "boolean" } }, "required": ["name", "description", "type"] }, { "title": "ArrayParameter", "type": "object", "properties": { "name": { "description": "The parameter name.", "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$" }, "description": { "description": "A description of the parameter.", "type": "string", "minLength": 1, "maxLength": 1024 }, "required": { "description": "Whether the parameter is required.", "default": true, "type": "boolean" }, "type": { "type": "string", "const": "array" }, "items": { "description": "Item schema for array elements.", "type": "object", "properties": { "type": { "description": "The type of each element in the array.", "type": "string", "enum": [ "string", "integer", "number", "boolean" ] } }, "required": ["type"] } }, "required": [ "name", "description", "type", "items" ] }, { "title": "ObjectParameter", "type": "object", "properties": { "name": { "description": "The parameter name.", "type": "string", "minLength": 1, "maxLength": 64, "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$" }, "description": { "description": "A description of the parameter.", "type": "string", "minLength": 1, "maxLength": 1024 }, "required": { "description": "Whether the parameter is required.", "default": true, "type": "boolean" }, "type": { "type": "string", "const": "object" }, "properties": { "description": "The properties of the object.", "maxItems": 20, "type": "array", "items": {} } }, "required": [ "name", "description", "type", "properties" ] } ], "discriminator": { "propertyName": "type" } } }, "timeoutSeconds": { "description": "Maximum time to wait for the backend to respond.", "default": 4, "type": "number", "minimum": 1, "maximum": 8 } }, "required": ["type", "name", "description"] } ], "discriminator": { "propertyName": "type" } } } }, "required": ["model", "avatar"] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "The ID of the created realtime session. This same value is later used as the conversation ID in the avatar conversation endpoints.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" } }, "required": ["id"], "additionalProperties": false } } } } } } }, "/v1/realtime_sessions/{id}": { "get": { "tags": ["Realtime Sessions"], "summary": "Get realtime session", "description": "Get the status of a realtime session. This endpoint uses the same ID that the avatar conversation endpoints later expose as the conversation ID.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nconst session = await client.realtimeSessions.retrieve(\n '550e8400-e29b-41d4-a716-446655440000'\n);\nconsole.log(session.status);" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\nsession = client.realtime_sessions.retrieve(\n id='550e8400-e29b-41d4-a716-446655440000'\n)\nprint(session.status)" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "description": "The realtime session ID. This same value is later used as the conversation ID in the avatar conversation endpoints." }, { "$ref": "#/components/parameters/X-Runway-Version" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "oneOf": [ { "title": "SessionNotReady", "description": "A session that is being provisioned.", "type": "object", "properties": { "id": { "description": "The realtime session ID. This same value is later used as the conversation ID in the avatar conversation endpoints.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "createdAt": { "description": "When the session was created.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "status": { "type": "string", "const": "NOT_READY" }, "queued": { "description": "When true, the session is waiting in a queue for available capacity. When false or absent, the session is actively being provisioned.", "type": "boolean" } }, "required": ["id", "createdAt", "status"], "additionalProperties": false }, { "title": "SessionReady", "description": "A session that is ready to connect.", "type": "object", "properties": { "id": { "description": "The realtime session ID. This same value is later used as the conversation ID in the avatar conversation endpoints.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "createdAt": { "description": "When the session was created.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "status": { "type": "string", "const": "READY" }, "expiresAt": { "description": "When the session credentials expire.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "sessionKey": { "description": "Session key for authenticating the /consume endpoint. Use as Bearer token.", "type": "string" } }, "required": [ "id", "createdAt", "status", "expiresAt", "sessionKey" ], "additionalProperties": false }, { "title": "SessionRunning", "description": "A session with an active WebRTC connection.", "type": "object", "properties": { "id": { "description": "The realtime session ID. This same value is later used as the conversation ID in the avatar conversation endpoints.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "createdAt": { "description": "When the session was created.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "status": { "type": "string", "const": "RUNNING" } }, "required": ["id", "createdAt", "status"], "additionalProperties": false }, { "title": "SessionCompleted", "description": "A session that ended normally.", "type": "object", "properties": { "id": { "description": "The realtime session ID. This same value is later used as the conversation ID in the avatar conversation endpoints.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "createdAt": { "description": "When the session was created.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "status": { "type": "string", "const": "COMPLETED" }, "duration": { "description": "The session duration in seconds.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["id", "createdAt", "status", "duration"], "additionalProperties": false }, { "title": "SessionFailed", "description": "A session that encountered an error.", "type": "object", "properties": { "id": { "description": "The realtime session ID. This same value is later used as the conversation ID in the avatar conversation endpoints.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "createdAt": { "description": "When the session was created.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "status": { "type": "string", "const": "FAILED" }, "failure": { "description": "A human-readable error message. This value is not stable and should not be matched against programmatically.", "type": "string" }, "failureCode": { "description": "A stable, machine-readable error code. See https://docs.dev.runwayml.com/errors/task-failures/ for more information.", "type": "string" } }, "required": [ "id", "createdAt", "status", "failure", "failureCode" ], "additionalProperties": false }, { "title": "SessionCancelled", "description": "A session that was explicitly cancelled.", "type": "object", "properties": { "id": { "description": "The realtime session ID. This same value is later used as the conversation ID in the avatar conversation endpoints.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "createdAt": { "description": "When the session was created.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "status": { "type": "string", "const": "CANCELLED" } }, "required": ["id", "createdAt", "status"], "additionalProperties": false } ], "discriminator": { "propertyName": "status" } } } } } } }, "delete": { "tags": ["Realtime Sessions"], "summary": "Cancel realtime session", "description": "Cancel an active realtime session.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nawait client.realtimeSessions.delete(\n '550e8400-e29b-41d4-a716-446655440000'\n);" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\nclient.realtime_sessions.delete(\n id='550e8400-e29b-41d4-a716-446655440000'\n)" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "description": "The realtime session ID. This same value is later used as the conversation ID in the avatar conversation endpoints." }, { "$ref": "#/components/parameters/X-Runway-Version" } ], "responses": { "204": { "description": "Success" } } } }, "/v1/tasks/{id}": { "get": { "tags": ["Task management"], "summary": "Get task detail", "description": "Return details about a task. Consumers of this API should not expect updates more frequent than once every five seconds for a given task.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\n// Fetch the current state of the task:\nconst task = await client.tasks.retrieve(\n '17f20503-6c24-4c16-946b-35dbbce2af2f'\n);\n\n// Or, wait for the task to succeed or fail:\nconst task = await client.tasks\n .retrieve('17f20503-6c24-4c16-946b-35dbbce2af2f')\n .waitForTaskOutput();" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\ntask_id = '17f20503-6c24-4c16-946b-35dbbce2af2f'\n\n# Fetch the current state of the task:\ntask = client.tasks.retrieve(id=task_id)\nprint(task)\n\n# Or, wait for the task to succeed or fail:\ntask = client.tasks.retrieve(id=task_id).wait_for_task_output()\nprint(task)" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "description": "The ID of a previously-submitted task that has not been canceled or deleted." }, { "$ref": "#/components/parameters/X-Runway-Version" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "oneOf": [ { "description": "A pending task", "type": "object", "properties": { "id": { "description": "The ID of the task being returned.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "createdAt": { "description": "The timestamp that the task was submitted at.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "status": { "type": "string", "const": "PENDING" } }, "required": ["id", "createdAt", "status"], "additionalProperties": false }, { "description": "A throttled task", "type": "object", "properties": { "id": { "description": "The ID of the task being returned.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "createdAt": { "description": "The timestamp that the task was submitted at.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "status": { "type": "string", "const": "THROTTLED" } }, "required": ["id", "createdAt", "status"], "additionalProperties": false }, { "description": "A cancelled or deleted task", "type": "object", "properties": { "id": { "description": "The ID of the task being returned.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "createdAt": { "description": "The timestamp that the task was submitted at.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "status": { "type": "string", "const": "CANCELLED" } }, "required": ["id", "createdAt", "status"], "additionalProperties": false }, { "description": "A running task", "type": "object", "properties": { "id": { "description": "The ID of the task being returned.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "createdAt": { "description": "The timestamp that the task was submitted at.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "status": { "type": "string", "const": "RUNNING" }, "progress": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": ["id", "createdAt", "status", "progress"], "additionalProperties": false }, { "description": "A failed task", "type": "object", "properties": { "id": { "description": "The ID of the task being returned.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "createdAt": { "description": "The timestamp that the task was submitted at.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "status": { "type": "string", "const": "FAILED" }, "failure": { "description": "A human-friendly reason for the failure. We do not recommend returning this to users directly without adding context.", "type": "string" }, "failureCode": { "description": "A machine-readable error code for the failure. See https://docs.dev.runwayml.com/errors/task-failures/ for more information.", "type": "string" } }, "required": ["id", "createdAt", "status", "failure"], "additionalProperties": false }, { "description": "A succeeded task", "type": "object", "properties": { "id": { "description": "The ID of the task being returned.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "createdAt": { "description": "The timestamp that the task was submitted at.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "status": { "type": "string", "const": "SUCCEEDED" }, "output": { "description": "An array of URLs that return the output of the task. These URLs will expire within 24-48 hours; fetch the task again to get fresh URLs. It is expected that you download the assets at these URLs and store them in your own storage system.", "type": "array", "items": { "type": "string", "format": "uri" } } }, "required": ["id", "createdAt", "status", "output"], "additionalProperties": false } ], "discriminator": { "propertyName": "status" } }, "examples": { "pending": { "title": "Pending task", "summary": "An example of a pending task", "value": { "id": "17f20503-6c24-4c16-946b-35dbbce2af2f", "status": "PENDING", "createdAt": "2024-06-27T19:49:32.334Z" } }, "throttled": { "title": "Throttled task", "summary": "An example of a throttled task", "value": { "id": "355e42da-b3f9-4b65-9be2-fb10bda026fc", "status": "THROTTLED", "createdAt": "2024-06-27T19:49:32.335Z" } }, "running": { "title": "Running task", "summary": "An example of a running task", "value": { "id": "08388106-1b46-4f5c-bd46-1c1d7ee86892", "status": "RUNNING", "createdAt": "2024-06-27T19:49:32.335Z", "progress": 0.2 } }, "succeeded": { "title": "Succeeded task", "summary": "An example of a succeeded task", "value": { "id": "d2e3d1f4-1b3c-4b5c-8d46-1c1d7ee86892", "status": "SUCCEEDED", "createdAt": "2024-06-27T19:49:32.335Z", "output": [ "https://example.com/output1.jpg", "https://example.com/output2.jpg" ] } }, "failed": { "title": "Failed task", "summary": "An example of a failed task", "value": { "id": "6da960dd-ef88-40fc-9628-02e9b6a6a008", "status": "FAILED", "createdAt": "2024-06-27T19:49:32.335Z", "failure": "The provided image was flagged by content moderation.", "failureCode": "SAFETY.INPUT.IMAGE" } } } } } }, "404": { "description": "The task does not exist, or was deleted or canceled.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } }, "delete": { "tags": ["Task management"], "summary": "Cancel or delete a task", "description": "Tasks that are running, pending, or throttled can be canceled by invoking this method. Invoking this method for other tasks will delete them.\n\nThe 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.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nawait client.tasks.delete('17f20503-6c24-4c16-946b-35dbbce2af2f');" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\nclient.tasks.delete(id='17f20503-6c24-4c16-946b-35dbbce2af2f')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "description": "The ID of a previously-submitted task that has not been canceled or deleted." }, { "$ref": "#/components/parameters/X-Runway-Version" } ], "responses": { "204": { "description": "This endpoint will produce a 204 No Content response indicating successful cancellation or deletion. Calling this endpoint for tasks which have already been deleted or aborted will result in a 404: for idempotency purposes, it is safe to ignore these 404 errors." } } } }, "/v1/image_to_video": { "post": { "tags": ["Start generating"], "summary": "Image to video", "description": "This endpoint will start a new task to generate a video from an image.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nconst task = await client.imageToVideo\n .create({\n model: 'gen4_turbo',\n promptImage: 'https://example.com/bunny.jpg',\n promptText: 'A cute bunny hopping in a meadow',\n duration: 10,\n })\n .waitForTaskOutput();\n\nconsole.log(task);" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\ntask = client.image_to_video.create(\n model='gen4_turbo',\n prompt_image='https://example.com/bunny.jpg',\n prompt_text='A cute bunny hopping in a meadow',\n duration=10,\n).wait_for_task_output()\n\nprint(task)" } ], "parameters": [{ "$ref": "#/components/parameters/X-Runway-Version" }], "requestBody": { "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "oneOf": [ { "title": "gen4.5", "type": "object", "properties": { "promptText": { "description": "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.", "type": "string", "minLength": 1, "maxLength": 1000 }, "promptImage": { "anyOf": [ { "description": "A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "anyOf": [ { "description": "A HTTPS URL.", "example": "https://example.com/file", "type": "string", "minLength": 13, "maxLength": 2048, "pattern": "^https:\\/\\/.*" }, { "description": "A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.", "example": "runway://", "type": "string", "minLength": 13, "maxLength": 5000, "pattern": "^runway:\\/\\/.*" }, { "description": "A data URI containing encoded media.", "example": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "type": "string", "minLength": 13, "maxLength": 5242880, "pattern": "^data:image\\/.*" } ] }, { "title": "PromptImages", "description": "An array of objects representing images to be used in the output video. Only a `first` frame is supported.", "minItems": 1, "maxItems": 1, "type": "array", "items": { "title": "PromptImage", "x-stainless-variantName": "PromptImage", "type": "object", "properties": { "uri": { "description": "A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "anyOf": [ { "description": "A HTTPS URL.", "example": "https://example.com/file", "type": "string", "minLength": 13, "maxLength": 2048, "pattern": "^https:\\/\\/.*" }, { "description": "A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.", "example": "runway://", "type": "string", "minLength": 13, "maxLength": 5000, "pattern": "^runway:\\/\\/.*" }, { "description": "A data URI containing encoded media.", "example": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "type": "string", "minLength": 13, "maxLength": 5242880, "pattern": "^data:image\\/.*" } ] }, "position": { "description": "The position of the image in the output video. \"first\" will use the image as the first frame of the video.", "type": "string", "const": "first" } }, "required": ["uri", "position"] } } ] }, "seed": { "description": "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.", "type": "integer", "minimum": 0, "maximum": 4294967295 }, "ratio": { "description": "The resolution of the output video.", "type": "string", "enum": [ "1280:720", "720:1280", "1104:832", "960:960", "832:1104", "1584:672" ] }, "duration": { "description": "The number of seconds of duration for the output video. Must be an integer from 2 to 10.", "type": "integer", "minimum": 2, "maximum": 10 }, "contentModeration": { "description": "Settings that affect the behavior of the content moderation system.", "type": "object", "properties": { "publicFigureThreshold": { "description": "When set to `low`, the content moderation system will be less strict about preventing generations that include recognizable public figures.", "type": "string", "enum": ["auto", "low"] } } }, "model": { "type": "string", "const": "gen4.5" } }, "required": [ "promptText", "promptImage", "ratio", "duration", "model" ] }, { "title": "gen4_turbo", "type": "object", "properties": { "promptText": { "description": "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.", "type": "string", "minLength": 1, "maxLength": 1000 }, "promptImage": { "anyOf": [ { "description": "A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "anyOf": [ { "description": "A HTTPS URL.", "example": "https://example.com/file", "type": "string", "minLength": 13, "maxLength": 2048, "pattern": "^https:\\/\\/.*" }, { "description": "A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.", "example": "runway://", "type": "string", "minLength": 13, "maxLength": 5000, "pattern": "^runway:\\/\\/.*" }, { "description": "A data URI containing encoded media.", "example": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "type": "string", "minLength": 13, "maxLength": 5242880, "pattern": "^data:image\\/.*" } ] }, { "title": "PromptImages", "description": "An array of objects representing images to be used in the output video. Only a `first` frame is supported.", "minItems": 1, "maxItems": 1, "type": "array", "items": { "title": "PromptImage", "x-stainless-variantName": "PromptImage", "type": "object", "properties": { "uri": { "description": "A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "anyOf": [ { "description": "A HTTPS URL.", "example": "https://example.com/file", "type": "string", "minLength": 13, "maxLength": 2048, "pattern": "^https:\\/\\/.*" }, { "description": "A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.", "example": "runway://", "type": "string", "minLength": 13, "maxLength": 5000, "pattern": "^runway:\\/\\/.*" }, { "description": "A data URI containing encoded media.", "example": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "type": "string", "minLength": 13, "maxLength": 5242880, "pattern": "^data:image\\/.*" } ] }, "position": { "description": "The position of the image in the output video. \"first\" will use the image as the first frame of the video.", "type": "string", "const": "first" } }, "required": ["uri", "position"] } } ] }, "seed": { "description": "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.", "type": "integer", "minimum": 0, "maximum": 4294967295 }, "ratio": { "description": "The resolution of the output video.", "type": "string", "enum": [ "1280:720", "720:1280", "1104:832", "832:1104", "960:960", "1584:672" ] }, "duration": { "description": "The number of seconds of duration for the output video.", "type": "integer", "minimum": 2, "maximum": 10 }, "contentModeration": { "description": "Settings that affect the behavior of the content moderation system.", "type": "object", "properties": { "publicFigureThreshold": { "description": "When set to `low`, the content moderation system will be less strict about preventing generations that include recognizable public figures.", "type": "string", "enum": ["auto", "low"] } } }, "model": { "type": "string", "const": "gen4_turbo" } }, "required": ["promptImage", "ratio", "model"] }, { "title": "veo3.1", "type": "object", "properties": { "promptText": { "description": "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.", "type": "string", "minLength": 1, "maxLength": 1000 }, "promptImage": { "description": "You may specify an image to use as the first frame of the output video, or an array with a first frame and optionally a last frame. This model does not support generating with only a last frame.", "anyOf": [ { "description": "A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "anyOf": [ { "description": "A HTTPS URL.", "example": "https://example.com/file", "type": "string", "minLength": 13, "maxLength": 2048, "pattern": "^https:\\/\\/.*" }, { "description": "A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.", "example": "runway://", "type": "string", "minLength": 13, "maxLength": 5000, "pattern": "^runway:\\/\\/.*" }, { "description": "A data URI containing encoded media.", "example": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "type": "string", "minLength": 13, "maxLength": 5242880, "pattern": "^data:image\\/.*" } ] }, { "title": "PromptImages", "description": "An array of objects representing images to be used in the output video. No two provided images may have the same `position` value.", "example": [ { "uri": "https://example.com/firstFrame.jpg", "position": "first" }, { "uri": "https://example.com/lastFrame.jpg", "position": "last" } ], "minItems": 1, "maxItems": 2, "type": "array", "items": { "title": "PromptImage", "x-stainless-variantName": "PromptImage", "type": "object", "properties": { "uri": { "description": "A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "anyOf": [ { "description": "A HTTPS URL.", "example": "https://example.com/file", "type": "string", "minLength": 13, "maxLength": 2048, "pattern": "^https:\\/\\/.*" }, { "description": "A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.", "example": "runway://", "type": "string", "minLength": 13, "maxLength": 5000, "pattern": "^runway:\\/\\/.*" }, { "description": "A data URI containing encoded media.", "example": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "type": "string", "minLength": 13, "maxLength": 5242880, "pattern": "^data:image\\/.*" } ] }, "position": { "description": "The position of the image in the output video. \"first\" will use the image as the first frame of the video, \"last\" will use the image as the last frame of the video.", "type": "string", "enum": ["first", "last"] } }, "required": ["uri", "position"] } } ] }, "ratio": { "description": "The resolution of the output video.", "type": "string", "enum": [ "1280:720", "720:1280", "1080:1920", "1920:1080" ] }, "audio": { "description": "Whether to generate audio for the video. Audio inclusion affects pricing.", "default": true, "type": "boolean" }, "duration": { "description": "The number of seconds of duration for the output video.", "type": "number", "enum": [4, 6, 8] }, "model": { "type": "string", "const": "veo3.1" } }, "required": ["promptImage", "ratio", "model"] }, { "title": "gen3a_turbo", "type": "object", "properties": { "promptText": { "description": "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.", "example": "A beautiful sunset over a calm ocean.", "type": "string", "minLength": 1, "maxLength": 1000 }, "promptImage": { "anyOf": [ { "description": "A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "anyOf": [ { "description": "A HTTPS URL.", "example": "https://example.com/file", "type": "string", "minLength": 13, "maxLength": 2048, "pattern": "^https:\\/\\/.*" }, { "description": "A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.", "example": "runway://", "type": "string", "minLength": 13, "maxLength": 5000, "pattern": "^runway:\\/\\/.*" }, { "description": "A data URI containing encoded media.", "example": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "type": "string", "minLength": 13, "maxLength": 5242880, "pattern": "^data:image\\/.*" } ] }, { "title": "PromptImages", "description": "An array of objects representing images to be used in the output video. No two provided images may have the same `position` value.", "example": [ { "uri": "https://example.com/firstFrame.jpg", "position": "first" }, { "uri": "https://example.com/lastFrame.jpg", "position": "last" } ], "minItems": 1, "maxItems": 2, "type": "array", "items": { "title": "PromptImage", "x-stainless-variantName": "PromptImage", "type": "object", "properties": { "uri": { "description": "A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "anyOf": [ { "description": "A HTTPS URL.", "example": "https://example.com/file", "type": "string", "minLength": 13, "maxLength": 2048, "pattern": "^https:\\/\\/.*" }, { "description": "A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.", "example": "runway://", "type": "string", "minLength": 13, "maxLength": 5000, "pattern": "^runway:\\/\\/.*" }, { "description": "A data URI containing encoded media.", "example": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "type": "string", "minLength": 13, "maxLength": 5242880, "pattern": "^data:image\\/.*" } ] }, "position": { "description": "The position of the image in the output video. \"first\" will use the image as the first frame of the video, \"last\" will use the image as the last frame of the video.", "type": "string", "enum": ["first", "last"] } }, "required": ["uri", "position"] } } ] }, "seed": { "description": "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.", "type": "integer", "minimum": 0, "maximum": 4294967295 }, "duration": { "description": "The duration of the output video in seconds.", "example": 5, "default": 10, "type": "number", "enum": [5, 10] }, "ratio": { "description": "The resolution of the output video.", "example": "1280:768", "type": "string", "enum": ["768:1280", "1280:768"] }, "contentModeration": { "description": "Settings that affect the behavior of the content moderation system.", "example": { "publicFigureThreshold": "auto" }, "type": "object", "properties": { "publicFigureThreshold": { "description": "When set to `low`, the content moderation system will be less strict about preventing generations that include recognizable public figures.", "type": "string", "enum": ["auto", "low"] } } }, "model": { "type": "string", "const": "gen3a_turbo" } }, "required": ["promptText", "promptImage", "model"] }, { "title": "veo3.1_fast", "type": "object", "properties": { "promptText": { "description": "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.", "type": "string", "minLength": 1, "maxLength": 1000 }, "promptImage": { "description": "You may specify an image to use as the first frame of the output video, or an array with a first frame and optionally a last frame. This model does not support generating with only a last frame.", "anyOf": [ { "description": "A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "anyOf": [ { "description": "A HTTPS URL.", "example": "https://example.com/file", "type": "string", "minLength": 13, "maxLength": 2048, "pattern": "^https:\\/\\/.*" }, { "description": "A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.", "example": "runway://", "type": "string", "minLength": 13, "maxLength": 5000, "pattern": "^runway:\\/\\/.*" }, { "description": "A data URI containing encoded media.", "example": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "type": "string", "minLength": 13, "maxLength": 5242880, "pattern": "^data:image\\/.*" } ] }, { "title": "PromptImages", "description": "An array of objects representing images to be used in the output video. No two provided images may have the same `position` value.", "example": [ { "uri": "https://example.com/firstFrame.jpg", "position": "first" }, { "uri": "https://example.com/lastFrame.jpg", "position": "last" } ], "minItems": 1, "maxItems": 2, "type": "array", "items": { "title": "PromptImage", "x-stainless-variantName": "PromptImage", "type": "object", "properties": { "uri": { "description": "A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "anyOf": [ { "description": "A HTTPS URL.", "example": "https://example.com/file", "type": "string", "minLength": 13, "maxLength": 2048, "pattern": "^https:\\/\\/.*" }, { "description": "A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.", "example": "runway://", "type": "string", "minLength": 13, "maxLength": 5000, "pattern": "^runway:\\/\\/.*" }, { "description": "A data URI containing encoded media.", "example": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "type": "string", "minLength": 13, "maxLength": 5242880, "pattern": "^data:image\\/.*" } ] }, "position": { "description": "The position of the image in the output video. \"first\" will use the image as the first frame of the video, \"last\" will use the image as the last frame of the video.", "type": "string", "enum": ["first", "last"] } }, "required": ["uri", "position"] } } ] }, "ratio": { "description": "The resolution of the output video.", "type": "string", "enum": [ "1280:720", "720:1280", "1080:1920", "1920:1080" ] }, "audio": { "description": "Whether to generate audio for the video. Audio inclusion affects pricing.", "default": true, "type": "boolean" }, "duration": { "description": "The number of seconds of duration for the output video.", "type": "number", "enum": [4, 6, 8] }, "model": { "type": "string", "const": "veo3.1_fast" } }, "required": ["promptImage", "ratio", "model"] }, { "title": "veo3", "type": "object", "properties": { "promptText": { "description": "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.", "type": "string", "minLength": 1, "maxLength": 1000 }, "promptImage": { "anyOf": [ { "description": "A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "anyOf": [ { "description": "A HTTPS URL.", "example": "https://example.com/file", "type": "string", "minLength": 13, "maxLength": 2048, "pattern": "^https:\\/\\/.*" }, { "description": "A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.", "example": "runway://", "type": "string", "minLength": 13, "maxLength": 5000, "pattern": "^runway:\\/\\/.*" }, { "description": "A data URI containing encoded media.", "example": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "type": "string", "minLength": 13, "maxLength": 5242880, "pattern": "^data:image\\/.*" } ] }, { "title": "PromptImages", "description": "An array of objects representing images to be used in the output video. Only a `first` frame is supported.", "minItems": 1, "maxItems": 1, "type": "array", "items": { "title": "PromptImage", "x-stainless-variantName": "PromptImage", "type": "object", "properties": { "uri": { "description": "A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "anyOf": [ { "description": "A HTTPS URL.", "example": "https://example.com/file", "type": "string", "minLength": 13, "maxLength": 2048, "pattern": "^https:\\/\\/.*" }, { "description": "A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.", "example": "runway://", "type": "string", "minLength": 13, "maxLength": 5000, "pattern": "^runway:\\/\\/.*" }, { "description": "A data URI containing encoded media.", "example": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "type": "string", "minLength": 13, "maxLength": 5242880, "pattern": "^data:image\\/.*" } ] }, "position": { "description": "The position of the image in the output video. \"first\" will use the image as the first frame of the video.", "type": "string", "const": "first" } }, "required": ["uri", "position"] } } ] }, "duration": { "description": "The number of seconds of duration for the output video.", "type": "number", "const": 8 }, "ratio": { "description": "The resolution of the output video.", "type": "string", "enum": [ "1280:720", "720:1280", "1080:1920", "1920:1080" ] }, "model": { "type": "string", "const": "veo3" } }, "required": ["promptImage", "duration", "ratio", "model"] } ], "discriminator": { "propertyName": "model" } } } } }, "responses": { "200": { "description": "The task that was created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "The ID of the task that was created. Use this to retrieve the task later.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" } }, "required": ["id"], "additionalProperties": false } } } }, "429": { "description": "You have exceeded the rate limit for this endpoint.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/v1/text_to_video": { "post": { "tags": ["Start generating"], "summary": "Text to video", "description": "This endpoint will start a new task to generate a video from a text prompt.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nconst task = await client.textToVideo\n .create({\n model: 'veo3.1',\n promptText: 'A cute bunny hopping in a meadow',\n ratio: '1280:720',\n duration: 8,\n })\n .waitForTaskOutput();\n\nconsole.log(task);" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\ntask = client.text_to_video.create(\n model='veo3.1',\n prompt_text='A cute bunny hopping in a meadow',\n ratio='1280:720',\n duration=8,\n).wait_for_task_output()\n\nprint(task)" } ], "parameters": [{ "$ref": "#/components/parameters/X-Runway-Version" }], "requestBody": { "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "oneOf": [ { "title": "gen4.5", "type": "object", "properties": { "promptText": { "description": "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.", "type": "string", "minLength": 1, "maxLength": 1000 }, "ratio": { "description": "The resolution of the output video.", "type": "string", "enum": ["1280:720", "720:1280"] }, "duration": { "description": "The number of seconds of duration for the output video. Must be an integer from 2 to 10.", "type": "integer", "minimum": 2, "maximum": 10 }, "seed": { "description": "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.", "type": "integer", "minimum": 0, "maximum": 4294967295 }, "contentModeration": { "description": "Settings that affect the behavior of the content moderation system.", "type": "object", "properties": { "publicFigureThreshold": { "description": "When set to `low`, the content moderation system will be less strict about preventing generations that include recognizable public figures.", "type": "string", "enum": ["auto", "low"] } } }, "model": { "type": "string", "const": "gen4.5" } }, "required": ["promptText", "ratio", "duration", "model"] }, { "title": "veo3.1", "type": "object", "properties": { "promptText": { "description": "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.", "type": "string", "minLength": 1, "maxLength": 1000 }, "ratio": { "description": "The resolution of the output video.", "type": "string", "enum": [ "1280:720", "720:1280", "1080:1920", "1920:1080" ] }, "audio": { "description": "Whether to generate audio for the video. Audio inclusion affects pricing.", "default": true, "type": "boolean" }, "duration": { "description": "The number of seconds of duration for the output video.", "type": "number", "enum": [4, 6, 8] }, "model": { "type": "string", "const": "veo3.1" } }, "required": ["promptText", "ratio", "model"] }, { "title": "veo3.1_fast", "type": "object", "properties": { "promptText": { "description": "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.", "type": "string", "minLength": 1, "maxLength": 1000 }, "ratio": { "description": "The resolution of the output video.", "type": "string", "enum": [ "1280:720", "720:1280", "1080:1920", "1920:1080" ] }, "audio": { "description": "Whether to generate audio for the video. Audio inclusion affects pricing.", "default": true, "type": "boolean" }, "duration": { "description": "The number of seconds of duration for the output video.", "type": "number", "enum": [4, 6, 8] }, "model": { "type": "string", "const": "veo3.1_fast" } }, "required": ["promptText", "ratio", "model"] }, { "title": "veo3", "type": "object", "properties": { "promptText": { "description": "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.", "type": "string", "minLength": 1, "maxLength": 1000 }, "duration": { "description": "The number of seconds of duration for the output video.", "type": "number", "const": 8 }, "ratio": { "description": "The resolution of the output video.", "type": "string", "enum": [ "1280:720", "720:1280", "1080:1920", "1920:1080" ] }, "model": { "type": "string", "const": "veo3" } }, "required": ["promptText", "duration", "ratio", "model"] } ], "discriminator": { "propertyName": "model" } } } } }, "responses": { "200": { "description": "The task that was created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "The ID of the task that was created. Use this to retrieve the task later.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" } }, "required": ["id"], "additionalProperties": false } } } }, "429": { "description": "You have exceeded the rate limit for this endpoint.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/v1/video_to_video": { "post": { "tags": ["Start generating"], "summary": "Video to video", "description": "This endpoint will start a new task to generate a video from a video.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nconst task = await client.videoToVideo\n .create({\n model: 'gen4_aleph',\n videoUri: 'https://example.com/bunny.mp4',\n promptText: 'string',\n references: [\n {\n type: 'image',\n uri: 'https://example.com/easter-scene.jpg',\n },\n ],\n ratio: '1280:720',\n })\n .waitForTaskOutput();\n\nconsole.log(task);" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\ntask = client.video_to_video.create(\n model='gen4_aleph',\n video_uri='https://example.com/bunny.mp4',\n prompt_text='string',\n references=[\n {\n 'type': 'image',\n 'uri': 'https://example.com/easter-scene.jpg',\n },\n ],\n ratio='1280:720',\n).wait_for_task_output()\n\nprint(task)" } ], "parameters": [{ "$ref": "#/components/parameters/X-Runway-Version" }], "requestBody": { "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "oneOf": [ { "title": "gen4_aleph", "type": "object", "properties": { "videoUri": { "description": "A HTTPS URL, Runway or data URI containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information.", "example": "https://example.com/video.mp4", "anyOf": [ { "description": "A HTTPS URL.", "example": "https://example.com/file", "type": "string", "minLength": 13, "maxLength": 2048, "pattern": "^https:\\/\\/.*" }, { "description": "A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.", "example": "runway://", "type": "string", "minLength": 13, "maxLength": 5000, "pattern": "^runway:\\/\\/.*" }, { "description": "A data URI containing encoded media.", "example": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "type": "string", "minLength": 13, "maxLength": 16777216, "pattern": "^data:video\\/.*" } ] }, "promptText": { "description": "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.", "type": "string", "minLength": 1, "maxLength": 1000 }, "ratio": { "description": "Deprecated. This field is ignored. The resolution of the output video is determined by the input video.", "deprecated": true, "type": "string", "enum": [ "1280:720", "720:1280", "1104:832", "960:960", "832:1104", "1584:672", "848:480", "640:480" ] }, "seed": { "description": "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.", "type": "integer", "minimum": 0, "maximum": 4294967295 }, "references": { "description": "An array of references. Currently up to one reference is supported. See [our docs](/assets/inputs#images) on image inputs for more information.", "type": "array", "items": { "oneOf": [ { "title": "ImageReference", "description": "Passing an image reference allows the model to emulate the style or content of the reference in the output.", "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "uri": { "description": "A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "anyOf": [ { "description": "A HTTPS URL.", "example": "https://example.com/file", "type": "string", "minLength": 13, "maxLength": 2048, "pattern": "^https:\\/\\/.*" }, { "description": "A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.", "example": "runway://", "type": "string", "minLength": 13, "maxLength": 5000, "pattern": "^runway:\\/\\/.*" }, { "description": "A data URI containing encoded media.", "example": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "type": "string", "minLength": 13, "maxLength": 5242880, "pattern": "^data:image\\/.*" } ] } }, "required": ["type", "uri"] } ], "discriminator": { "propertyName": "type" } } }, "contentModeration": { "description": "Settings that affect the behavior of the content moderation system.", "type": "object", "properties": { "publicFigureThreshold": { "description": "When set to `low`, the content moderation system will be less strict about preventing generations that include recognizable public figures.", "type": "string", "enum": ["auto", "low"] } } }, "model": { "type": "string", "const": "gen4_aleph" } }, "required": ["videoUri", "promptText", "model"] } ], "discriminator": { "propertyName": "model" } } } } }, "responses": { "200": { "description": "The task that was created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "The ID of the task that was created. Use this to retrieve the task later.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" } }, "required": ["id"], "additionalProperties": false } } } }, "429": { "description": "You have exceeded the rate limit for this endpoint.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/v1/text_to_image": { "post": { "tags": ["Start generating"], "summary": "Text/Image to Image", "description": "This endpoint will start a new task to generate images from text and/or image(s)", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nconst task = await client.textToImage\n .create({\n model: 'gen4_image',\n promptText: 'A serene landscape with mountains',\n ratio: '1360:768',\n })\n .waitForTaskOutput();\n\nconsole.log(task);" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\ntask = client.text_to_image.create(\n model='gen4_image',\n prompt_text='A serene landscape with mountains',\n ratio='1360:768',\n).wait_for_task_output()\n\nprint(task)" } ], "parameters": [{ "$ref": "#/components/parameters/X-Runway-Version" }], "requestBody": { "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "oneOf": [ { "title": "gen4_image_turbo", "type": "object", "properties": { "promptText": { "description": "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.", "type": "string", "minLength": 1, "maxLength": 1000 }, "seed": { "description": "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.", "type": "integer", "minimum": 0, "maximum": 4294967295 }, "ratio": { "description": "The resolution of the output image.", "type": "string", "enum": [ "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" ] }, "referenceImages": { "description": "An array of one to three images to be used as references for the generated image output.", "minItems": 1, "maxItems": 3, "type": "array", "items": { "title": "ReferenceImage", "type": "object", "properties": { "uri": { "description": "A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "anyOf": [ { "description": "A HTTPS URL.", "example": "https://example.com/file", "type": "string", "minLength": 13, "maxLength": 2048, "pattern": "^https:\\/\\/.*" }, { "description": "A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.", "example": "runway://", "type": "string", "minLength": 13, "maxLength": 5000, "pattern": "^runway:\\/\\/.*" }, { "description": "A data URI containing encoded media.", "example": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "type": "string", "minLength": 13, "maxLength": 5242880, "pattern": "^data:image\\/.*" } ] }, "tag": { "description": "A tag to identify the reference image. This is used to reference the image in prompt text.", "type": "string", "minLength": 3, "maxLength": 16, "pattern": "^[a-z][a-z0-9_]+$" } }, "required": ["uri"] } }, "contentModeration": { "description": "Settings that affect the behavior of the content moderation system.", "type": "object", "properties": { "publicFigureThreshold": { "description": "When set to `low`, the content moderation system will be less strict about preventing generations that include recognizable public figures.", "type": "string", "enum": ["auto", "low"] } } }, "model": { "type": "string", "const": "gen4_image_turbo" } }, "required": [ "promptText", "ratio", "referenceImages", "model" ] }, { "title": "gen4_image", "type": "object", "properties": { "promptText": { "description": "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.", "type": "string", "minLength": 1, "maxLength": 1000 }, "seed": { "description": "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.", "type": "integer", "minimum": 0, "maximum": 4294967295 }, "ratio": { "description": "The resolution of the output image.", "type": "string", "enum": [ "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" ] }, "referenceImages": { "description": "An array of up to three images to be used as references for the generated image output.", "maxItems": 3, "type": "array", "items": { "title": "ReferenceImage", "type": "object", "properties": { "uri": { "description": "A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "anyOf": [ { "description": "A HTTPS URL.", "example": "https://example.com/file", "type": "string", "minLength": 13, "maxLength": 2048, "pattern": "^https:\\/\\/.*" }, { "description": "A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.", "example": "runway://", "type": "string", "minLength": 13, "maxLength": 5000, "pattern": "^runway:\\/\\/.*" }, { "description": "A data URI containing encoded media.", "example": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "type": "string", "minLength": 13, "maxLength": 5242880, "pattern": "^data:image\\/.*" } ] }, "tag": { "description": "A tag to identify the reference image. This is used to reference the image in prompt text.", "type": "string", "minLength": 3, "maxLength": 16, "pattern": "^[a-z][a-z0-9_]+$" } }, "required": ["uri"] } }, "contentModeration": { "description": "Settings that affect the behavior of the content moderation system.", "type": "object", "properties": { "publicFigureThreshold": { "description": "When set to `low`, the content moderation system will be less strict about preventing generations that include recognizable public figures.", "type": "string", "enum": ["auto", "low"] } } }, "model": { "type": "string", "const": "gen4_image" } }, "required": ["promptText", "ratio", "model"] }, { "title": "gpt_image_2", "type": "object", "properties": { "promptText": { "description": "A non-empty string up to 32,000 characters describing the desired image.", "type": "string", "minLength": 1, "maxLength": 32000 }, "ratio": { "description": "The resolution of the output image, expressed as `:`. Use `auto` to let the model choose.", "type": "string", "enum": [ "2048:880", "1920:1088", "1920:1280", "1920:1440", "1920:1536", "1920:1920", "1536:1920", "1440:1920", "1280:1920", "1088:1920", "2912:1248", "2560:1440", "2560:1712", "2560:1920", "2560:2048", "2560:2560", "2048:2560", "1920:2560", "1712:2560", "1440:2560", "3840:1648", "3840:2160", "3504:2336", "3264:2448", "3200:2560", "2880:2880", "2560:3200", "2448:3264", "2336:3504", "2160:3840", "auto" ] }, "quality": { "description": "Rendering quality. Higher qualities consume more credits. Defaults to `high`.", "type": "string", "enum": ["low", "medium", "high", "auto"] }, "background": { "description": "Background treatment. Defaults to `auto`, which lets the model pick. `transparent` is not supported by this model.", "type": "string", "enum": ["opaque", "auto"] }, "referenceImages": { "description": "An array of up to 16 images to be used as references for the generated image output.", "maxItems": 16, "type": "array", "items": { "title": "GptImage2ReferenceImage", "type": "object", "properties": { "uri": { "description": "A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "anyOf": [ { "description": "A HTTPS URL.", "example": "https://example.com/file", "type": "string", "minLength": 13, "maxLength": 2048, "pattern": "^https:\\/\\/.*" }, { "description": "A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.", "example": "runway://", "type": "string", "minLength": 13, "maxLength": 5000, "pattern": "^runway:\\/\\/.*" }, { "description": "A data URI containing encoded media.", "example": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "type": "string", "minLength": 13, "maxLength": 5242880, "pattern": "^data:image\\/.*" } ] }, "tag": { "description": "A tag to identify the reference image. This may be used to reference the image in prompt text.", "type": "string", "minLength": 3, "maxLength": 16, "pattern": "^[a-z][a-z0-9_]+$" } }, "required": ["uri"], "additionalProperties": false } }, "outputCount": { "description": "The number of images to generate (1-10). Increasing this number will affect the number of credits consumed by the generation.", "type": "integer", "minimum": 1, "maximum": 10 }, "model": { "type": "string", "const": "gpt_image_2" } }, "required": ["promptText", "ratio", "model"], "additionalProperties": false }, { "title": "gemini_image3_pro", "type": "object", "properties": { "promptText": { "description": "A non-empty string up to 5,500 characters (measured in UTF-16 code units). This should describe in detail what should appear in the output.", "type": "string", "minLength": 1, "maxLength": 5500 }, "ratio": { "description": "The resolution of the output image.", "type": "string", "enum": [ "1344:768", "768:1344", "1024:1024", "1184:864", "864:1184", "1536:672", "832:1248", "1248:832", "896:1152", "1152:896", "2048:2048", "1696:2528", "2528:1696", "1792:2400", "2400:1792", "1856:2304", "2304:1856", "1536:2752", "2752:1536", "3168:1344", "4096:4096", "3392:5056", "5056:3392", "3584:4800", "4800:3584", "3712:4608", "4608:3712", "3072:5504", "5504:3072", "6336:2688" ] }, "referenceImages": { "description": "An array of up to 14 images to be used as references for the generated image output. Up to five of those images can pass `subject: \"human\"` to maintain character consistency, and up to nine of those images can pass `subject: \"object\"` with high-fidelity images of objects to include in the output.", "maxItems": 14, "type": "array", "items": { "title": "Gemini3ProReferenceImage", "type": "object", "properties": { "uri": { "description": "A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "anyOf": [ { "description": "A HTTPS URL.", "example": "https://example.com/file", "type": "string", "minLength": 13, "maxLength": 2048, "pattern": "^https:\\/\\/.*" }, { "description": "A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.", "example": "runway://", "type": "string", "minLength": 13, "maxLength": 5000, "pattern": "^runway:\\/\\/.*" }, { "description": "A data URI containing encoded media.", "example": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "type": "string", "minLength": 13, "maxLength": 5242880, "pattern": "^data:image\\/.*" } ] }, "tag": { "description": "A tag to identify the reference image. This is used to reference the image in prompt text.", "type": "string", "minLength": 3, "maxLength": 16, "pattern": "^[a-z][a-z0-9_]+$" }, "subject": { "description": "Whether this is a reference of a human subject (for character consistency) or an object that appears in the output.", "default": "object", "type": "string", "enum": ["object", "human"] } }, "required": ["uri"], "additionalProperties": false } }, "outputCount": { "description": "The number of images to generate. Increasing this number will affect the number of credits consumed by the generation. Up to four images can be generated at once.", "type": "number", "enum": [1, 4] }, "model": { "type": "string", "const": "gemini_image3_pro" } }, "required": ["promptText", "ratio", "model"], "additionalProperties": false }, { "title": "gemini_2.5_flash", "type": "object", "properties": { "promptText": { "description": "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.", "type": "string", "minLength": 1, "maxLength": 1000 }, "ratio": { "description": "The resolution of the output image.", "type": "string", "enum": [ "1344:768", "768:1344", "1024:1024", "1184:864", "864:1184", "1536:672", "832:1248", "1248:832", "896:1152", "1152:896" ] }, "referenceImages": { "description": "An array of up to three images to be used as references for the generated image output.", "maxItems": 3, "type": "array", "items": { "title": "ReferenceImage", "type": "object", "properties": { "uri": { "description": "A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "anyOf": [ { "description": "A HTTPS URL.", "example": "https://example.com/file", "type": "string", "minLength": 13, "maxLength": 2048, "pattern": "^https:\\/\\/.*" }, { "description": "A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.", "example": "runway://", "type": "string", "minLength": 13, "maxLength": 5000, "pattern": "^runway:\\/\\/.*" }, { "description": "A data URI containing encoded media.", "example": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "type": "string", "minLength": 13, "maxLength": 5242880, "pattern": "^data:image\\/.*" } ] }, "tag": { "description": "A tag to identify the reference image. This is used to reference the image in prompt text.", "type": "string", "minLength": 3, "maxLength": 16, "pattern": "^[a-z][a-z0-9_]+$" } }, "required": ["uri"] } }, "model": { "type": "string", "const": "gemini_2.5_flash" } }, "required": ["promptText", "ratio", "model"] } ], "discriminator": { "propertyName": "model" } } } } }, "responses": { "200": { "description": "The task that was created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "The ID of the task that was created. Use this to retrieve the task later.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" } }, "required": ["id"], "additionalProperties": false } } } }, "429": { "description": "You have exceeded the rate limit for this endpoint.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/v1/character_performance": { "post": { "tags": ["Start generating"], "summary": "Control a character", "description": "This endpoint will start a new task to control a character's facial expressions and body movements using a reference video.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nconst task = await client.characterPerformance\n .create({\n model: 'act_two',\n character: {\n type: 'video',\n uri: 'https://example.com/posedCharacter.mp4',\n },\n reference: {\n type: 'video',\n uri: 'https://example.com/actorPerformance.mp4',\n },\n ratio: '1280:720',\n })\n .waitForTaskOutput();\nconsole.log(task);" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\ntask = client.character_performance.create(\n model='act_two',\n character={\n 'type': 'video',\n 'uri': 'https://example.com/posedCharacter.mp4',\n },\n reference={\n 'type': 'video',\n 'uri': 'https://example.com/actorPerformance.mp4',\n },\n ratio='1280:720',\n).wait_for_task_output()\n\nprint(task)" } ], "parameters": [{ "$ref": "#/components/parameters/X-Runway-Version" }], "requestBody": { "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "oneOf": [ { "title": "act_two", "type": "object", "properties": { "seed": { "description": "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.", "type": "integer", "minimum": 0, "maximum": 4294967295 }, "character": { "description": "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.", "oneOf": [ { "title": "CharacterImage", "description": "An image of your character. In the output, the character will use the reference video performance in its original static environment.", "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "uri": { "description": "A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "anyOf": [ { "description": "A HTTPS URL.", "example": "https://example.com/file", "type": "string", "minLength": 13, "maxLength": 2048, "pattern": "^https:\\/\\/.*" }, { "description": "A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.", "example": "runway://", "type": "string", "minLength": 13, "maxLength": 5000, "pattern": "^runway:\\/\\/.*" }, { "description": "A data URI containing encoded media.", "example": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "type": "string", "minLength": 13, "maxLength": 5242880, "pattern": "^data:image\\/.*" } ] } }, "required": ["type", "uri"] }, { "title": "CharacterVideo", "description": "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.", "type": "object", "properties": { "type": { "type": "string", "const": "video" }, "uri": { "description": "A HTTPS URL, Runway or data URI containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information.", "example": "https://example.com/video.mp4", "anyOf": [ { "description": "A HTTPS URL.", "example": "https://example.com/file", "type": "string", "minLength": 13, "maxLength": 2048, "pattern": "^https:\\/\\/.*" }, { "description": "A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.", "example": "runway://", "type": "string", "minLength": 13, "maxLength": 5000, "pattern": "^runway:\\/\\/.*" }, { "description": "A data URI containing encoded media.", "example": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "type": "string", "minLength": 13, "maxLength": 16777216, "pattern": "^data:video\\/.*" } ] } }, "required": ["type", "uri"] } ], "discriminator": { "propertyName": "type" } }, "reference": { "description": "The reference video containing the performance to apply to the character.", "example": { "type": "video", "uri": "https://example.com/reference-performance.mp4" }, "oneOf": [ { "title": "CharacterReferenceVideo", "description": "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.", "type": "object", "properties": { "type": { "type": "string", "const": "video" }, "uri": { "description": "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](/assets/inputs#videos) on video inputs for more information.", "example": "https://example.com/reference-performance.mp4", "anyOf": [ { "description": "A HTTPS URL.", "example": "https://example.com/file", "type": "string", "minLength": 13, "maxLength": 2048, "pattern": "^https:\\/\\/.*" }, { "description": "A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.", "example": "runway://", "type": "string", "minLength": 13, "maxLength": 5000, "pattern": "^runway:\\/\\/.*" }, { "description": "A data URI containing encoded media.", "example": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "type": "string", "minLength": 13, "maxLength": 16777216, "pattern": "^data:video\\/.*" } ] } }, "required": ["type", "uri"] } ], "discriminator": { "propertyName": "type" } }, "bodyControl": { "description": "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.", "example": true, "type": "boolean" }, "expressionIntensity": { "description": "An integer between 1 and 5 (inclusive). A larger value increases the intensity of the character's expression.", "example": 3, "default": 3, "type": "integer", "minimum": 1, "maximum": 5 }, "ratio": { "description": "The resolution of the output video.", "example": "1280:720", "type": "string", "enum": [ "1280:720", "720:1280", "960:960", "1104:832", "832:1104", "1584:672" ] }, "contentModeration": { "description": "Settings that affect the behavior of the content moderation system.", "example": { "publicFigureThreshold": "auto" }, "type": "object", "properties": { "publicFigureThreshold": { "description": "When set to `low`, the content moderation system will be less strict about preventing generations that include recognizable public figures.", "type": "string", "enum": ["auto", "low"] } } }, "model": { "type": "string", "const": "act_two" } }, "required": ["character", "reference", "model"] } ], "discriminator": { "propertyName": "model" } } } } }, "responses": { "200": { "description": "The task that was created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "The ID of the task that was created. Use this to retrieve the task later.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" } }, "required": ["id"], "additionalProperties": false } } } }, "429": { "description": "You have exceeded the rate limit for this endpoint.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/v1/sound_effect": { "post": { "tags": ["Start generating"], "summary": "Generate sound effects", "description": "This endpoint will start a new task to generate sound effects from a text description.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nconst task = await client.soundEffect\n .create({\n model: 'eleven_text_to_sound_v2',\n promptText: 'A thunderstorm with heavy rain',\n duration: 10,\n loop: true,\n })\n .waitForTaskOutput();\nconsole.log(task);" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\ntask = client.sound_effect.create(\n model='eleven_text_to_sound_v2',\n promptText='A thunderstorm with heavy rain',\n duration=10,\n loop=True,\n).wait_for_task_output()\n\nprint(task)" } ], "parameters": [{ "$ref": "#/components/parameters/X-Runway-Version" }], "requestBody": { "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "oneOf": [ { "title": "eleven_text_to_sound_v2", "type": "object", "properties": { "promptText": { "description": "A text description of the sound effect to generate.", "type": "string", "minLength": 1, "maxLength": 3000 }, "duration": { "description": "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.", "type": "number", "minimum": 0.5, "maximum": 30 }, "loop": { "description": "Whether the output sound effect should be designed to loop seamlessly.", "default": false, "type": "boolean" }, "model": { "type": "string", "const": "eleven_text_to_sound_v2" } }, "required": ["promptText", "model"] } ], "discriminator": { "propertyName": "model" } } } } }, "responses": { "200": { "description": "The task that was created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "The ID of the task that was created. Use this to retrieve the task later.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" } }, "required": ["id"], "additionalProperties": false } } } }, "429": { "description": "You have exceeded the rate limit for this endpoint.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/v1/speech_to_speech": { "post": { "tags": ["Start generating"], "summary": "Speech to speech", "description": "This endpoint will start a new task to convert speech from one voice to another in audio or video.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nconst audioTask = await client.speechToSpeech\n .create({\n model: 'eleven_multilingual_sts_v2',\n media: {\n type: 'audio',\n uri: 'https://example.com/audio.mp3',\n },\n voice: {\n type: 'runway-preset',\n presetId: 'Maggie',\n },\n })\n .waitForTaskOutput();\nconsole.log(audioTask);\n\nconst videoTask = await client.speechToSpeech\n .create({\n model: 'eleven_multilingual_sts_v2',\n media: {\n type: 'video',\n uri: 'https://example.com/video.mp4',\n },\n voice: {\n type: 'runway-preset',\n presetId: 'Noah',\n },\n })\n .waitForTaskOutput();\nconsole.log(videoTask);" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\naudioTask = client.speech_to_speech.create(\n model='eleven_multilingual_sts_v2',\n media={\n 'type': 'audio',\n 'uri': 'https://example.com/audio.mp3',\n },\n voice={\n 'type': 'runway-preset',\n 'presetId': 'Maggie',\n },\n).wait_for_task_output()\n\nprint(audioTask)\n\nvideoTask = client.speech_to_speech.create(\n model='eleven_multilingual_sts_v2',\n media={\n 'type': 'video',\n 'uri': 'https://example.com/video.mp4',\n },\n voice={\n 'type': 'runway-preset',\n 'presetId': 'Noah',\n },\n).wait_for_task_output()\n\nprint(videoTask)" } ], "parameters": [{ "$ref": "#/components/parameters/X-Runway-Version" }], "requestBody": { "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "oneOf": [ { "title": "eleven_multilingual_sts_v2", "type": "object", "properties": { "removeBackgroundNoise": { "description": "Whether to remove background noise from the generated speech.", "type": "boolean" }, "media": { "oneOf": [ { "title": "SpeechToSpeechAudio", "description": "An audio file containing dialogue to be processed.", "type": "object", "properties": { "type": { "type": "string", "const": "audio" }, "uri": { "description": "A HTTPS URL, Runway or data URI containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information.", "example": "https://example.com/audio.mp3", "anyOf": [ { "description": "A HTTPS URL.", "example": "https://example.com/file", "type": "string", "minLength": 13, "maxLength": 2048, "pattern": "^https:\\/\\/.*" }, { "description": "A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.", "example": "runway://", "type": "string", "minLength": 13, "maxLength": 5000, "pattern": "^runway:\\/\\/.*" }, { "description": "A data URI containing encoded media.", "example": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "type": "string", "minLength": 13, "maxLength": 16777216, "pattern": "^data:audio\\/.*" } ] } }, "required": ["type", "uri"] }, { "title": "SpeechToSpeechVideo", "description": "A video file containing dialogue to be processed.", "type": "object", "properties": { "type": { "type": "string", "const": "video" }, "uri": { "description": "A HTTPS URL, Runway or data URI containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information.", "example": "https://example.com/video.mp4", "anyOf": [ { "description": "A HTTPS URL.", "example": "https://example.com/file", "type": "string", "minLength": 13, "maxLength": 2048, "pattern": "^https:\\/\\/.*" }, { "description": "A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.", "example": "runway://", "type": "string", "minLength": 13, "maxLength": 5000, "pattern": "^runway:\\/\\/.*" }, { "description": "A data URI containing encoded media.", "example": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "type": "string", "minLength": 13, "maxLength": 16777216, "pattern": "^data:video\\/.*" } ] } }, "required": ["type", "uri"] } ], "discriminator": { "propertyName": "type" } }, "voice": { "description": "The voice to use for the generated speech.", "oneOf": [ { "title": "RunwayPresetVoice", "description": "A voice preset from the RunwayML API.", "type": "object", "properties": { "type": { "type": "string", "const": "runway-preset" }, "presetId": { "description": "The preset voice ID to use for the generated speech.", "type": "string", "enum": [ "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" ] } }, "required": ["type", "presetId"] } ], "discriminator": { "propertyName": "type" } }, "model": { "type": "string", "const": "eleven_multilingual_sts_v2" } }, "required": ["media", "voice", "model"] } ], "discriminator": { "propertyName": "model" } } } } }, "responses": { "200": { "description": "The task that was created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "The ID of the task that was created. Use this to retrieve the task later.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" } }, "required": ["id"], "additionalProperties": false } } } }, "429": { "description": "You have exceeded the rate limit for this endpoint.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/v1/text_to_speech": { "post": { "tags": ["Start generating"], "summary": "Text to speech", "description": "This endpoint will start a new task to generate speech from text.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nconst task = await client.textToSpeech\n .create({\n model: 'eleven_multilingual_v2',\n promptText: 'The quick brown fox jumps over the lazy dog',\n voice: {\n type: 'runway-preset',\n presetId: 'Leslie',\n },\n })\n .waitForTaskOutput();\nconsole.log(task);" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\ntask = client.text_to_speech.create(\n model='eleven_multilingual_v2',\n prompt_text='The quick brown fox jumps over the lazy dog',\n voice={\n 'type': 'runway-preset',\n 'presetId': 'Leslie',\n },\n).wait_for_task_output()\n\nprint(task)" } ], "parameters": [{ "$ref": "#/components/parameters/X-Runway-Version" }], "requestBody": { "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "oneOf": [ { "title": "eleven_multilingual_v2", "type": "object", "properties": { "promptText": { "description": "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.", "type": "string", "minLength": 1, "maxLength": 1000 }, "voice": { "description": "The voice to use for the generated speech.", "oneOf": [ { "title": "RunwayPresetVoice", "description": "A voice preset from the RunwayML API.", "type": "object", "properties": { "type": { "type": "string", "const": "runway-preset" }, "presetId": { "description": "The preset voice ID to use for the generated speech.", "type": "string", "enum": [ "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" ] } }, "required": ["type", "presetId"] } ], "discriminator": { "propertyName": "type" } }, "model": { "type": "string", "const": "eleven_multilingual_v2" } }, "required": ["promptText", "voice", "model"] } ], "discriminator": { "propertyName": "model" } } } } }, "responses": { "200": { "description": "The task that was created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "The ID of the task that was created. Use this to retrieve the task later.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" } }, "required": ["id"], "additionalProperties": false } } } }, "429": { "description": "You have exceeded the rate limit for this endpoint.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/v1/voice_dubbing": { "post": { "tags": ["Start generating"], "summary": "Voice dubbing", "description": "This endpoint will start a new task to dub audio content to a target language.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nconst task = await client.voiceDubbing\n .create({\n model: 'eleven_voice_dubbing',\n audioUri: 'https://example.com/audio.mp3',\n targetLang: 'es',\n })\n .waitForTaskOutput();\nconsole.log(task);" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\ntask = client.voice_dubbing.create(\n model='eleven_voice_dubbing',\n audio_uri='https://example.com/audio.mp3',\n target_lang='es',\n).wait_for_task_output()\n\nprint(task)" } ], "parameters": [{ "$ref": "#/components/parameters/X-Runway-Version" }], "requestBody": { "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "oneOf": [ { "title": "eleven_voice_dubbing", "type": "object", "properties": { "audioUri": { "description": "A HTTPS URL, Runway or data URI containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information.", "example": "https://example.com/audio.mp3", "anyOf": [ { "description": "A HTTPS URL.", "example": "https://example.com/file", "type": "string", "minLength": 13, "maxLength": 2048, "pattern": "^https:\\/\\/.*" }, { "description": "A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.", "example": "runway://", "type": "string", "minLength": 13, "maxLength": 5000, "pattern": "^runway:\\/\\/.*" }, { "description": "A data URI containing encoded media.", "example": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "type": "string", "minLength": 13, "maxLength": 16777216, "pattern": "^data:audio\\/.*" } ] }, "targetLang": { "description": "The target language code to dub the audio to (e.g., \"es\" for Spanish, \"fr\" for French).", "type": "string", "enum": [ "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" ] }, "disableVoiceCloning": { "description": "Whether to disable voice cloning and use a generic voice instead.", "type": "boolean" }, "dropBackgroundAudio": { "description": "Whether to remove background audio from the dubbed output.", "type": "boolean" }, "numSpeakers": { "description": "The number of speakers in the audio. If not provided, it will be detected automatically.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "model": { "type": "string", "const": "eleven_voice_dubbing" } }, "required": ["audioUri", "targetLang", "model"] } ], "discriminator": { "propertyName": "model" } } } } }, "responses": { "200": { "description": "The task that was created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "The ID of the task that was created. Use this to retrieve the task later.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" } }, "required": ["id"], "additionalProperties": false } } } }, "429": { "description": "You have exceeded the rate limit for this endpoint.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/v1/voice_isolation": { "post": { "tags": ["Start generating"], "summary": "Voice isolation", "description": "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.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nconst task = await client.voiceIsolation\n .create({\n model: 'eleven_voice_isolation',\n audioUrl: 'https://example.com/audio.mp3',\n })\n .waitForTaskOutput();\nconsole.log(task);" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\ntask = client.voice_isolation.create(\n model='eleven_voice_isolation',\n audio_url='https://example.com/audio.mp3',\n).wait_for_task_output()\n\nprint(task)" } ], "parameters": [{ "$ref": "#/components/parameters/X-Runway-Version" }], "requestBody": { "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "oneOf": [ { "title": "eleven_voice_isolation", "type": "object", "properties": { "audioUri": { "description": "A HTTPS URL, Runway or data URI containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information.", "example": "https://example.com/audio.mp3", "anyOf": [ { "description": "A HTTPS URL.", "example": "https://example.com/file", "type": "string", "minLength": 13, "maxLength": 2048, "pattern": "^https:\\/\\/.*" }, { "description": "A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.", "example": "runway://", "type": "string", "minLength": 13, "maxLength": 5000, "pattern": "^runway:\\/\\/.*" }, { "description": "A data URI containing encoded media.", "example": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "type": "string", "minLength": 13, "maxLength": 16777216, "pattern": "^data:audio\\/.*" } ] }, "model": { "type": "string", "const": "eleven_voice_isolation" } }, "required": ["audioUri", "model"] } ], "discriminator": { "propertyName": "model" } } } } }, "responses": { "200": { "description": "The task that was created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "The ID of the task that was created. Use this to retrieve the task later.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" } }, "required": ["id"], "additionalProperties": false } } } }, "429": { "description": "You have exceeded the rate limit for this endpoint.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/v1/organization": { "get": { "tags": ["Organization"], "summary": "Get organization information", "description": "Get usage tier and credit balance information about the organization associated with the API key used to make the request.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nconst details = await client.organization.retrieve();\nconsole.log(details.creditBalance);" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\ndetails = client.organization.retrieve()\nprint(details.creditBalance)" } ], "parameters": [{ "$ref": "#/components/parameters/X-Runway-Version" }], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "tier": { "title": "OrganizationTierDetails", "description": "Limits associated with the organization's tier.", "type": "object", "properties": { "maxMonthlyCreditSpend": { "description": "The maximum number of credits that can be purchased in a month.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "models": { "description": "An object containing model-specific limits. Each key represents a model.", "type": "object", "propertyNames": { "title": "ModelVariant", "type": "string", "enum": [ "gen4.5", "gen3a_turbo", "gen4_turbo", "gen4_image", "gen4_image_turbo", "gpt_image_2", "act_two", "gen4_aleph", "veo3", "veo3.1", "veo3.1_fast", "gemini_2.5_flash", "gemini_image3_pro", "gemini_image3.1_flash", "eleven_multilingual_v2", "eleven_v3", "eleven_text_to_sound_v2", "eleven_voice_isolation", "eleven_voice_dubbing", "eleven_multilingual_sts_v2", "eleven_scribe_v2", "gwm1_avatars", "gwm1_avatar_async_audio_to_video", "gwm1_avatar_async_text_to_video", "voice_processing", "seedance2" ] }, "additionalProperties": { "title": "ModelTierLimits", "description": "Limits associated with the model.", "type": "object", "properties": { "maxConcurrentGenerations": { "description": "The maximum number of generations that can be run concurrently for this model.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "maxDailyGenerations": { "description": "The maximum number of generations that can be created each day for this model.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "maxConcurrentGenerations", "maxDailyGenerations" ], "additionalProperties": false } } }, "required": ["maxMonthlyCreditSpend", "models"], "additionalProperties": false }, "creditBalance": { "description": "The number of credits remaining in the organization account.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "usage": { "title": "OrganizationUsageDetails", "description": "Usage data for the organization.", "type": "object", "properties": { "models": { "type": "object", "propertyNames": { "title": "ModelVariant", "type": "string", "enum": [ "gen4.5", "gen3a_turbo", "gen4_turbo", "gen4_image", "gen4_image_turbo", "gpt_image_2", "act_two", "gen4_aleph", "veo3", "veo3.1", "veo3.1_fast", "gemini_2.5_flash", "gemini_image3_pro", "gemini_image3.1_flash", "eleven_multilingual_v2", "eleven_v3", "eleven_text_to_sound_v2", "eleven_voice_isolation", "eleven_voice_dubbing", "eleven_multilingual_sts_v2", "eleven_scribe_v2", "gwm1_avatars", "gwm1_avatar_async_audio_to_video", "gwm1_avatar_async_text_to_video", "voice_processing", "seedance2" ] }, "additionalProperties": { "title": "ModelUsage", "description": "Usage data for the model.", "type": "object", "properties": { "dailyGenerations": { "description": "The number of generations that have been run for this model in the past day.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": ["dailyGenerations"], "additionalProperties": false } } }, "required": ["models"], "additionalProperties": false } }, "required": ["tier", "creditBalance", "usage"], "additionalProperties": false } } } } } } }, "/v1/organization/usage": { "post": { "tags": ["Organization"], "summary": "Query credit usage", "description": "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.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nconst usage = await client.organization.retrieveUsage();\nconsole.log(usage);" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\nusage = client.organization.retrieve_usage()\nprint(usage)" } ], "parameters": [{ "$ref": "#/components/parameters/X-Runway-Version" }], "requestBody": { "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "startDate": { "description": "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.", "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "beforeDate": { "description": "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.", "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "date": { "description": "The date of the usage data in ISO-8601 format (YYYY-MM-DD). All dates are in UTC.", "type": "string", "format": "date", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$" }, "usedCredits": { "description": "The credits used per model for the given date.", "type": "array", "items": { "title": "CreditUsageForModelForDate", "type": "object", "properties": { "model": { "title": "ModelVariant", "description": "The model that credits were spent on.", "type": "string", "enum": [ "gen4.5", "gen3a_turbo", "gen4_turbo", "gen4_image", "gen4_image_turbo", "gpt_image_2", "act_two", "gen4_aleph", "veo3", "veo3.1", "veo3.1_fast", "gemini_2.5_flash", "gemini_image3_pro", "gemini_image3.1_flash", "eleven_multilingual_v2", "eleven_v3", "eleven_text_to_sound_v2", "eleven_voice_isolation", "eleven_voice_dubbing", "eleven_multilingual_sts_v2", "eleven_scribe_v2", "gwm1_avatars", "gwm1_avatar_async_audio_to_video", "gwm1_avatar_async_text_to_video", "voice_processing", "seedance2" ] }, "amount": { "description": "The net number of credits spent on the model. May be negative if refunds exceeded charges on this day.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["model", "amount"], "additionalProperties": false } } }, "required": ["date", "usedCredits"], "additionalProperties": false } }, "models": { "description": "The list of models with usage during the queried time range.", "type": "array", "items": { "title": "ModelVariant", "description": "A model that was used during the queried time range.", "type": "string", "enum": [ "gen4.5", "gen3a_turbo", "gen4_turbo", "gen4_image", "gen4_image_turbo", "gpt_image_2", "act_two", "gen4_aleph", "veo3", "veo3.1", "veo3.1_fast", "gemini_2.5_flash", "gemini_image3_pro", "gemini_image3.1_flash", "eleven_multilingual_v2", "eleven_v3", "eleven_text_to_sound_v2", "eleven_voice_isolation", "eleven_voice_dubbing", "eleven_multilingual_sts_v2", "eleven_scribe_v2", "gwm1_avatars", "gwm1_avatar_async_audio_to_video", "gwm1_avatar_async_text_to_video", "voice_processing", "seedance2" ] } } }, "required": ["results", "models"], "additionalProperties": false } } } } } } }, "/v1/uploads": { "post": { "tags": ["Uploads"], "summary": "Upload a file", "description": "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.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\nimport fs from 'node:fs';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nfilename = './funny-cats.mp4';\nconst uploadUri = await client.uploads.createEphemeral(\n fs.createReadStream(filename),\n);\n\n// Use the runwayUri in generation requests\nconst task = await client.videoToVideo\n .create({\n model: 'gen4_aleph',\n videoUri: uploadUri,\n promptText: 'Add the easter elements to the cat video',\n references: [\n {\n type: 'image',\n uri: 'https://example.com/easter-scene.jpg',\n },\n ],\n ratio: '1280:720',\n })\n .waitForTaskOutput();\n\nconsole.log(task);" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\nfrom pathlib import Path\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\nfile = Path('./funny-cats.mp4');\nupload_uri = client.uploads.create_ephemeral(\n file=file,\n)\n\n# Use the upload_uri in generation requests\ntask = client.video_to_video.create(\n model='gen4_aleph',\n video_uri=upload_uri,\n prompt_text='Add the easter elements to the cat video',\n references=[\n {\n 'type': 'image',\n 'uri': 'https://example.com/easter-scene.jpg',\n },\n ],\n ratio='1280:720',\n).wait_for_task_output()\n\nprint(task)" } ], "parameters": [{ "$ref": "#/components/parameters/X-Runway-Version" }], "requestBody": { "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "filename": { "description": "The filename of the file to upload. Must have a valid extension and be a supported media type (image, video, or audio).", "type": "string", "minLength": 3, "maxLength": 255 }, "type": { "description": "The type of upload to create", "type": "string", "enum": ["ephemeral"] } }, "required": ["filename", "type"] } } } }, "responses": { "200": { "description": "The upload URL and Runway URI have been successfully created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "uploadUrl": { "description": "The URL to upload your media file to with a POST request.", "type": "string", "format": "uri" }, "fields": { "description": "Fields that must be included in the file upload request as form data.", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "runwayUri": { "description": "The Runway upload URI to use in other API generation requests", "type": "string", "pattern": "^runway:\\/\\/.*" } }, "required": ["uploadUrl", "fields", "runwayUri"], "additionalProperties": false } } } }, "429": { "description": "You have exceeded the rate limit for this endpoint." } } } }, "/v1/voices": { "get": { "tags": ["Voices"], "summary": "List voices", "description": "List custom voices for the authenticated organization with cursor-based pagination.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nconst voices = await client.voices.list();\n\nfor await (const voice of voices) {\n console.log(voice);\n}" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\nfor voice in client.voices.list():\n print(voice)" } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 1000 }, "description": "Cursor from a previous response for fetching the next page of results." }, { "name": "limit", "in": "query", "required": true, "schema": { "default": 50, "type": "integer", "minimum": 1, "maximum": 100 }, "description": "The maximum number of items to return per page." }, { "$ref": "#/components/parameters/X-Runway-Version" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "description": "The list of items for the current page.", "type": "array", "items": { "oneOf": [ { "title": "VoiceProcessing", "description": "A voice that is still being processed.", "type": "object", "properties": { "id": { "description": "The unique identifier of the voice.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "name": { "description": "The name of the voice.", "type": "string" }, "description": { "description": "A description of the voice, or null if not set.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "description": "When the voice was created.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "status": { "type": "string", "const": "PROCESSING" } }, "required": [ "id", "name", "description", "createdAt", "status" ], "additionalProperties": false }, { "title": "VoiceReady", "description": "A voice that is ready for use.", "type": "object", "properties": { "id": { "description": "The unique identifier of the voice.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "name": { "description": "The name of the voice.", "type": "string" }, "description": { "description": "A description of the voice, or null if not set.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "description": "When the voice was created.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "status": { "type": "string", "const": "READY" }, "previewUrl": { "description": "A signed URL to an MP3 audio sample of the voice, or null if no sample is available.", "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, "required": [ "id", "name", "description", "createdAt", "status", "previewUrl" ], "additionalProperties": false }, { "title": "VoiceFailed", "description": "A voice that failed to finish processing.", "type": "object", "properties": { "id": { "description": "The unique identifier of the voice.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "name": { "description": "The name of the voice.", "type": "string" }, "description": { "description": "A description of the voice, or null if not set.", "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "description": "When the voice was created.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "status": { "type": "string", "const": "FAILED" }, "failureReason": { "description": "A human-readable error message. This value is not stable and should not be matched against programmatically.", "type": "string" } }, "required": [ "id", "name", "description", "createdAt", "status", "failureReason" ], "additionalProperties": false } ], "discriminator": { "propertyName": "status" } } }, "hasMore": { "description": "Whether there are more items available after this page.", "type": "boolean" }, "nextCursor": { "description": "Cursor to use for fetching the next page, or null if there are no more pages.", "anyOf": [{ "type": "string" }, { "type": "null" }] } }, "required": ["data", "hasMore", "nextCursor"], "additionalProperties": false } } } } } }, "post": { "tags": ["Voices"], "summary": "Create a voice", "description": "Create a custom voice from a text description, or clone a voice from an audio sample.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nconst voice = await client.voices.create({\n name: 'My Custom Voice',\n from: {\n type: 'text',\n prompt: 'A warm, friendly voice with a slight British accent',\n model: 'eleven_ttv_v3',\n },\n});\nconsole.log(voice.id);" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\nvoice = client.voices.create(\n name='My Custom Voice',\n from_={\n 'type': 'text',\n 'prompt': 'A warm, friendly voice with a slight British accent',\n 'model': 'eleven_ttv_v3',\n },\n)\nprint(voice.id)" } ], "parameters": [{ "$ref": "#/components/parameters/X-Runway-Version" }], "requestBody": { "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "description": "A name for the voice.", "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "description": "An optional description of the voice.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512 }, { "type": "null" } ] }, "from": { "oneOf": [ { "title": "VoiceFromAudio", "type": "object", "properties": { "type": { "type": "string", "const": "audio" }, "audio": { "description": "Audio sample to clone the voice from. Must be between 10 seconds and 5 minutes long and at most 10MB. For best results, use a clear recording with minimal background noise and varied tone.", "example": "https://example.com/audio.mp3", "anyOf": [ { "description": "A HTTPS URL.", "example": "https://example.com/file", "type": "string", "minLength": 13, "maxLength": 2048, "pattern": "^https:\\/\\/.*" }, { "description": "A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.", "example": "runway://", "type": "string", "minLength": 13, "maxLength": 5000, "pattern": "^runway:\\/\\/.*" }, { "description": "A data URI containing encoded media.", "example": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "type": "string", "minLength": 13, "maxLength": 16777216, "pattern": "^data:audio\\/.*" } ] } }, "required": ["type", "audio"] }, { "title": "VoiceFromText", "type": "object", "properties": { "type": { "type": "string", "const": "text" }, "prompt": { "description": "A text description of the desired voice characteristics. Must be at least 20 characters.", "type": "string", "minLength": 20, "maxLength": 1000 }, "model": { "description": "The voice design model to use. Prefer eleven_ttv_v3 (latest); eleven_multilingual_ttv_v2 is the previous generation.", "type": "string", "enum": [ "eleven_ttv_v3", "eleven_multilingual_ttv_v2" ] } }, "required": ["type", "prompt", "model"] } ], "discriminator": { "propertyName": "type" } } }, "required": ["name", "from"] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "The ID of the voice that was created.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" } }, "required": ["id"], "additionalProperties": false } } } } } } }, "/v1/voices/{id}": { "get": { "tags": ["Voices"], "summary": "Get a voice", "description": "Get details about a specific custom voice.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nconst voice = await client.voices.retrieve('550e8400-e29b-41d4-a716-446655440000');\nconsole.log(voice);" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\nvoice = client.voices.retrieve(id='550e8400-e29b-41d4-a716-446655440000')\nprint(voice)" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "description": "The ID of the voice to retrieve." }, { "$ref": "#/components/parameters/X-Runway-Version" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "oneOf": [ { "title": "VoiceProcessing", "description": "A voice that is still being processed.", "type": "object", "properties": { "id": { "description": "The unique identifier of the voice.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "name": { "description": "The name of the voice.", "type": "string" }, "description": { "description": "A description of the voice, or null if not set.", "anyOf": [{ "type": "string" }, { "type": "null" }] }, "createdAt": { "description": "When the voice was created.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "status": { "type": "string", "const": "PROCESSING" } }, "required": [ "id", "name", "description", "createdAt", "status" ], "additionalProperties": false }, { "title": "VoiceReady", "description": "A voice that is ready for use.", "type": "object", "properties": { "id": { "description": "The unique identifier of the voice.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "name": { "description": "The name of the voice.", "type": "string" }, "description": { "description": "A description of the voice, or null if not set.", "anyOf": [{ "type": "string" }, { "type": "null" }] }, "createdAt": { "description": "When the voice was created.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "status": { "type": "string", "const": "READY" }, "previewUrl": { "description": "A signed URL to an MP3 audio sample of the voice, or null if no sample is available.", "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, "required": [ "id", "name", "description", "createdAt", "status", "previewUrl" ], "additionalProperties": false }, { "title": "VoiceFailed", "description": "A voice that failed to finish processing.", "type": "object", "properties": { "id": { "description": "The unique identifier of the voice.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "name": { "description": "The name of the voice.", "type": "string" }, "description": { "description": "A description of the voice, or null if not set.", "anyOf": [{ "type": "string" }, { "type": "null" }] }, "createdAt": { "description": "When the voice was created.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "status": { "type": "string", "const": "FAILED" }, "failureReason": { "description": "A human-readable error message. This value is not stable and should not be matched against programmatically.", "type": "string" } }, "required": [ "id", "name", "description", "createdAt", "status", "failureReason" ], "additionalProperties": false } ], "discriminator": { "propertyName": "status" } } } } } } }, "patch": { "tags": ["Voices"], "summary": "Update a voice", "description": "Update the name and/or description of a custom voice.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nconst voice = await client.voices.update(\n '550e8400-e29b-41d4-a716-446655440000',\n { name: 'My Updated Voice' },\n);\nconsole.log(voice.name);" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\nvoice = client.voices.update(\n id='550e8400-e29b-41d4-a716-446655440000',\n name='My Updated Voice',\n)\nprint(voice.name)" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "description": "The ID of the voice to update." }, { "$ref": "#/components/parameters/X-Runway-Version" } ], "requestBody": { "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "description": "A name for the voice.", "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "description": "An optional description of the voice.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 512 }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "oneOf": [ { "title": "VoiceProcessing", "description": "A voice that is still being processed.", "type": "object", "properties": { "id": { "description": "The unique identifier of the voice.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "name": { "description": "The name of the voice.", "type": "string" }, "description": { "description": "A description of the voice, or null if not set.", "anyOf": [{ "type": "string" }, { "type": "null" }] }, "createdAt": { "description": "When the voice was created.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "status": { "type": "string", "const": "PROCESSING" } }, "required": [ "id", "name", "description", "createdAt", "status" ], "additionalProperties": false }, { "title": "VoiceReady", "description": "A voice that is ready for use.", "type": "object", "properties": { "id": { "description": "The unique identifier of the voice.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "name": { "description": "The name of the voice.", "type": "string" }, "description": { "description": "A description of the voice, or null if not set.", "anyOf": [{ "type": "string" }, { "type": "null" }] }, "createdAt": { "description": "When the voice was created.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "status": { "type": "string", "const": "READY" }, "previewUrl": { "description": "A signed URL to an MP3 audio sample of the voice, or null if no sample is available.", "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, "required": [ "id", "name", "description", "createdAt", "status", "previewUrl" ], "additionalProperties": false }, { "title": "VoiceFailed", "description": "A voice that failed to finish processing.", "type": "object", "properties": { "id": { "description": "The unique identifier of the voice.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "name": { "description": "The name of the voice.", "type": "string" }, "description": { "description": "A description of the voice, or null if not set.", "anyOf": [{ "type": "string" }, { "type": "null" }] }, "createdAt": { "description": "When the voice was created.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "status": { "type": "string", "const": "FAILED" }, "failureReason": { "description": "A human-readable error message. This value is not stable and should not be matched against programmatically.", "type": "string" } }, "required": [ "id", "name", "description", "createdAt", "status", "failureReason" ], "additionalProperties": false } ], "discriminator": { "propertyName": "status" } } } } } } }, "delete": { "tags": ["Voices"], "summary": "Delete a voice", "description": "Delete a custom voice.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nawait client.voices.delete('550e8400-e29b-41d4-a716-446655440000');" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\nclient.voices.delete(id='550e8400-e29b-41d4-a716-446655440000')" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "description": "The ID of the voice to delete." }, { "$ref": "#/components/parameters/X-Runway-Version" } ], "responses": { "204": { "description": "Success" } } } }, "/v1/voices/preview": { "post": { "tags": ["Voices"], "summary": "Preview a voice", "description": "Generate a short audio preview of a voice from a text description. Use this to audition a voice before creating it.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nconst preview = await client.voices.preview({\n prompt: 'A warm, friendly voice with a slight British accent',\n model: 'eleven_ttv_v3',\n});\nconsole.log(preview.url, preview.durationSecs);" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\npreview = client.voices.preview(\n prompt='A warm, friendly voice with a slight British accent',\n model='eleven_ttv_v3',\n)\nprint(preview.url, preview.duration_secs)" } ], "parameters": [{ "$ref": "#/components/parameters/X-Runway-Version" }], "requestBody": { "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "prompt": { "description": "A text description of the desired voice characteristics. Must be at least 20 characters.", "type": "string", "minLength": 20, "maxLength": 1000 }, "model": { "description": "The voice design model to use. Prefer eleven_ttv_v3 (latest); eleven_multilingual_ttv_v2 is the previous generation.", "type": "string", "enum": ["eleven_ttv_v3", "eleven_multilingual_ttv_v2"] } }, "required": ["prompt", "model"] } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "description": "A presigned URL to the audio preview. The URL expires after 24 hours.", "type": "string", "format": "uri" }, "durationSecs": { "description": "Duration of the audio preview in seconds.", "type": "number" } }, "required": ["url", "durationSecs"], "additionalProperties": false } } } } } } }, "/v1/workflows/{id}": { "post": { "tags": ["Workflows"], "summary": "Run a published workflow", "description": "Start a new task to execute a published workflow. You can optionally provide custom input values via `nodeOutputs` to override the defaults defined in the workflow graph.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nconst { id } = await client.workflows.run('YOUR_WORKFLOW_ID', {\n nodeOutputs: {\n 'node-uuid': {\n // For text/number/boolean values, use type: 'primitive'\n 'prompt': { type: 'primitive', value: 'A beautiful sunset' },\n // For media assets, use type: 'image', 'video', or 'audio'\n 'image': { type: 'image', uri: 'https://example.com/image.jpg' },\n },\n },\n});\n\n// Then poll for the workflow result\nconst invocation = await client.workflowInvocations\n .retrieve(id)\n .waitForTaskOutput();\n\nconsole.log(invocation);" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\n# Run a published workflow with custom inputs\ninvocation = client.workflows.run(\n 'YOUR_WORKFLOW_ID',\n node_outputs={\n 'node-uuid': {\n # For text/number/boolean values, use type: 'primitive'\n 'prompt': { 'type': 'primitive', 'value': 'A beautiful sunset' },\n # For media assets, use type: 'image', 'video', or 'audio'\n 'image': { 'type': 'image', 'uri': 'https://example.com/image.jpg' },\n },\n },\n)\n\n# Then poll for the workflow result\ninvocation = client.workflow_invocations.retrieve(id=invocation.id).wait_for_task_output()\nprint(invocation)" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "description": "The ID of the published workflow to run. You can copy this value from the developer portal." }, { "$ref": "#/components/parameters/X-Runway-Version" } ], "requestBody": { "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "nodeOutputs": { "description": "Optional node outputs to override default values. Keys are node IDs from the workflow graph, values are objects mapping output keys to typed values.", "type": "object", "propertyNames": { "description": "The ID of the workflow node to override", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "additionalProperties": { "type": "object", "propertyNames": { "description": "The output key to override", "type": "string", "minLength": 1, "maxLength": 256 }, "additionalProperties": { "oneOf": [ { "title": "WorkflowNodeOutputPrimitive", "description": "A primitive value (string, number, or boolean)", "type": "object", "properties": { "type": { "type": "string", "const": "primitive" }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "required": ["type", "value"] }, { "title": "WorkflowNodeOutputImage", "description": "An image asset", "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "uri": { "description": "A HTTPS URL, Runway or data URI containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "anyOf": [ { "description": "A HTTPS URL.", "example": "https://example.com/file", "type": "string", "minLength": 13, "maxLength": 2048, "pattern": "^https:\\/\\/.*" }, { "description": "A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.", "example": "runway://", "type": "string", "minLength": 13, "maxLength": 5000, "pattern": "^runway:\\/\\/.*" }, { "description": "A data URI containing encoded media.", "example": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "type": "string", "minLength": 13, "maxLength": 5242880, "pattern": "^data:image\\/.*" } ] } }, "required": ["type", "uri"] }, { "title": "WorkflowNodeOutputVideo", "description": "A video asset", "type": "object", "properties": { "type": { "type": "string", "const": "video" }, "uri": { "description": "A HTTPS URL, Runway or data URI containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information.", "example": "https://example.com/video.mp4", "anyOf": [ { "description": "A HTTPS URL.", "example": "https://example.com/file", "type": "string", "minLength": 13, "maxLength": 2048, "pattern": "^https:\\/\\/.*" }, { "description": "A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.", "example": "runway://", "type": "string", "minLength": 13, "maxLength": 5000, "pattern": "^runway:\\/\\/.*" }, { "description": "A data URI containing encoded media.", "example": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "type": "string", "minLength": 13, "maxLength": 16777216, "pattern": "^data:video\\/.*" } ] } }, "required": ["type", "uri"] }, { "title": "WorkflowNodeOutputAudio", "description": "An audio asset", "type": "object", "properties": { "type": { "type": "string", "const": "audio" }, "uri": { "description": "A HTTPS URL, Runway or data URI containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information.", "example": "https://example.com/audio.mp3", "anyOf": [ { "description": "A HTTPS URL.", "example": "https://example.com/file", "type": "string", "minLength": 13, "maxLength": 2048, "pattern": "^https:\\/\\/.*" }, { "description": "A Runway upload URI. See https://docs.dev.runwayml.com/assets/uploads for more information.", "example": "runway://", "type": "string", "minLength": 13, "maxLength": 5000, "pattern": "^runway:\\/\\/.*" }, { "description": "A data URI containing encoded media.", "example": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==", "type": "string", "minLength": 13, "maxLength": 16777216, "pattern": "^data:audio\\/.*" } ] } }, "required": ["type", "uri"] } ], "discriminator": { "propertyName": "type" } } } } } } } } }, "responses": { "200": { "description": "The response from running a workflow.", "content": { "application/json": { "schema": { "title": "WorkflowRunResponse", "type": "object", "properties": { "id": { "description": "The ID of the workflow invocation that was created.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" } }, "required": ["id"], "additionalProperties": false }, "examples": { "example": { "title": "Workflow run response", "summary": "An example of a workflow run response", "value": { "id": "17f20503-6c24-4c16-946b-35dbbce2af2f" } } } } } }, "404": { "description": "The published workflow does not exist or was deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } }, "get": { "tags": ["Workflows"], "summary": "Get workflow details", "description": "Returns details about a specific published workflow, including its graph schema.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nconst workflow = await client.workflows.retrieve(\n 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'\n);\nconsole.log(workflow);" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\nworkflow = client.workflows.retrieve(\n id='a1b2c3d4-e5f6-7890-abcd-ef1234567890'\n)\nprint(workflow)" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "description": "The ID of the published workflow to run. You can copy this value from the developer portal." }, { "$ref": "#/components/parameters/X-Runway-Version" } ], "responses": { "200": { "description": "The workflow details including graph schema.", "content": { "application/json": { "schema": { "title": "WorkflowDetail", "type": "object", "properties": { "id": { "description": "The globally unique ID of the published workflow.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "name": { "description": "The name of the published workflow.", "type": "string" }, "description": { "description": "The description of the published workflow.", "anyOf": [{ "type": "string" }, { "type": "null" }] }, "version": { "description": "A monotonically increasing version number. Each workflow version for the same published workflow has a unique version number.", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "createdAt": { "description": "When this version was published", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "updatedAt": { "description": "When this version was last updated", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "graph": { "description": "The workflow graph definition.", "type": "object", "properties": { "nodes": { "description": "The list of nodes in the workflow graph.", "type": "array", "items": {} }, "edges": { "description": "The list of edges connecting nodes in the workflow graph.", "type": "array", "items": {} }, "version": { "description": "The schema version of the workflow graph format.", "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": ["nodes", "edges", "version"], "additionalProperties": false } }, "required": [ "id", "name", "description", "version", "createdAt", "updatedAt", "graph" ], "additionalProperties": false }, "examples": { "example": { "title": "Workflow details", "summary": "An example of workflow details response", "value": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "My Video Generator", "description": "A workflow that generates videos from text prompts", "version": 1, "createdAt": "2024-06-27T19:49:32.334Z", "updatedAt": "2024-06-27T19:49:32.334Z", "graph": { "version": 1, "nodes": [], "edges": [] } } } } } } }, "404": { "description": "The workflow does not exist or was deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/v1/workflows": { "get": { "tags": ["Workflows"], "summary": "List published workflows", "description": "Returns a list of all published workflows for the authenticated user, grouped by source workflow with their published versions.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\nconst { data: workflows } = await client.workflows.list();\nconsole.log(workflows);" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\nworkflows = client.workflows.list()\nprint(workflows.data)" } ], "parameters": [{ "$ref": "#/components/parameters/X-Runway-Version" }], "responses": { "200": { "description": "A list of published workflows grouped by source workflow.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "title": "WorkflowList", "description": "A list of published workflows grouped by source workflow.", "type": "array", "items": { "title": "WorkflowListItem", "description": "A published workflow with all its available versions.", "type": "object", "properties": { "name": { "description": "The name of the published workflow.", "type": "string" }, "versions": { "description": "The published versions of this workflow, newest first.", "type": "array", "items": { "title": "WorkflowVersion", "description": "A specific published version of a workflow.", "type": "object", "properties": { "id": { "description": "The globally unique ID of this published workflow version.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "version": { "description": "A monotonically increasing version number. Each workflow version for the same published workflow has a unique version number.", "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "createdAt": { "description": "When this version was published", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": ["id", "version", "createdAt"], "additionalProperties": false } } }, "required": ["name", "versions"], "additionalProperties": false } } }, "required": ["data"], "additionalProperties": false }, "examples": { "example": { "title": "Workflow list", "summary": "An example of a workflow list response", "value": { "data": [ { "name": "My Video Generator", "versions": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "version": 2, "createdAt": "2024-06-27T19:49:32.334Z" }, { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "version": 1, "createdAt": "2024-06-20T10:30:00.000Z" } ] } ] } } } } } } } } }, "/v1/workflow_invocations/{id}": { "get": { "tags": ["Workflows"], "summary": "Get workflow invocation detail", "description": "Return details about a workflow invocation. Consumers of this API should not expect updates more frequent than once every five seconds for a given workflow invocation.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\n// The env var RUNWAYML_API_SECRET is expected to contain your API key.\nconst client = new RunwayML();\n\n// Fetch the current state of the workflow invocation:\nconst invocation = await client.workflowInvocations.retrieve(\n '17f20503-6c24-4c16-946b-35dbbce2af2f'\n);\n\n// Or, wait for the workflow to succeed or fail:\nconst invocation = await client.workflowInvocations\n .retrieve('17f20503-6c24-4c16-946b-35dbbce2af2f')\n .waitForTaskOutput();" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\n# The env var RUNWAYML_API_SECRET is expected to contain your API key.\nclient = RunwayML()\n\ninvocation_id = '17f20503-6c24-4c16-946b-35dbbce2af2f'\n\n# Fetch the current state of the workflow invocation:\ninvocation = client.workflow_invocations.retrieve(id=invocation_id)\nprint(invocation)\n\n# Or, wait for the workflow to succeed or fail:\ninvocation = client.workflow_invocations.retrieve(id=invocation_id).wait_for_task_output()\nprint(invocation)" } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "description": "The ID of a previously-submitted workflow invocation that has not been canceled or deleted." }, { "$ref": "#/components/parameters/X-Runway-Version" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "oneOf": [ { "title": "WorkflowInvocationPending", "description": "A pending workflow invocation", "type": "object", "properties": { "id": { "description": "The ID of the workflow invocation being returned.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "createdAt": { "description": "The timestamp that the workflow invocation was submitted at.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "status": { "type": "string", "const": "PENDING" } }, "required": ["id", "createdAt", "status"], "additionalProperties": false }, { "title": "WorkflowInvocationThrottled", "description": "A throttled workflow invocation", "type": "object", "properties": { "id": { "description": "The ID of the workflow invocation being returned.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "createdAt": { "description": "The timestamp that the workflow invocation was submitted at.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "status": { "type": "string", "const": "THROTTLED" } }, "required": ["id", "createdAt", "status"], "additionalProperties": false }, { "title": "WorkflowInvocationCancelled", "description": "A cancelled or deleted workflow invocation", "type": "object", "properties": { "id": { "description": "The ID of the workflow invocation being returned.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "createdAt": { "description": "The timestamp that the workflow invocation was submitted at.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "status": { "type": "string", "const": "CANCELLED" } }, "required": ["id", "createdAt", "status"], "additionalProperties": false }, { "title": "WorkflowInvocationRunning", "description": "A running workflow invocation", "type": "object", "properties": { "id": { "description": "The ID of the workflow invocation being returned.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "createdAt": { "description": "The timestamp that the workflow invocation was submitted at.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "status": { "type": "string", "const": "RUNNING" }, "progress": { "description": "A number between 0 and 1 representing the overall workflow execution progress.", "type": "number", "minimum": 0, "maximum": 1 }, "output": { "description": "A record mapping workflow node IDs to arrays of output URLs for nodes that have already completed. This allows streaming partial results while the workflow is still running.", "type": "object", "propertyNames": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "additionalProperties": { "type": "array", "items": { "type": "string", "format": "uri" } } }, "nodeErrors": { "description": "A record mapping workflow node IDs to their error details. Only present when one or more nodes have errored.", "type": "object", "propertyNames": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "additionalProperties": { "type": "object", "properties": { "nodeName": { "description": "The human-readable name of the node that errored.", "type": "string" }, "message": { "description": "A human-readable description of the node error.", "type": "string" } }, "required": ["message"], "additionalProperties": false } } }, "required": [ "id", "createdAt", "status", "progress", "output" ], "additionalProperties": false }, { "title": "WorkflowInvocationFailed", "description": "A failed workflow invocation", "type": "object", "properties": { "id": { "description": "The ID of the workflow invocation being returned.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "createdAt": { "description": "The timestamp that the workflow invocation was submitted at.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "status": { "type": "string", "const": "FAILED" }, "failure": { "description": "A human-friendly reason for the failure. We do not recommend returning this to users directly without adding context.", "type": "string" }, "failureCode": { "description": "A machine-readable error code for the failure. See https://docs.dev.runwayml.com/errors/task-failures/ for more information.", "type": "string" }, "nodeErrors": { "description": "A record mapping workflow node IDs to their error details. Only present when one or more nodes have errored.", "type": "object", "propertyNames": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "additionalProperties": { "type": "object", "properties": { "nodeName": { "description": "The human-readable name of the node that errored.", "type": "string" }, "message": { "description": "A human-readable description of the node error.", "type": "string" } }, "required": ["message"], "additionalProperties": false } } }, "required": ["id", "createdAt", "status", "failure"], "additionalProperties": false }, { "title": "WorkflowInvocationSucceeded", "description": "A succeeded workflow invocation", "type": "object", "properties": { "id": { "description": "The ID of the workflow invocation being returned.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "createdAt": { "description": "The timestamp that the workflow invocation was submitted at.", "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "status": { "type": "string", "const": "SUCCEEDED" }, "output": { "description": "A record mapping workflow node IDs to arrays of output URLs. Each key is the UUID of a workflow node that produced output, and each value is an array of URLs for that node's artifacts. These URLs will expire within 24-48 hours; fetch the invocation again to get fresh URLs. It is expected that you download the assets at these URLs and store them in your own storage system.", "type": "object", "propertyNames": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "additionalProperties": { "type": "array", "items": { "type": "string", "format": "uri" } } }, "nodeErrors": { "description": "A record mapping workflow node IDs to their error details. Even when the overall workflow succeeds, individual nodes may have encountered non-fatal errors. Only present when one or more nodes have errored.", "type": "object", "propertyNames": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12})$" }, "additionalProperties": { "type": "object", "properties": { "nodeName": { "description": "The human-readable name of the node that errored.", "type": "string" }, "message": { "description": "A human-readable description of the node error.", "type": "string" } }, "required": ["message"], "additionalProperties": false } } }, "required": ["id", "createdAt", "status", "output"], "additionalProperties": false } ], "discriminator": { "propertyName": "status" } }, "examples": { "pending": { "title": "Pending workflow invocation", "summary": "An example of a pending workflow invocation", "value": { "id": "17f20503-6c24-4c16-946b-35dbbce2af2f", "status": "PENDING", "createdAt": "2024-06-27T19:49:32.334Z" } }, "running": { "title": "Running workflow invocation", "summary": "An example of a running workflow invocation", "value": { "id": "08388106-1b46-4f5c-bd46-1c1d7ee86892", "status": "RUNNING", "createdAt": "2024-06-27T19:49:32.335Z", "progress": 0.2, "output": { "a1b2c3d4-e5f6-7890-abcd-ef1234567890": [ "https://example.com/output1.jpg" ] } } }, "succeeded": { "title": "Succeeded workflow invocation", "summary": "An example of a succeeded workflow invocation", "value": { "id": "d2e3d1f4-1b3c-4b5c-8d46-1c1d7ee86892", "status": "SUCCEEDED", "createdAt": "2024-06-27T19:49:32.335Z", "output": { "a1b2c3d4-e5f6-7890-abcd-ef1234567890": [ "https://example.com/output1.jpg" ], "b2c3d4e5-f6a7-8901-bcde-f12345678901": [ "https://example.com/output2.mp4" ] } } }, "failed": { "title": "Failed workflow invocation", "summary": "An example of a failed workflow invocation", "value": { "id": "6da960dd-ef88-40fc-9628-02e9b6a6a008", "status": "FAILED", "createdAt": "2024-06-27T19:49:32.335Z", "failure": "The provided image was flagged by content moderation.", "failureCode": "SAFETY.INPUT.IMAGE" } } } } } }, "404": { "description": "The workflow invocation does not exist, was deleted or canceled, or is not a workflow task.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } } }, "components": { "schemas": {}, "responses": {}, "parameters": { "X-Runway-Version": { "name": "X-Runway-Version", "in": "header", "required": true, "description": "The version of the RunwayML API being used. You can read more about versioning [here](/api-details/versioning).", "schema": { "type": "string", "const": "2024-11-06", "default": "2024-11-06" } } }, "examples": {}, "requestBodies": {}, "headers": {}, "securitySchemes": { "ApiKeyAuth": { "type": "http", "scheme": "bearer" } }, "links": {}, "callbacks": {} }, "security": [{ "ApiKeyAuth": [] }], "tags": [ { "name": "Start generating", "description": "These endpoints all kick off tasks to create generations." }, { "name": "Task management", "description": "Endpoints for managing tasks that have been submitted." }, { "name": "Uploads", "description": "Endpoints for uploading media files." } ], "servers": [{ "url": "https://api.dev.runwayml.com" }] }