{ "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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, Runway upload URI, or base64 data URI (e.g. `data:audio/mp3;base64,...`, up to 16MB) containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information.", "example": "https://example.com/audio.mp3", "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": 5000 }, "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" } } }, "integration": { "description": "External integration. Runway renders the avatar; the integration owns conversation or audio.", "oneOf": [ { "title": "ElevenLabsIntegration", "description": "ElevenLabs handles conversation; Runway renders the avatar video.", "type": "object", "properties": { "type": { "type": "string", "const": "elevenlabs" }, "signedUrl": { "description": "ConvAI signed WebSocket URL (~15 min lifetime).", "type": "string", "format": "uri" } }, "required": ["type", "signedUrl"] }, { "title": "LiveKitIntegration", "description": "Join an external LiveKit room; Runway publishes video, your agent supplies audio.", "type": "object", "properties": { "type": { "type": "string", "const": "livekit" }, "url": { "description": "WebSocket URL of the external LiveKit server the avatar worker should join.", "type": "string", "format": "uri" }, "token": { "description": "LiveKit access token granting the avatar worker publish rights in the external room.", "type": "string", "minLength": 1, "maxLength": 2048 }, "roomName": { "description": "Name of the external LiveKit room.", "type": "string", "minLength": 1, "maxLength": 256 }, "agentIdentity": { "description": "The participant identity of the customer agent already in the room. When provided, the avatar worker trusts audio published by this identity.", "type": "string", "minLength": 1, "maxLength": 256 } }, "required": ["type", "url", "token", "roomName"] } ], "discriminator": { "propertyName": "type" } }, "livekit": { "deprecated": true, "description": "Use integration with type \"livekit\" instead.", "title": "DeprecatedLiveKit", "x-stainless-model": "realtime_sessions.deprecated_livekit", "type": "object", "properties": { "url": { "description": "WebSocket URL of the external LiveKit server the avatar worker should join.", "type": "string", "format": "uri" }, "token": { "description": "LiveKit access token granting the avatar worker publish rights in the external room.", "type": "string", "minLength": 1, "maxLength": 2048 }, "roomName": { "description": "Name of the external LiveKit room.", "type": "string", "minLength": 1, "maxLength": 256 }, "agentIdentity": { "description": "The participant identity of the customer agent already in the room. When provided, the avatar worker trusts audio published by this identity.", "type": "string", "minLength": 1, "maxLength": 256 } }, "required": ["url", "token", "roomName"] } }, "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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"] } }, "additionalProperties": false }, "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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"] } }, "additionalProperties": false }, "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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" }, "negativePrompt": { "description": "Text describing what should not appear in the output video.", "type": "string", "minLength": 1, "maxLength": 1000 }, "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": "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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" }, "negativePrompt": { "description": "Text describing what should not appear in the output video.", "type": "string", "minLength": 1, "maxLength": 1000 }, "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": "happyhorse_1_0", "type": "object", "properties": { "promptText": { "description": "A string up to 2500 characters (measured in UTF-16 code units) describing motion or changes in the output video.", "type": "string", "minLength": 2, "maxLength": 2500 }, "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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"] } } ] }, "resolution": { "description": "Output quality tier. Output aspect ratio follows the input image.", "type": "string", "enum": ["720P", "1080P"] }, "duration": { "description": "The number of seconds of duration for the output video.", "type": "integer", "minimum": 3, "maximum": 15 }, "model": { "type": "string", "const": "happyhorse_1_0" } }, "required": ["promptImage", "model"], "additionalProperties": false }, { "title": "seedance2", "type": "object", "properties": { "promptImage": { "description": "An image or array of images. Use position `first`/`last` for keyframe mode, or omit position for reference images. The two modes cannot be mixed.", "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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 image objects. Use position \"first\"/\"last\" for keyframe mode, or omit position for reference images. The two modes cannot be mixed.", "example": [ { "uri": "https://example.com/firstFrame.jpg", "position": "first" }, { "uri": "https://example.com/lastFrame.jpg", "position": "last" } ], "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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, \"last\" as the last frame. Omit for a reference image.", "type": "string", "enum": ["first", "last"] } }, "required": ["uri"] } } ] }, "promptText": { "description": "An optional text prompt up to 3500 characters describing what should appear in the output.", "type": "string", "minLength": 1, "maxLength": 3500 }, "audio": { "description": "Whether to generate audio for the video.", "default": true, "type": "boolean" }, "duration": { "description": "The number of seconds of duration for the output video.", "type": "integer", "minimum": 4, "maximum": 15 }, "ratio": { "description": "The resolution of the output video.", "type": "string", "enum": [ "992:432", "864:496", "752:560", "640:640", "560:752", "496:864", "1470:630", "1280:720", "1112:834", "960:960", "834:1112", "720:1280", "2206:946", "1920:1080", "1664:1248", "1440:1440", "1248:1664", "1080:1920", "3840:1646", "3840:2160", "3840:2880", "3840:3840", "2880:3840", "2160:3840" ] }, "referenceAudio": { "description": "An optional array of audio references. Audio references require a text prompt, and the total combined duration must not exceed 15 seconds.", "maxItems": 3, "type": "array", "items": { "title": "AudioReference", "description": "An audio reference allows the model to use the audio as additional context for the output.", "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, Runway upload URI, or base64 data URI (e.g. `data:audio/mp3;base64,...`, up to 16MB) containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information.", "example": "https://example.com/audio.mp3", "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"] } }, "model": { "type": "string", "const": "seedance2" } }, "required": ["promptImage", "model"], "additionalProperties": false }, { "title": "seedance2_fast", "type": "object", "properties": { "promptImage": { "description": "An image or array of images. Use position `first`/`last` for keyframe mode, or omit position for reference images. The two modes cannot be mixed.", "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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 image objects. Use position \"first\"/\"last\" for keyframe mode, or omit position for reference images. The two modes cannot be mixed.", "example": [ { "uri": "https://example.com/firstFrame.jpg", "position": "first" }, { "uri": "https://example.com/lastFrame.jpg", "position": "last" } ], "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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, \"last\" as the last frame. Omit for a reference image.", "type": "string", "enum": ["first", "last"] } }, "required": ["uri"] } } ] }, "promptText": { "description": "An optional text prompt up to 3500 characters describing what should appear in the output.", "type": "string", "minLength": 1, "maxLength": 3500 }, "audio": { "description": "Whether to generate audio for the video.", "default": true, "type": "boolean" }, "duration": { "description": "The number of seconds of duration for the output video.", "type": "integer", "minimum": 4, "maximum": 15 }, "ratio": { "description": "The resolution of the output video. Seedance 2.0 Fast supports 480p and 720p only.", "type": "string", "enum": [ "992:432", "864:496", "752:560", "640:640", "560:752", "496:864", "1470:630", "1280:720", "1112:834", "960:960", "834:1112", "720:1280" ] }, "referenceAudio": { "description": "An optional array of audio references. Audio references require a text prompt, and the total combined duration must not exceed 15 seconds.", "maxItems": 3, "type": "array", "items": { "title": "AudioReference", "description": "An audio reference allows the model to use the audio as additional context for the output.", "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, Runway upload URI, or base64 data URI (e.g. `data:audio/mp3;base64,...`, up to 16MB) containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information.", "example": "https://example.com/audio.mp3", "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"] } }, "model": { "type": "string", "const": "seedance2_fast" } }, "required": ["promptImage", "model"], "additionalProperties": false }, { "title": "seedance2_mini", "type": "object", "properties": { "promptImage": { "description": "An image or array of images. Use position `first`/`last` for keyframe mode, or omit position for reference images. The two modes cannot be mixed.", "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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 image objects. Use position \"first\"/\"last\" for keyframe mode, or omit position for reference images. The two modes cannot be mixed.", "example": [ { "uri": "https://example.com/firstFrame.jpg", "position": "first" }, { "uri": "https://example.com/lastFrame.jpg", "position": "last" } ], "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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, \"last\" as the last frame. Omit for a reference image.", "type": "string", "enum": ["first", "last"] } }, "required": ["uri"] } } ] }, "promptText": { "description": "An optional text prompt up to 3500 characters describing what should appear in the output.", "type": "string", "minLength": 1, "maxLength": 3500 }, "audio": { "description": "Whether to generate audio for the video.", "default": true, "type": "boolean" }, "duration": { "description": "The number of seconds of duration for the output video.", "type": "integer", "minimum": 4, "maximum": 15 }, "ratio": { "description": "The resolution of the output video. Seedance 2.0 Mini supports 480p and 720p only.", "type": "string", "enum": [ "992:432", "864:496", "752:560", "640:640", "560:752", "496:864", "1470:630", "1280:720", "1112:834", "960:960", "834:1112", "720:1280" ] }, "referenceAudio": { "description": "An optional array of audio references. Audio references require a text prompt, and the total combined duration must not exceed 15 seconds.", "maxItems": 3, "type": "array", "items": { "title": "AudioReference", "description": "An audio reference allows the model to use the audio as additional context for the output.", "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, Runway upload URI, or base64 data URI (e.g. `data:audio/mp3;base64,...`, up to 16MB) containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information.", "example": "https://example.com/audio.mp3", "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"] } }, "model": { "type": "string", "const": "seedance2_mini" } }, "required": ["promptImage", "model"], "additionalProperties": false }, { "title": "gemini_omni_flash", "type": "object", "properties": { "promptImage": { "description": "An image to use as the first frame of the output video. Gemini Omni Flash only supports a first 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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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"] } } ] }, "promptText": { "description": "An optional text prompt describing how the video should evolve from the first frame.", "type": "string", "minLength": 1, "maxLength": 4000 }, "ratio": { "description": "The aspect ratio of the output video: `1280:720` (landscape) or `720:1280` (portrait).", "type": "string", "enum": ["1280:720", "720:1280"] }, "duration": { "description": "The duration of the output video in seconds, as a whole number from 3 to 10.", "type": "integer", "minimum": 3, "maximum": 10 }, "model": { "type": "string", "const": "gemini_omni_flash" } }, "required": ["promptImage", "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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" ] }, "negativePrompt": { "description": "Text describing what should not appear in the output video.", "type": "string", "minLength": 1, "maxLength": 1000 }, "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"] } }, "additionalProperties": false }, "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" }, "negativePrompt": { "description": "Text describing what should not appear in the output video.", "type": "string", "minLength": 1, "maxLength": 1000 }, "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" }, "negativePrompt": { "description": "Text describing what should not appear in the output video.", "type": "string", "minLength": 1, "maxLength": 1000 }, "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": "happyhorse_1_0", "type": "object", "properties": { "promptText": { "description": "A non-empty string up to 2500 characters (measured in UTF-16 code units). This should describe in detail what should appear in the output.", "type": "string", "minLength": 2, "maxLength": 2500 }, "duration": { "description": "The number of seconds of duration for the output video.", "type": "integer", "minimum": 3, "maximum": 15 }, "ratio": { "description": "The resolution of the output video.", "type": "string", "enum": [ "1280:720", "720:1280", "960:960", "1108:832", "832:1108", "1920:1080", "1080:1920", "1440:1440", "1662:1248", "1248:1662" ] }, "model": { "type": "string", "const": "happyhorse_1_0" } }, "required": ["promptText", "model"], "additionalProperties": false }, { "title": "seedance2", "type": "object", "properties": { "promptText": { "description": "A non-empty text prompt up to 3500 characters describing what should appear in the output.", "type": "string", "minLength": 1, "maxLength": 3500 }, "audio": { "description": "Whether to generate audio for the video.", "default": true, "type": "boolean" }, "duration": { "description": "The number of seconds of duration for the output video.", "type": "integer", "minimum": 4, "maximum": 15 }, "ratio": { "description": "The resolution of the output video.", "type": "string", "enum": [ "992:432", "864:496", "752:560", "640:640", "560:752", "496:864", "1470:630", "1280:720", "1112:834", "960:960", "834:1112", "720:1280", "2206:946", "1920:1080", "1664:1248", "1440:1440", "1248:1664", "1080:1920", "3840:1646", "3840:2160", "3840:2880", "3840:3840", "2880:3840", "2160:3840" ] }, "references": { "description": "An optional array of image references (up to 9). See [our docs](/assets/inputs#images) on image inputs for more information.", "maxItems": 9, "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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": ["uri"], "additionalProperties": false } }, "referenceVideos": { "description": "An optional array of video references. The combined duration across all video references must not exceed 15 seconds. See [our docs](/assets/inputs#videos) on video inputs for more information.", "maxItems": 3, "type": "array", "items": { "title": "VideoReference", "description": "A video reference allows the model to use the video as additional context for the output.", "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, Runway upload URI, or base64 data URI (e.g. `data:video/mp4;base64,...`, up to 16MB) containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information.", "example": "https://example.com/video.mp4", "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"] } }, "referenceAudio": { "description": "An optional array of audio references. Audio references require a text prompt, and the total combined duration must not exceed 15 seconds.", "maxItems": 3, "type": "array", "items": { "title": "AudioReference", "description": "An audio reference allows the model to use the audio as additional context for the output.", "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, Runway upload URI, or base64 data URI (e.g. `data:audio/mp3;base64,...`, up to 16MB) containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information.", "example": "https://example.com/audio.mp3", "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"] } }, "model": { "type": "string", "const": "seedance2" } }, "required": ["promptText", "model"], "additionalProperties": false }, { "title": "seedance2_fast", "type": "object", "properties": { "promptText": { "description": "A non-empty text prompt up to 3500 characters describing what should appear in the output.", "type": "string", "minLength": 1, "maxLength": 3500 }, "audio": { "description": "Whether to generate audio for the video.", "default": true, "type": "boolean" }, "duration": { "description": "The number of seconds of duration for the output video.", "type": "integer", "minimum": 4, "maximum": 15 }, "ratio": { "description": "The resolution of the output video. Seedance 2.0 Fast supports 480p and 720p only.", "type": "string", "enum": [ "992:432", "864:496", "752:560", "640:640", "560:752", "496:864", "1470:630", "1280:720", "1112:834", "960:960", "834:1112", "720:1280" ] }, "references": { "description": "An optional array of image references (up to 9). See [our docs](/assets/inputs#images) on image inputs for more information.", "maxItems": 9, "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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": ["uri"], "additionalProperties": false } }, "referenceVideos": { "description": "An optional array of video references. The combined duration across all video references must not exceed 15 seconds. See [our docs](/assets/inputs#videos) on video inputs for more information.", "maxItems": 3, "type": "array", "items": { "title": "VideoReference", "description": "A video reference allows the model to use the video as additional context for the output.", "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, Runway upload URI, or base64 data URI (e.g. `data:video/mp4;base64,...`, up to 16MB) containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information.", "example": "https://example.com/video.mp4", "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"] } }, "referenceAudio": { "description": "An optional array of audio references. Audio references require a text prompt, and the total combined duration must not exceed 15 seconds.", "maxItems": 3, "type": "array", "items": { "title": "AudioReference", "description": "An audio reference allows the model to use the audio as additional context for the output.", "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, Runway upload URI, or base64 data URI (e.g. `data:audio/mp3;base64,...`, up to 16MB) containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information.", "example": "https://example.com/audio.mp3", "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"] } }, "model": { "type": "string", "const": "seedance2_fast" } }, "required": ["promptText", "model"], "additionalProperties": false }, { "title": "seedance2_mini", "type": "object", "properties": { "promptText": { "description": "A non-empty text prompt up to 3500 characters describing what should appear in the output.", "type": "string", "minLength": 1, "maxLength": 3500 }, "audio": { "description": "Whether to generate audio for the video.", "default": true, "type": "boolean" }, "duration": { "description": "The number of seconds of duration for the output video.", "type": "integer", "minimum": 4, "maximum": 15 }, "ratio": { "description": "The resolution of the output video. Seedance 2.0 Mini supports 480p and 720p only.", "type": "string", "enum": [ "992:432", "864:496", "752:560", "640:640", "560:752", "496:864", "1470:630", "1280:720", "1112:834", "960:960", "834:1112", "720:1280" ] }, "references": { "description": "An optional array of image references (up to 9). See [our docs](/assets/inputs#images) on image inputs for more information.", "maxItems": 9, "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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": ["uri"], "additionalProperties": false } }, "referenceVideos": { "description": "An optional array of video references. The combined duration across all video references must not exceed 15 seconds. See [our docs](/assets/inputs#videos) on video inputs for more information.", "maxItems": 3, "type": "array", "items": { "title": "VideoReference", "description": "A video reference allows the model to use the video as additional context for the output.", "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, Runway upload URI, or base64 data URI (e.g. `data:video/mp4;base64,...`, up to 16MB) containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information.", "example": "https://example.com/video.mp4", "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"] } }, "referenceAudio": { "description": "An optional array of audio references. Audio references require a text prompt, and the total combined duration must not exceed 15 seconds.", "maxItems": 3, "type": "array", "items": { "title": "AudioReference", "description": "An audio reference allows the model to use the audio as additional context for the output.", "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, Runway upload URI, or base64 data URI (e.g. `data:audio/mp3;base64,...`, up to 16MB) containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information.", "example": "https://example.com/audio.mp3", "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"] } }, "model": { "type": "string", "const": "seedance2_mini" } }, "required": ["promptText", "model"], "additionalProperties": false }, { "title": "gemini_omni_flash", "type": "object", "properties": { "promptText": { "description": "A non-empty text prompt describing the video to generate.", "type": "string", "minLength": 1, "maxLength": 4000 }, "ratio": { "description": "The aspect ratio of the output video: `1280:720` (landscape) or `720:1280` (portrait).", "type": "string", "enum": ["1280:720", "720:1280"] }, "duration": { "description": "The duration of the output video in seconds, as a whole number from 3 to 10.", "type": "integer", "minimum": 3, "maximum": 10 }, "model": { "type": "string", "const": "gemini_omni_flash" } }, "required": ["promptText", "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" ] }, "negativePrompt": { "description": "Text describing what should not appear in the output video.", "type": "string", "minLength": 1, "maxLength": 1000 }, "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": [ { "type": "object", "properties": { "promptText": { "description": "A non-empty and optional string describing what should appear in the output.", "type": "string", "minLength": 1, "maxLength": 1000 }, "keyframes": { "description": "Timed guidance images placed at specific points in the input video. Up to 5 keyframes.", "title": "Keyframes", "minItems": 1, "maxItems": 5, "type": "array", "items": { "title": "Keyframe", "x-stainless-variantName": "Keyframe", "anyOf": [ { "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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\\/.*" } ] }, "seconds": { "description": "Absolute timestamp in seconds from the start of the input video when this guidance image should apply.", "type": "number", "minimum": 0, "maximum": 30 }, "range": { "description": "Optional edit window. When set, the edit applies only to this time range and the keyframe timestamp must fall within it. All keyframes must either set a range or none may.", "title": "KeyframeRange", "type": "object", "properties": { "start_seconds": { "description": "Start of the edit window in whole seconds from the start of the input video.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "end_seconds": { "description": "End of the edit window (exclusive) in whole seconds from the start of the input video.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": ["start_seconds", "end_seconds"], "additionalProperties": false } }, "required": ["uri", "seconds"], "additionalProperties": false }, { "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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\\/.*" } ] }, "at": { "description": "Position as a fraction [0.0, 1.0] of the input video duration when this guidance image should apply.", "type": "number", "minimum": 0, "maximum": 1 }, "range": { "description": "Optional edit window. When set, the edit applies only to this time range and the keyframe timestamp must fall within it. All keyframes must either set a range or none may.", "title": "KeyframeRange", "type": "object", "properties": { "start_seconds": { "description": "Start of the edit window in whole seconds from the start of the input video.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "end_seconds": { "description": "End of the edit window (exclusive) in whole seconds from the start of the input video.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": ["start_seconds", "end_seconds"], "additionalProperties": false } }, "required": ["uri", "at"], "additionalProperties": false } ] } }, "videoUri": { "description": "The input video to edit. Must be 30 seconds or shorter.", "example": "https://example.com/video.mp4", "anyOf": [ { "description": "A HTTPS URL, Runway upload URI, or base64 data URI (e.g. `data:video/mp4;base64,...`, up to 16MB) containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information.", "example": "https://example.com/video.mp4", "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\\/.*" } ] }, "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": { "deprecated": true, "type": "string" }, "targetAspectRatio": { "description": "Target aspect ratio for expand/outpaint. Letterboxes the input video and keyframes before generation.", "type": "string", "enum": [ "16:9", "4:3", "3:2", "1:1", "2:3", "3:4", "9:16", "21:9" ] }, "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"] } }, "additionalProperties": false }, "model": { "type": "string", "const": "aleph2" } }, "required": ["videoUri", "model"], "additionalProperties": false }, { "title": "seedance2", "type": "object", "properties": { "promptVideo": { "description": "The input video to use as a reference for the output video. If additional video references are provided, the combined duration across all video references must not exceed 15 seconds.", "example": "https://example.com/video.mp4", "anyOf": [ { "description": "A HTTPS URL, Runway upload URI, or base64 data URI (e.g. `data:video/mp4;base64,...`, up to 16MB) containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information.", "example": "https://example.com/video.mp4", "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": "An optional text prompt up to 3500 characters describing what should appear in the output.", "type": "string", "minLength": 1, "maxLength": 3500 }, "audio": { "description": "Whether to generate audio for the video.", "default": true, "type": "boolean" }, "duration": { "description": "The number of seconds of duration for the output video.", "type": "integer", "minimum": 4, "maximum": 15 }, "ratio": { "description": "The resolution of the output video.", "type": "string", "enum": [ "992:432", "864:496", "752:560", "640:640", "560:752", "496:864", "1470:630", "1280:720", "1112:834", "960:960", "834:1112", "720:1280", "2206:946", "1920:1080", "1664:1248", "1440:1440", "1248:1664", "1080:1920", "3840:1646", "3840:2160", "3840:2880", "3840:3840", "2880:3840", "2160:3840" ] }, "references": { "description": "An optional array of image references (up to 9). See [our docs](/assets/inputs#images) on image inputs for more information.", "maxItems": 9, "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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": ["uri"], "additionalProperties": false } }, "referenceVideos": { "description": "An optional array of video references. The combined duration across all video references must not exceed 15 seconds. See [our docs](/assets/inputs#videos) on video inputs for more information.", "maxItems": 3, "type": "array", "items": { "title": "VideoReference", "description": "A video reference allows the model to use the video as additional context for the output.", "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, Runway upload URI, or base64 data URI (e.g. `data:video/mp4;base64,...`, up to 16MB) containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information.", "example": "https://example.com/video.mp4", "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"] } }, "referenceAudio": { "description": "An optional array of audio references. Audio references require a text prompt, and the total combined duration must not exceed 15 seconds.", "maxItems": 3, "type": "array", "items": { "title": "AudioReference", "description": "An audio reference allows the model to use the audio as additional context for the output.", "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, Runway upload URI, or base64 data URI (e.g. `data:audio/mp3;base64,...`, up to 16MB) containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information.", "example": "https://example.com/audio.mp3", "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"] } }, "model": { "type": "string", "const": "seedance2" } }, "required": ["promptVideo", "model"], "additionalProperties": false }, { "title": "seedance2_fast", "type": "object", "properties": { "promptVideo": { "description": "The input video to use as a reference for the output video. If additional video references are provided, the combined duration across all video references must not exceed 15 seconds.", "example": "https://example.com/video.mp4", "anyOf": [ { "description": "A HTTPS URL, Runway upload URI, or base64 data URI (e.g. `data:video/mp4;base64,...`, up to 16MB) containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information.", "example": "https://example.com/video.mp4", "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": "An optional text prompt up to 3500 characters describing what should appear in the output.", "type": "string", "minLength": 1, "maxLength": 3500 }, "audio": { "description": "Whether to generate audio for the video.", "default": true, "type": "boolean" }, "duration": { "description": "The number of seconds of duration for the output video.", "type": "integer", "minimum": 4, "maximum": 15 }, "ratio": { "description": "The resolution of the output video. Seedance 2.0 Fast supports 480p and 720p only.", "type": "string", "enum": [ "992:432", "864:496", "752:560", "640:640", "560:752", "496:864", "1470:630", "1280:720", "1112:834", "960:960", "834:1112", "720:1280" ] }, "references": { "description": "An optional array of image references (up to 9). See [our docs](/assets/inputs#images) on image inputs for more information.", "maxItems": 9, "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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": ["uri"], "additionalProperties": false } }, "referenceVideos": { "description": "An optional array of video references. The combined duration across all video references must not exceed 15 seconds. See [our docs](/assets/inputs#videos) on video inputs for more information.", "maxItems": 3, "type": "array", "items": { "title": "VideoReference", "description": "A video reference allows the model to use the video as additional context for the output.", "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, Runway upload URI, or base64 data URI (e.g. `data:video/mp4;base64,...`, up to 16MB) containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information.", "example": "https://example.com/video.mp4", "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"] } }, "referenceAudio": { "description": "An optional array of audio references. Audio references require a text prompt, and the total combined duration must not exceed 15 seconds.", "maxItems": 3, "type": "array", "items": { "title": "AudioReference", "description": "An audio reference allows the model to use the audio as additional context for the output.", "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, Runway upload URI, or base64 data URI (e.g. `data:audio/mp3;base64,...`, up to 16MB) containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information.", "example": "https://example.com/audio.mp3", "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"] } }, "model": { "type": "string", "const": "seedance2_fast" } }, "required": ["promptVideo", "model"], "additionalProperties": false }, { "title": "seedance2_mini", "type": "object", "properties": { "promptVideo": { "description": "The input video to use as a reference for the output video. If additional video references are provided, the combined duration across all video references must not exceed 15 seconds.", "example": "https://example.com/video.mp4", "anyOf": [ { "description": "A HTTPS URL, Runway upload URI, or base64 data URI (e.g. `data:video/mp4;base64,...`, up to 16MB) containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information.", "example": "https://example.com/video.mp4", "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": "An optional text prompt up to 3500 characters describing what should appear in the output.", "type": "string", "minLength": 1, "maxLength": 3500 }, "audio": { "description": "Whether to generate audio for the video.", "default": true, "type": "boolean" }, "duration": { "description": "The number of seconds of duration for the output video.", "type": "integer", "minimum": 4, "maximum": 15 }, "ratio": { "description": "The resolution of the output video. Seedance 2.0 Mini supports 480p and 720p only.", "type": "string", "enum": [ "992:432", "864:496", "752:560", "640:640", "560:752", "496:864", "1470:630", "1280:720", "1112:834", "960:960", "834:1112", "720:1280" ] }, "references": { "description": "An optional array of image references (up to 9). See [our docs](/assets/inputs#images) on image inputs for more information.", "maxItems": 9, "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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": ["uri"], "additionalProperties": false } }, "referenceVideos": { "description": "An optional array of video references. The combined duration across all video references must not exceed 15 seconds. See [our docs](/assets/inputs#videos) on video inputs for more information.", "maxItems": 3, "type": "array", "items": { "title": "VideoReference", "description": "A video reference allows the model to use the video as additional context for the output.", "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, Runway upload URI, or base64 data URI (e.g. `data:video/mp4;base64,...`, up to 16MB) containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information.", "example": "https://example.com/video.mp4", "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"] } }, "referenceAudio": { "description": "An optional array of audio references. Audio references require a text prompt, and the total combined duration must not exceed 15 seconds.", "maxItems": 3, "type": "array", "items": { "title": "AudioReference", "description": "An audio reference allows the model to use the audio as additional context for the output.", "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, Runway upload URI, or base64 data URI (e.g. `data:audio/mp3;base64,...`, up to 16MB) containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information.", "example": "https://example.com/audio.mp3", "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"] } }, "model": { "type": "string", "const": "seedance2_mini" } }, "required": ["promptVideo", "model"], "additionalProperties": false }, { "title": "gemini_omni_flash", "type": "object", "properties": { "videoUri": { "description": "The input video to edit. The output is 720p, with the orientation (landscape or portrait) matched to the input. The output duration matches the input, up to 10 seconds. The input must be at most 10 seconds.", "example": "https://example.com/video.mp4", "anyOf": [ { "description": "A HTTPS URL, Runway upload URI, or base64 data URI (e.g. `data:video/mp4;base64,...`, up to 16MB) containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information.", "example": "https://example.com/video.mp4", "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 instruction describing the edit to apply.", "type": "string", "minLength": 1, "maxLength": 4000 }, "references": { "description": "An optional array of image references to guide the edit.", "maxItems": 5, "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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": ["uri"], "additionalProperties": false } }, "model": { "type": "string", "const": "gemini_omni_flash" } }, "required": ["videoUri", "promptText", "model"], "additionalProperties": false } ], "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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. Must be 3-16 characters, start with a letter, and use only letters, digits, and underscores (no hyphens or other punctuation).", "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"] } }, "additionalProperties": false }, "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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. Must be 3-16 characters, start with a letter, and use only letters, digits, and underscores (no hyphens or other punctuation).", "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"] } }, "additionalProperties": false }, "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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. Must be 3-16 characters, start with a letter, and use only letters, digits, and underscores (no hyphens or other punctuation).", "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": "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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. Must be 3-16 characters, start with a letter, and use only letters, digits, and underscores (no hyphens or other punctuation).", "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_image3.1_flash", "type": "object", "properties": { "promptText": { "description": "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": [ "512:512", "416:624", "624:416", "432:592", "592:432", "448:576", "576:448", "384:672", "672:384", "768:336", "256:1024", "1024:256", "176:1408", "1408:176", "1024:1024", "832:1248", "1248:832", "864:1184", "1184:864", "896:1152", "1152:896", "768:1344", "1344:768", "1536:672", "512:2048", "2048:512", "352:2816", "2816:352", "2048:2048", "1696:2528", "2528:1696", "1792:2400", "2400:1792", "1856:2304", "2304:1856", "1536:2752", "2752:1536", "3168:1344", "1024:4096", "4096:1024", "704:5632", "5632:704", "4096:4096", "3392:5056", "5056:3392", "3584:4800", "4800:3584", "3712:4608", "4608:3712", "3072:5504", "5504:3072", "6336:2688", "2048:8192", "8192:2048", "1408:11264", "11264:1408" ] }, "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": "Gemini31FlashReferenceImage", "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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. Must be 3-16 characters, start with a letter, and use only letters, digits, and underscores (no hyphens or other punctuation).", "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"] } }, "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.1_flash" } }, "required": ["promptText", "ratio", "model"] }, { "title": "seedream5_pro", "type": "object", "properties": { "promptText": { "description": "A non-empty string up to 4,000 characters describing the desired image.", "type": "string", "minLength": 1, "maxLength": 4000 }, "ratio": { "description": "The resolution of the output image, expressed as `:`. Use `auto_1k` or `auto_2k` to let the model pick aspect ratio at a fixed resolution tier.", "type": "string", "enum": [ "1024:1024", "1184:896", "896:1184", "1376:768", "768:1376", "1296:864", "864:1296", "2048:2048", "2304:1728", "1728:2304", "2720:1530", "1530:2720", "2496:1664", "1664:2496", "auto_1k", "auto_2k" ] }, "outputFormat": { "description": "The file format of the output image. Defaults to png.", "type": "string", "enum": ["png", "jpeg"] }, "referenceImages": { "description": "An array of reference images for multi-image fusion and interactive editing. Reference by upload order in prompt text (Figure 1, Figure 2, etc.).", "maxItems": 10, "type": "array", "items": { "title": "Seedream5ProReferenceImage", "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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": ["uri"], "additionalProperties": false } }, "outputCount": { "description": "The number of images to generate. Increasing this number will affect the number of credits consumed by the generation.", "type": "integer", "minimum": 1, "maximum": 4 }, "grounding": { "description": "When true, enable live web search so the model can use current brand, trend, or event context. Default false for deterministic output.", "type": "boolean" }, "model": { "type": "string", "const": "seedream5_pro" } }, "required": ["promptText", "ratio", "model"], "additionalProperties": false }, { "title": "seedream5_lite", "type": "object", "properties": { "promptText": { "description": "A non-empty string up to 4,000 characters describing the desired image.", "type": "string", "minLength": 1, "maxLength": 4000 }, "ratio": { "description": "The resolution of the output image, expressed as `:`.", "type": "string", "enum": [ "2048:2048", "2304:1728", "1728:2304", "2848:1600", "1600:2848", "2496:1664", "1664:2496", "3136:1344", "3072:3072", "3456:2592", "2592:3456", "4096:2304", "2304:4096", "3744:2496", "2496:3744", "4704:2016" ] }, "outputFormat": { "description": "The file format of the output image. Defaults to png.", "type": "string", "enum": ["png", "jpeg"] }, "referenceImages": { "description": "An array of reference images for multi-image fusion and interactive editing. Reference by upload order in prompt text (Figure 1, Figure 2, etc.).", "maxItems": 14, "type": "array", "items": { "title": "Seedream5LiteReferenceImage", "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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": ["uri"], "additionalProperties": false } }, "outputCount": { "description": "The number of images to generate. Increasing this number will affect the number of credits consumed by the generation.", "type": "integer", "minimum": 1, "maximum": 4 }, "model": { "type": "string", "const": "seedream5_lite" } }, "required": ["promptText", "ratio", "model"], "additionalProperties": false }, { "title": "gemini_2.5_flash", "type": "object", "properties": { "promptText": { "description": "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" ] }, "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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. Must be 3-16 characters, start with a letter, and use only letters, digits, and underscores (no hyphens or other punctuation).", "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/image_upscale": { "post": { "tags": ["Start generating"], "summary": "Image upscale", "description": "Upscale an image with Magnific precision upscaling. Each input dimension must be between 300px and 8000px. Output width and height are the input dimensions multiplied by `scaleFactor` (default 2). Output width times height cannot exceed 25,300,000 pixels (~25.3 million).", "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.imageUpscale\n .create({\n model: 'magnific_precision_upscaler_v2',\n imageUri: 'https://example.com/photo.jpg',\n scaleFactor: 2,\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.image_upscale.create(\n model='magnific_precision_upscaler_v2',\n image_uri='https://example.com/photo.jpg',\n scale_factor=2,\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": "magnific_precision_upscaler_v2", "type": "object", "properties": { "imageUri": { "description": "Image to upscale. See [image inputs](/assets/inputs#images) for URL, upload, and file size limits.", "example": "https://example.com/image.jpg", "anyOf": [ { "description": "A HTTPS URL, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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\\/.*" } ] }, "scaleFactor": { "description": "Multiplies each input dimension to produce output width and height. Defaults to 2.", "type": "number", "enum": [2, 4, 8, 16] }, "sharpen": { "description": "Sharpness intensity from 0 (none) to 100.", "type": "integer", "minimum": 0, "maximum": 100 }, "smartGrain": { "description": "Grain and texture enhancement from 0 to 100.", "type": "integer", "minimum": 0, "maximum": 100 }, "ultraDetail": { "description": "Fine detail enhancement from 0 to 100.", "type": "integer", "minimum": 0, "maximum": 100 }, "flavor": { "description": "Optimization preset: `sublime` (illustration), `photo` (photographic), or `photo_denoiser` (noisy photos).", "type": "string", "enum": ["sublime", "photo", "photo_denoiser"] }, "model": { "type": "string", "const": "magnific_precision_upscaler_v2" } }, "required": ["imageUri", "model"], "additionalProperties": false } ], "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_upscale": { "post": { "tags": ["Start generating"], "summary": "Video upscale", "description": "This endpoint starts a task to upscale a video. Set `model` to choose the upscaler.", "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.videoUpscale\n .create({\n model: 'magnific_video_upscaler_creative',\n videoUri: 'https://example.com/bunny.mp4',\n resolution: '2k',\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.video_upscale.create(\n model='magnific_video_upscaler_creative',\n video_uri='https://example.com/bunny.mp4',\n resolution='2k',\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": "magnific_video_upscaler_creative", "type": "object", "properties": { "videoUri": { "description": "Video to upscale. See [video inputs](/assets/inputs#videos) for URL, upload, and file size limits. Maximum duration is 30 seconds.", "example": "https://example.com/video.mp4", "anyOf": [ { "description": "A HTTPS URL, Runway upload URI, or base64 data URI (e.g. `data:video/mp4;base64,...`, up to 16MB) containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information.", "example": "https://example.com/video.mp4", "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\\/.*" } ] }, "resolution": { "description": "Target output resolution from 720p to 4k. Defaults to `2k`.", "type": "string", "enum": ["720p", "1k", "2k", "4k"] }, "creativity": { "description": "How much AI-generated detail to add during upscaling, from 0 (faithful) to 100.", "type": "integer", "minimum": 0, "maximum": 100 }, "sharpen": { "description": "Sharpness intensity from 0 (none) to 100.", "type": "integer", "minimum": 0, "maximum": 100 }, "smartGrain": { "description": "Grain and texture enhancement from 0 to 100.", "type": "integer", "minimum": 0, "maximum": 100 }, "flavor": { "description": "Processing style: `vivid` for enhanced color and detail, `natural` for faithful reproduction.", "type": "string", "enum": ["vivid", "natural"] }, "fpsBoost": { "description": "Whether to increase the output frame rate.", "type": "boolean" }, "model": { "type": "string", "const": "magnific_video_upscaler_creative" } }, "required": ["videoUri", "model"], "additionalProperties": false } ], "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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, Runway upload URI, or base64 data URI (e.g. `data:video/mp4;base64,...`, up to 16MB) containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information.", "example": "https://example.com/video.mp4", "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, Runway upload URI, or base64 data URI (e.g. `data:video/mp4;base64,...`, up to 16MB) containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information.", "example": "https://example.com/video.mp4", "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"] } }, "additionalProperties": false }, "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": "seed_audio", "type": "object", "properties": { "promptText": { "description": "A non-empty text prompt. For text-to-speech, the words to speak. For text-to-audio, a scene description that can include voice direction, dialogue, music, and sound effects.", "type": "string", "minLength": 1, "maxLength": 2048 }, "referenceAudios": { "description": "Up to three reference audio clips. When provided, reference them in promptText as @Audio1, @Audio2, and @Audio3 in order.", "maxItems": 3, "type": "array", "items": { "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, Runway upload URI, or base64 data URI (e.g. `data:audio/mp3;base64,...`, up to 16MB) containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information.", "example": "https://example.com/audio.mp3", "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\\/.*" } ] } }, "speechRate": { "description": "Relative speech speed. Negative is slower, positive is faster; 0 is normal.", "type": "integer", "minimum": -50, "maximum": 100 }, "loudnessRate": { "description": "Relative output loudness. Negative is quieter, positive is louder; 0 is normal.", "type": "integer", "minimum": -50, "maximum": 100 }, "pitchRate": { "description": "Pitch shift in semitones. Negative lowers, positive raises; 0 is unchanged.", "type": "integer", "minimum": -12, "maximum": 12 }, "sampleRate": { "description": "Output sample rate in Hz.", "type": "number", "enum": [8000, 16000, 24000, 32000, 44100, 48000] }, "outputFormat": { "description": "Output audio container/format.", "type": "string", "enum": ["wav", "mp3", "ogg_opus"] }, "model": { "type": "string", "const": "seed_audio" } }, "required": ["promptText", "model"], "additionalProperties": false }, { "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, Runway upload URI, or base64 data URI (e.g. `data:audio/mp3;base64,...`, up to 16MB) containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information.", "example": "https://example.com/audio.mp3", "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, Runway upload URI, or base64 data URI (e.g. `data:video/mp4;base64,...`, up to 16MB) containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information.", "example": "https://example.com/video.mp4", "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": "seed_audio", "type": "object", "properties": { "promptText": { "description": "A non-empty text prompt. For text-to-speech, the words to speak. For text-to-audio, a scene description that can include voice direction, dialogue, music, and sound effects.", "type": "string", "minLength": 1, "maxLength": 2048 }, "voice": { "description": "The voice to use for text-to-speech generation. If omitted, a default voice is used.", "oneOf": [ { "title": "SeedReferenceVoice", "description": "Clone from a single reference audio clip, then speak promptText in that voice.", "type": "object", "properties": { "type": { "type": "string", "const": "reference-audio" }, "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, Runway upload URI, or base64 data URI (e.g. `data:audio/mp3;base64,...`, up to 16MB) containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information.", "example": "https://example.com/audio.mp3", "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", "audioUri"] } ], "discriminator": { "propertyName": "type" } }, "speechRate": { "description": "Relative speech speed. Negative is slower, positive is faster; 0 is normal.", "type": "integer", "minimum": -50, "maximum": 100 }, "loudnessRate": { "description": "Relative output loudness. Negative is quieter, positive is louder; 0 is normal.", "type": "integer", "minimum": -50, "maximum": 100 }, "pitchRate": { "description": "Pitch shift in semitones. Negative lowers, positive raises; 0 is unchanged.", "type": "integer", "minimum": -12, "maximum": 12 }, "sampleRate": { "description": "Output sample rate in Hz.", "type": "number", "enum": [8000, 16000, 24000, 32000, 44100, 48000] }, "outputFormat": { "description": "Output audio container/format.", "type": "string", "enum": ["wav", "mp3", "ogg_opus"] }, "model": { "type": "string", "const": "seed_audio" } }, "required": ["promptText", "model"], "additionalProperties": false }, { "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, Runway upload URI, or base64 data URI (e.g. `data:audio/mp3;base64,...`, up to 16MB) containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information.", "example": "https://example.com/audio.mp3", "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, Runway upload URI, or base64 data URI (e.g. `data:audio/mp3;base64,...`, up to 16MB) containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information.", "example": "https://example.com/audio.mp3", "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/generate/video": { "post": { "tags": ["Model Router"], "summary": "Routed video generation", "description": "Start a video generation task using a saved Model Router config instead of naming a model.", "parameters": [{ "$ref": "#/components/parameters/X-Runway-Version" }], "requestBody": { "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "RoutedVideoRequest", "type": "object", "properties": { "configId": { "description": "The slug of a saved Model Router config to route this request with.", "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,63}$" }, "input": { "title": "UniversalVideoInput", "description": "Model-agnostic video generation input. Fields are optional; the router selects a model and maps these options to it.", "type": "object", "properties": { "promptText": { "description": "A text prompt describing the desired video.", "type": "string", "minLength": 1, "maxLength": 4000 }, "negativePrompt": { "description": "A text description of what to avoid in the output.", "type": "string", "maxLength": 1000 }, "referenceImages": { "description": "Optional image inputs. Each entry requires a `role`. At most one `first` and one `last` are allowed; multiple `reference` images are allowed.", "maxItems": 4, "type": "array", "items": { "title": "VideoReferenceImage", "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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\\/.*" } ] }, "role": { "description": "How the image is used. `first` is the starting frame; `last` is an end frame; `reference` is additional image context.", "type": "string", "enum": ["first", "last", "reference"] } }, "required": ["uri", "role"] } }, "referenceVideos": { "description": "Optional video inputs. Each entry requires a `role`. Use `source` for video-to-video; use `reference` for additional context videos (only models that support them remain eligible). At most one `source` is allowed.", "maxItems": 2, "type": "array", "items": { "title": "VideoReferenceVideo", "type": "object", "properties": { "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, Runway upload URI, or base64 data URI (e.g. `data:video/mp4;base64,...`, up to 16MB) containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information.", "example": "https://example.com/video.mp4", "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\\/.*" } ] }, "role": { "description": "How the video is used. `source` is the primary video-to-video input; `reference` is additional video context.", "type": "string", "enum": ["source", "reference"] } }, "required": ["uri", "role"] } }, "referenceAudio": { "description": "Optional audio inputs for the generation.", "maxItems": 1, "type": "array", "items": { "title": "VideoReferenceAudio", "type": "object", "properties": { "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, Runway upload URI, or base64 data URI (e.g. `data:audio/mp3;base64,...`, up to 16MB) containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information.", "example": "https://example.com/audio.mp3", "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": ["uri"] } }, "keyframes": { "description": "Timed guidance images for video restyle. Requires a source video; unsupported models are excluded.", "maxItems": 5, "type": "array", "items": { "title": "VideoKeyframe", "description": "Timed guidance image for video-to-video restyle. Provide either absolute `seconds` or fractional `at`.", "anyOf": [ { "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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\\/.*" } ] }, "seconds": { "type": "number", "minimum": 0, "maximum": 30 }, "range": { "type": "object", "properties": { "start_seconds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "end_seconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": ["start_seconds", "end_seconds"], "additionalProperties": false } }, "required": ["uri", "seconds"], "additionalProperties": false }, { "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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\\/.*" } ] }, "at": { "type": "number", "minimum": 0, "maximum": 1 }, "range": { "type": "object", "properties": { "start_seconds": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "end_seconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": ["start_seconds", "end_seconds"], "additionalProperties": false } }, "required": ["uri", "at"], "additionalProperties": false } ] } }, "duration": { "description": "Desired duration of the output video, in seconds. Unsupported values exclude models; with a source video, V2V duration support applies.", "type": "integer", "minimum": 2, "maximum": 15 }, "aspectRatio": { "description": "Desired aspect ratio. Models that do not support the requested aspect are excluded.", "type": "string", "enum": ["16:9", "9:16", "1:1", "4:3", "3:4", "21:9"] }, "resolution": { "description": "Desired output resolution tier. Models that do not support the requested tier are excluded.", "type": "string", "enum": ["480p", "720p", "1080p", "4k"] }, "audio": { "description": "Whether to generate native audio with the video. When true, only models that output audio remain eligible; when false, silent models and models with an audio toggle remain eligible (always-on native-audio models are excluded). When omitted, the selected model's default applies.", "type": "boolean" }, "seed": { "description": "A seed for reproducible generation. Random if omitted.", "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"] } }, "additionalProperties": false } }, "additionalProperties": false } }, "required": ["configId", "input"], "additionalProperties": false } } } }, "responses": { "200": { "description": "The routing decision. Includes a task `id` for real requests; dry runs return the decision only.", "content": { "application/json": { "schema": { "title": "RoutedVideoTaskCreated", "type": "object", "properties": { "id": { "description": "The ID of the created task. Poll GET /v1/tasks/:id for the result.", "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})$" }, "routing": { "description": "Metadata describing which model the router selected and why.", "type": "object", "properties": { "model": { "description": "The public name of the model the router selected.", "type": "string" }, "provider": { "description": "The provider of the selected model.", "type": "string" }, "configId": { "description": "The slug of the router config that was applied to this request.", "type": "string" }, "resolvedSettings": { "description": "The resolved config settings the router used for this request.", "type": "object", "properties": { "optimizeFor": { "description": "The single optimization preference the config selected, used as the soft weighting when scoring eligible models.", "type": "string", "enum": ["cost", "latency", "quality"] }, "priceCeiling": { "description": "The applied maximum credits per generation for this request's modality, or null if the config sets no ceiling.", "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": ["optimizeFor", "priceCeiling"], "additionalProperties": false }, "resolvedInput": { "description": "Request-side defaults resolved for the routing response. Not necessarily identical to prepared model options.", "type": "object", "properties": { "duration": { "description": "Duration in seconds used for routing display (request value or router default).", "type": "number" }, "ratio": { "description": "Concrete output ratio derived from aspectRatio (e.g. \"1280:720\"), or the router default.", "type": "string" }, "resolution": { "description": "Resolution tier from the request, or the router default when omitted.", "type": "string" } }, "required": ["duration", "ratio", "resolution"], "additionalProperties": false }, "estimatedCost": { "description": "Estimated cost, computed against current pricing.", "type": "object", "properties": { "credits": { "description": "Estimated cost of the generation in credits.", "type": "number" } }, "required": ["credits"], "additionalProperties": false } }, "required": [ "model", "provider", "configId", "resolvedSettings", "resolvedInput", "estimatedCost" ], "additionalProperties": false } }, "required": ["id", "routing"], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "anyOf": [ { "description": "No model satisfies the config and request together. Returned identically for real and dry-run requests.", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "const": "no_eligible_model" }, "pipeline": { "description": "The hard-filter pipeline in execution order with survivor counts at each stage.", "type": "array", "items": { "type": "object", "properties": { "filter": { "type": "string", "enum": [ "capability", "prompt_length", "input_support", "allow_deny", "price" ] }, "remaining": { "description": "How many models remained eligible after this filter ran.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["filter", "remaining"], "additionalProperties": false } }, "emptiedBy": { "description": "The filter(s) that reduced the eligible pool to zero.", "type": "array", "items": { "type": "string", "enum": [ "capability", "prompt_length", "input_support", "allow_deny", "price" ] } } }, "required": ["error", "code", "pipeline", "emptiedBy"], "additionalProperties": false }, { "description": "The request was invalid - e.g. an input failed validation for the routed model.", "type": "object", "properties": { "error": { "description": "A message describing why the request was rejected.", "type": "string" }, "issues": { "description": "Field-level validation issues, when available.", "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": {} } } }, "required": ["error"], "additionalProperties": false } ] } } } }, "404": { "description": "The referenced router config does not exist or is not accessible to this account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "const": "router_config_not_found" } }, "required": ["error", "code"], "additionalProperties": false } } } } } } }, "/v1/generate/image": { "post": { "tags": ["Model Router"], "summary": "Routed image generation", "description": "Start an image generation task using a saved Model Router config instead of naming a model.", "parameters": [{ "$ref": "#/components/parameters/X-Runway-Version" }], "requestBody": { "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "RoutedImageRequest", "type": "object", "properties": { "configId": { "description": "The slug of a saved Model Router config to route this request with.", "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,63}$" }, "input": { "title": "UniversalImageInput", "description": "Model-agnostic image generation input. The router selects a model and maps these options to it.", "type": "object", "properties": { "promptText": { "description": "A text prompt describing the desired image.", "type": "string", "minLength": 1, "maxLength": 32000 }, "referenceImages": { "description": "Optional reference images for models that support them. Tags are assigned per model when omitted.", "maxItems": 16, "type": "array", "items": { "title": "ImageReferenceImage", "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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": ["uri"], "additionalProperties": false } }, "aspectRatio": { "description": "Desired aspect ratio. Models that do not support the requested aspect are excluded.", "type": "string", "enum": [ "16:9", "9:16", "1:1", "4:3", "3:4", "21:9", "2:3", "3:2", "4:5", "5:4" ] }, "resolution": { "description": "Desired megapixel tier. Models that do not support the requested tier are excluded.", "type": "string", "enum": ["1k", "2k", "4k"] }, "outputCount": { "description": "Number of images to generate (1-10). Models that cannot produce the exact count are excluded and cost scales with this value.", "type": "integer", "minimum": 1, "maximum": 10 }, "seed": { "description": "A seed for reproducible generation. Only gen4_image and gen4_image_turbo accept this field.", "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"] } }, "additionalProperties": false } }, "required": ["promptText"], "additionalProperties": false } }, "required": ["configId", "input"], "additionalProperties": false } } } }, "responses": { "200": { "description": "The routing decision. Includes a task `id` for real requests; dry runs return the decision only.", "content": { "application/json": { "schema": { "title": "RoutedImageTaskCreated", "type": "object", "properties": { "id": { "description": "The ID of the created task. Poll GET /v1/tasks/:id for the result.", "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})$" }, "routing": { "description": "Metadata describing which model the router selected and why.", "type": "object", "properties": { "model": { "description": "The public name of the model the router selected.", "type": "string" }, "provider": { "description": "The provider of the selected model.", "type": "string" }, "configId": { "description": "The slug of the router config that was applied to this request.", "type": "string" }, "resolvedSettings": { "description": "The resolved config settings the router used for this request.", "type": "object", "properties": { "optimizeFor": { "description": "The single optimization preference the config selected, used as the soft weighting when scoring eligible models.", "type": "string", "enum": ["cost", "latency", "quality"] }, "priceCeiling": { "description": "The applied maximum credits per generation for this request's modality, or null if the config sets no ceiling.", "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": ["optimizeFor", "priceCeiling"], "additionalProperties": false }, "resolvedInput": { "description": "Request-side defaults resolved for the routing response. Not necessarily identical to prepared model options.", "type": "object", "properties": { "ratio": { "description": "Concrete output ratio derived from aspectRatio and resolution for the selected model.", "type": "string" }, "aspectRatio": { "description": "Aspect ratio used for routing display.", "type": "string" }, "resolution": { "description": "Megapixel tier used for routing display.", "type": "string" } }, "required": ["ratio", "aspectRatio", "resolution"], "additionalProperties": false }, "estimatedCost": { "description": "Estimated cost, computed against current pricing.", "type": "object", "properties": { "credits": { "description": "Estimated cost of the generation in credits.", "type": "number" } }, "required": ["credits"], "additionalProperties": false } }, "required": [ "model", "provider", "configId", "resolvedSettings", "resolvedInput", "estimatedCost" ], "additionalProperties": false } }, "required": ["id", "routing"], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "anyOf": [ { "description": "No model satisfies the config and request together. Returned identically for real and dry-run requests.", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "const": "no_eligible_model" }, "pipeline": { "description": "The hard-filter pipeline in execution order with survivor counts at each stage.", "type": "array", "items": { "type": "object", "properties": { "filter": { "type": "string", "enum": [ "capability", "prompt_length", "input_support", "allow_deny", "price" ] }, "remaining": { "description": "How many models remained eligible after this filter ran.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["filter", "remaining"], "additionalProperties": false } }, "emptiedBy": { "description": "The filter(s) that reduced the eligible pool to zero.", "type": "array", "items": { "type": "string", "enum": [ "capability", "prompt_length", "input_support", "allow_deny", "price" ] } } }, "required": ["error", "code", "pipeline", "emptiedBy"], "additionalProperties": false }, { "description": "The request was invalid - e.g. an input failed validation for the routed model.", "type": "object", "properties": { "error": { "description": "A message describing why the request was rejected.", "type": "string" }, "issues": { "description": "Field-level validation issues, when available.", "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": {} } } }, "required": ["error"], "additionalProperties": false } ] } } } }, "404": { "description": "The referenced router config does not exist or is not accessible to this account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "const": "router_config_not_found" } }, "required": ["error", "code"], "additionalProperties": false } } } } } } }, "/v1/generate/audio": { "post": { "tags": ["Model Router"], "summary": "Routed audio generation", "description": "Start an audio generation task using a saved Model Router config instead of naming a model. Set input.type to speech to speak promptText verbatim, or audio to generate audio described by promptText.", "parameters": [{ "$ref": "#/components/parameters/X-Runway-Version" }], "requestBody": { "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "RoutedAudioRequest", "type": "object", "properties": { "configId": { "description": "The slug of a saved Model Router config to route this request with.", "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,63}$" }, "input": { "title": "UniversalAudioInput", "description": "Model-agnostic audio generation input. The router selects a model and maps these options to it.", "type": "object", "properties": { "type": { "description": "How promptText is interpreted: `speech` speaks it verbatim as a script; `audio` treats it as a description of the desired audio, which may combine speech, music, ambience, and sound effects.", "type": "string", "enum": ["speech", "audio"] }, "promptText": { "description": "For `speech`, the words to speak. For `audio`, a description of the desired output.", "type": "string", "minLength": 1, "maxLength": 3000 }, "voice": { "description": "The voice to speak with. When omitted, models that support a default voice remain eligible.", "oneOf": [ { "title": "AudioPresetVoice", "description": "A preset voice.", "type": "object", "properties": { "type": { "type": "string", "const": "preset" }, "presetId": { "description": "A Runway preset voice id. Choosing a preset routes only to models that support preset voices.", "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"], "additionalProperties": false }, { "title": "AudioReferenceVoice", "description": "Clone a voice from a reference audio clip, then speak promptText in that voice. Routes only to models that support voice cloning.", "type": "object", "properties": { "type": { "type": "string", "const": "reference-audio" }, "audioUri": { "description": "A 1-30 second clip to clone the voice from.", "example": "https://example.com/audio.mp3", "anyOf": [ { "description": "A HTTPS URL, Runway upload URI, or base64 data URI (e.g. `data:audio/mp3;base64,...`, up to 16MB) containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information.", "example": "https://example.com/audio.mp3", "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", "audioUri"], "additionalProperties": false } ], "discriminator": { "propertyName": "type" } }, "referenceAudios": { "description": "Optional reference audio clips guiding `audio` generation, for models that support them. Reference each clip in promptText as @Audio1, @Audio2, and @Audio3 in order.", "maxItems": 3, "type": "array", "items": { "title": "AudioReferenceAudio", "type": "object", "properties": { "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, Runway upload URI, or base64 data URI (e.g. `data:audio/mp3;base64,...`, up to 16MB) containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information.", "example": "https://example.com/audio.mp3", "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": ["uri"], "additionalProperties": false } }, "duration": { "description": "Desired output duration in seconds for `audio` generation. Models that cannot honor an explicit duration are excluded.", "type": "number", "minimum": 0.5, "maximum": 30 }, "loop": { "description": "When true, the `audio` output is designed to loop seamlessly. Models without loop support are excluded.", "type": "boolean" } }, "required": ["type", "promptText"], "additionalProperties": false } }, "required": ["configId", "input"], "additionalProperties": false } } } }, "responses": { "200": { "description": "The routing decision. Includes a task `id` for real requests; dry runs return the decision only.", "content": { "application/json": { "schema": { "title": "RoutedAudioTaskCreated", "type": "object", "properties": { "id": { "description": "The ID of the created task. Poll GET /v1/tasks/:id for the result.", "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})$" }, "routing": { "description": "Metadata describing which model the router selected and why.", "type": "object", "properties": { "model": { "description": "The public name of the model the router selected.", "type": "string" }, "provider": { "description": "The provider of the selected model.", "type": "string" }, "configId": { "description": "The slug of the router config that was applied to this request.", "type": "string" }, "resolvedSettings": { "description": "The resolved config settings the router used for this request.", "type": "object", "properties": { "optimizeFor": { "description": "The single optimization preference the config selected, used as the soft weighting when scoring eligible models.", "type": "string", "enum": ["cost", "latency", "quality"] }, "priceCeiling": { "description": "The applied maximum credits per generation for this request's modality, or null if the config sets no ceiling.", "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": ["optimizeFor", "priceCeiling"], "additionalProperties": false }, "resolvedInput": { "description": "Request-side defaults resolved for the routing response. Not necessarily identical to prepared model options.", "type": "object", "properties": { "type": { "description": "The prompt mode the router routed for.", "type": "string", "enum": ["speech", "audio"] }, "voice": { "description": "How the selected model resolves the voice: the requested preset or reference-audio clone, the model default for voiceless speech, or none for general audio.", "type": "string", "enum": [ "preset", "reference-audio", "default", "none" ] } }, "required": ["type", "voice"], "additionalProperties": false }, "estimatedCost": { "description": "Estimated cost, computed against current pricing.", "type": "object", "properties": { "credits": { "description": "Estimated cost of the generation in credits.", "type": "number" } }, "required": ["credits"], "additionalProperties": false } }, "required": [ "model", "provider", "configId", "resolvedSettings", "resolvedInput", "estimatedCost" ], "additionalProperties": false } }, "required": ["id", "routing"], "additionalProperties": false } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "anyOf": [ { "description": "No model satisfies the config and request together. Returned identically for real and dry-run requests.", "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "const": "no_eligible_model" }, "pipeline": { "description": "The hard-filter pipeline in execution order with survivor counts at each stage.", "type": "array", "items": { "type": "object", "properties": { "filter": { "type": "string", "enum": [ "capability", "prompt_length", "input_support", "allow_deny", "price" ] }, "remaining": { "description": "How many models remained eligible after this filter ran.", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["filter", "remaining"], "additionalProperties": false } }, "emptiedBy": { "description": "The filter(s) that reduced the eligible pool to zero.", "type": "array", "items": { "type": "string", "enum": [ "capability", "prompt_length", "input_support", "allow_deny", "price" ] } } }, "required": ["error", "code", "pipeline", "emptiedBy"], "additionalProperties": false }, { "description": "The request was invalid - e.g. an input failed validation for the routed model.", "type": "object", "properties": { "error": { "description": "A message describing why the request was rejected.", "type": "string" }, "issues": { "description": "Field-level validation issues, when available.", "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": {} } } }, "required": ["error"], "additionalProperties": false } ] } } } }, "404": { "description": "The referenced router config does not exist or is not accessible to this account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string", "const": "router_config_not_found" } }, "required": ["error", "code"], "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", "seedream5_pro", "seedream5_lite", "gemini_omni_flash", "eleven_multilingual_v2", "seed_audio", "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", "seedance2_fast", "seedance2_mini", "magnific_precision_upscaler_v2", "magnific_video_upscaler_creative", "kling2.5_turbo_pro", "kling3.0_pro", "kling3.0_4k", "kling3.0_standard", "klingO3_pro", "klingO3_standard", "klingO3_4k", "happyhorse_1_0", "aleph2", "product_swap", "product_ad", "multi_shot_video", "product_ugc", "marketing_stock_image", "product_campaign_image", "ad_localization" ] }, "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", "seedream5_pro", "seedream5_lite", "gemini_omni_flash", "eleven_multilingual_v2", "seed_audio", "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", "seedance2_fast", "seedance2_mini", "magnific_precision_upscaler_v2", "magnific_video_upscaler_creative", "kling2.5_turbo_pro", "kling3.0_pro", "kling3.0_4k", "kling3.0_standard", "klingO3_pro", "klingO3_standard", "klingO3_4k", "happyhorse_1_0", "aleph2", "product_swap", "product_ad", "multi_shot_video", "product_ugc", "marketing_stock_image", "product_campaign_image", "ad_localization" ] }, "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", "seedream5_pro", "seedream5_lite", "gemini_omni_flash", "eleven_multilingual_v2", "seed_audio", "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", "seedance2_fast", "seedance2_mini", "magnific_precision_upscaler_v2", "magnific_video_upscaler_creative", "kling2.5_turbo_pro", "kling3.0_pro", "kling3.0_4k", "kling3.0_standard", "klingO3_pro", "klingO3_standard", "klingO3_4k", "happyhorse_1_0", "aleph2", "product_swap", "product_ad", "multi_shot_video", "product_ugc", "marketing_stock_image", "product_campaign_image", "ad_localization" ] }, "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", "seedream5_pro", "seedream5_lite", "gemini_omni_flash", "eleven_multilingual_v2", "seed_audio", "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", "seedance2_fast", "seedance2_mini", "magnific_precision_upscaler_v2", "magnific_video_upscaler_creative", "kling2.5_turbo_pro", "kling3.0_pro", "kling3.0_4k", "kling3.0_standard", "klingO3_pro", "klingO3_standard", "klingO3_4k", "happyhorse_1_0", "aleph2", "product_swap", "product_ad", "multi_shot_video", "product_ugc", "marketing_stock_image", "product_campaign_image", "ad_localization" ] } }, "apiKeys": { "description": "Reserved for future use.", "type": "array", "items": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "resultsByApiKey": { "description": "Reserved for future use.", "type": "array", "items": { "type": "object", "properties": { "date": { "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": { "type": "array", "items": { "type": "object", "properties": { "apiKeyId": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "amount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": ["apiKeyId", "amount"], "additionalProperties": false } } }, "required": ["date", "usedCredits"], "additionalProperties": false } } }, "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.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": ["error"], "additionalProperties": false } } } } } } }, "/v1/recipes/ad_localization": { "post": { "tags": ["Recipes"], "summary": "Localize an ad image", "description": "Localize an existing ad image for a target language, preserving visual creative while adapting on-screen messaging.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\nconst client = new RunwayML();\n\nconst task = await client.recipes.adLocalization({\n version: '2026-06',\n referenceImage: { uri: 'https://example.com/source-ad.jpg' },\n targetLanguage: 'ja',\n});\n\nconsole.log(task);" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\nclient = RunwayML()\n\ntask = client.recipes.ad_localization(\n version='2026-06',\n reference_image={'uri': 'https://example.com/source-ad.jpg'},\n target_language='ja',\n)\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": { "version": { "description": "Workflow version. Use a dated version (e.g. \"2026-06\") to pin behavior, or \"unsafe-latest\" to track the newest stable version (may break without notice).", "type": "string", "enum": ["2026-06", "unsafe-latest"] }, "referenceImage": { "description": "Reference ad image to localize. See [our docs](/assets/inputs#images) on image inputs.", "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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": ["uri"], "additionalProperties": false }, "targetLanguage": { "description": "Target language for the localized ad. Use ISO-style codes (e.g. \"ja\" for Japanese, \"es\" for Spanish).", "type": "string", "enum": [ "ar", "zh", "zh-Hant", "nl", "en", "fr", "de", "hi", "id", "it", "ja", "ko", "pl", "pt", "ru", "es", "sv", "th", "tr", "uk", "vi", "el" ] } }, "required": ["version", "referenceImage", "targetLanguage"], "additionalProperties": false } } } }, "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/recipes/marketing_stock_image": { "post": { "tags": ["Recipes"], "summary": "Create a marketing stock image", "description": "Generate a polished marketing stock image from a text brief and optional brand logo image.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\nconst client = new RunwayML();\n\nconst task = await client.recipes.marketingStockImage({\n version: '2026-06',\n prompt: 'Premium lifestyle photo for a sustainable travel backpack campaign, urban morning commute, natural copy space on the left',\n referenceImage: { uri: 'https://example.com/brand-logo.png' },\n});\n\nconsole.log(task);" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\nclient = RunwayML()\n\ntask = client.recipes.marketing_stock_image(\n version='2026-06',\n prompt='Premium lifestyle photo for a sustainable travel backpack campaign, urban morning commute, natural copy space on the left',\n reference_image={'uri': 'https://example.com/brand-logo.png'},\n)\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": { "version": { "description": "Workflow version. Use a dated version (e.g. \"2026-06\") to pin behavior, or \"unsafe-latest\" to track the newest stable version (may break without notice).", "type": "string", "enum": ["2026-06", "unsafe-latest"] }, "prompt": { "description": "Marketing image brief. Describe the subject, audience, channel, desired mood, setting, and any constraints.", "type": "string", "minLength": 1, "maxLength": 3500 }, "referenceImage": { "description": "Optional brand logo image to guide the generated marketing stock image. See [our docs](/assets/inputs#images) on image inputs.", "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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": ["uri"], "additionalProperties": false }, "outputCount": { "description": "The number of images to generate (1-4). Defaults to 4. Increasing this number affects credits consumed.", "default": 4, "type": "integer", "minimum": 1, "maximum": 4 }, "quality": { "description": "GPT Image 2 rendering quality (`low`, `medium`, or `high`). Lower settings are faster and use fewer credits; `high` (default) is slowest and highest fidelity.", "default": "high", "type": "string", "enum": ["low", "medium", "high"] } }, "required": ["version", "prompt"], "additionalProperties": false } } } }, "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/recipes/product_ad": { "post": { "tags": ["Recipes"], "summary": "Create a product ad video", "description": "Generate a cinematic product ad from product images, optional style references, product info, and creative direction.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\nconst client = new RunwayML();\n\nconst task = await client.recipes.productAd({\n version: '2026-07',\n productImages: [\n { uri: 'https://example.com/product-front.jpg' },\n { uri: 'https://example.com/product-side.jpg' },\n ],\n productInfo: 'Organic cold-pressed juice, 12oz glass bottle',\n userConcept: 'Bright, refreshing summer campaign with slow dolly moves',\n duration: 10,\n});\n\nconsole.log(task);" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\nclient = RunwayML()\n\ntask = client.recipes.product_ad(\n version='2026-07',\n product_images=[\n {'uri': 'https://example.com/product-front.jpg'},\n {'uri': 'https://example.com/product-side.jpg'},\n ],\n product_info='Organic cold-pressed juice, 12oz glass bottle',\n user_concept='Bright, refreshing summer campaign with slow dolly moves',\n duration=10,\n)\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": { "version": { "description": "Workflow version. Use a dated version (e.g. \"2026-07\") to pin behavior, or \"unsafe-latest\" to track the newest stable version (may break without notice).", "type": "string", "enum": ["2026-06", "2026-07", "unsafe-latest"] }, "productImages": { "description": "Product images (1-10). Multiple angles of the same product. All images inform product analysis and reference generation; only the first image is used as the primary product reference in the storyboard grid. See [our docs](/assets/inputs#images) on image inputs.", "minItems": 1, "maxItems": 10, "type": "array", "items": { "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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": ["uri"], "additionalProperties": false } }, "styleImages": { "description": "Optional style reference images (0-4). Defines the visual treatment (lighting, palette, mood). Treated as a moodboard when multiple are provided.", "maxItems": 4, "type": "array", "items": { "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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": ["uri"], "additionalProperties": false } }, "productInfo": { "description": "Optional product description and specifications to inform creative direction and which product elements to highlight.", "default": "", "type": "string", "maxLength": 2500 }, "userConcept": { "description": "Optional creative direction describing brand voice, product framing, scene specifics, lighting, camera motion, and narrative.", "default": "", "type": "string", "maxLength": 3500 }, "ratio": { "description": "The resolution of the output video.", "type": "string", "enum": [ "1280:720", "720:1280", "960:960", "834:1112", "1920:1080", "1080:1920", "1440:1440", "1248:1664" ] }, "duration": { "description": "Duration of the output video in seconds (4-15). Defaults to 10 seconds.", "type": "integer", "minimum": 4, "maximum": 15 }, "audio": { "description": "Whether to generate audio for the video.", "default": false, "type": "boolean" } }, "required": ["version", "productImages"], "additionalProperties": false } } } }, "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/recipes/product_campaign_image": { "post": { "tags": ["Recipes"], "summary": "Create product campaign images", "description": "Generate four fashion campaign images from a product image and style brief.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\nconst client = new RunwayML();\n\nconst task = await client.recipes.productCampaignImage({\n version: '2026-06',\n image: { uri: 'https://example.com/product.jpg' },\n prompt: 'High-key fashion editorial, gorpcore-meets-blokecore-meets-Y2K',\n});\n\nconsole.log(task);" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\nclient = RunwayML()\n\ntask = client.recipes.product_campaign_image(\n version='2026-06',\n image={'uri': 'https://example.com/product.jpg'},\n prompt='High-key fashion editorial, gorpcore-meets-blokecore-meets-Y2K',\n)\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": { "version": { "description": "Workflow version. Use a dated version (e.g. \"2026-06\") to pin behavior, or \"unsafe-latest\" to track the newest stable version (may break without notice).", "type": "string", "enum": ["2026-06", "unsafe-latest"] }, "image": { "description": "Product image to preserve across the generated campaign. See [our docs](/assets/inputs#images) on image inputs.", "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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": ["uri"], "additionalProperties": false }, "prompt": { "description": "Style / creative brief for the fashion campaign, e.g. \"High-key fashion editorial, gorpcore-meets-blokecore-meets-Y2K\".", "type": "string", "minLength": 1, "maxLength": 3500 } }, "required": ["version", "image", "prompt"], "additionalProperties": false } } } }, "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/recipes/product_swap": { "post": { "tags": ["Recipes"], "summary": "Swap a product in a reference video", "description": "Replace the product in a reference video with a new product, preserving camera motion, lighting, and scene composition.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\nconst client = new RunwayML();\n\nconst task = await client.recipes.productSwap({\n version: '2026-06',\n referenceVideo: { uri: 'https://example.com/reference-ad.mp4' },\n originalProductImage: { uri: 'https://example.com/original-product.jpg' },\n newProductImages: [\n { uri: 'https://example.com/new-product-front.jpg', view: 'front' },\n { uri: 'https://example.com/new-product-side.jpg', view: 'side' },\n ],\n duration: 10,\n});\n\nconsole.log(task);" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\nclient = RunwayML()\n\ntask = client.recipes.product_swap(\n version='2026-06',\n reference_video={'uri': 'https://example.com/reference-ad.mp4'},\n original_product_image={'uri': 'https://example.com/original-product.jpg'},\n new_product_images=[\n {'uri': 'https://example.com/new-product-front.jpg', 'view': 'front'},\n {'uri': 'https://example.com/new-product-side.jpg', 'view': 'side'},\n ],\n duration=10,\n)\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": { "version": { "description": "Workflow version. Use a dated version (e.g. \"2026-06\") to pin behavior, or \"unsafe-latest\" to track the newest stable version (may break without notice).", "type": "string", "enum": ["2026-06", "unsafe-latest"] }, "referenceVideo": { "description": "Reference video containing the product to swap. Duration must be between 1.8 and 15 seconds. See [our docs](/assets/inputs#videos) on video inputs.", "type": "object", "properties": { "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, Runway upload URI, or base64 data URI (e.g. `data:video/mp4;base64,...`, up to 16MB) containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information.", "example": "https://example.com/video.mp4", "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": ["uri"], "additionalProperties": false }, "originalProductImage": { "description": "Image of the original product being swapped out. See [our docs](/assets/inputs#images) on image inputs.", "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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": ["uri"], "additionalProperties": false }, "newProductImages": { "description": "Reference images of the new product (1-10). Supply multiple angles when the reference video shows the product from different views - optionally label each with `view` (\"front\", \"side\", or \"back\"). A single pre-composed reference sheet is also supported (omit `view`). See [our docs](/assets/inputs#images) on image inputs.", "minItems": 1, "maxItems": 10, "type": "array", "items": { "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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\\/.*" } ] }, "view": { "description": "Optional view label for this reference (front, side, or back). Omit when supplying a single reference sheet or when view labels are unknown.", "type": "string", "enum": ["front", "side", "back"] } }, "required": ["uri"], "additionalProperties": false } }, "duration": { "description": "Duration of the output video in seconds (4-15). Defaults to 10 seconds.", "type": "integer", "minimum": 4, "maximum": 15 }, "resolution": { "description": "Output video resolution. Defaults to 720p.", "type": "string", "enum": ["720p", "1080p"] }, "audio": { "description": "Whether to generate audio for the video.", "default": true, "type": "boolean" } }, "required": [ "version", "referenceVideo", "originalProductImage", "newProductImages" ], "additionalProperties": false } } } }, "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/recipes/multi_shot_video": { "post": { "tags": ["Recipes"], "summary": "Create a multi-shot video", "description": "Generate a multi-cut video from a story prompt (auto mode) or a custom shot list (custom mode).", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\nconst client = new RunwayML();\n\nconst task = await client.recipes.multiShotVideo({\n version: '2026-06',\n prompt: 'A lone astronaut discovers a glowing forest on a distant planet',\n duration: 10,\n ratio: '1280:720',\n});\n\nconsole.log(task);" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\nclient = RunwayML()\n\ntask = client.recipes.multi_shot_video(\n version='2026-06',\n prompt='A lone astronaut discovers a glowing forest on a distant planet',\n duration=10,\n ratio='1280:720',\n)\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": [ { "type": "object", "properties": { "mode": { "description": "Workflow mode. `auto` decomposes a story prompt into exactly 5 shots.", "type": "string", "const": "auto" }, "prompt": { "description": "Story prompt for auto mode.", "type": "string", "minLength": 1, "maxLength": 2500 }, "version": { "description": "Workflow version. Use a dated version (e.g. \"2026-06\") to pin behavior, or \"unsafe-latest\" to track the newest stable version (may break without notice).", "type": "string", "enum": ["2026-06", "unsafe-latest"] }, "firstFrame": { "description": "Optional image used as the first frame of the output video. See [our docs](/assets/inputs#images) on image inputs.", "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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": ["uri"], "additionalProperties": false }, "ratio": { "description": "Output dimensions as width:height. 720p ratios (`1280:720`, `720:1280`, `960:960`) use the standard tier; 1080p ratios (`1920:1080`, `1080:1920`, `1440:1440`) use the pro tier. Defaults to `1280:720`.", "type": "string", "enum": [ "1280:720", "720:1280", "960:960", "1920:1080", "1080:1920", "1440:1440" ] }, "duration": { "description": "Total duration of the output video in seconds. Defaults to 10 seconds.", "type": "number", "enum": [5, 10, 15] }, "audio": { "description": "Whether to generate audio for the video.", "default": true, "type": "boolean" } }, "required": ["mode", "prompt", "version"], "additionalProperties": false }, { "type": "object", "properties": { "mode": { "description": "Workflow mode. `custom` polishes a user-provided shot list of 3-5 shots.", "type": "string", "const": "custom" }, "shots": { "description": "Shot list for custom mode (3-5 shots). Per-shot durations must sum to `duration`.", "minItems": 3, "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "prompt": { "description": "Shot description prompt.", "type": "string", "minLength": 3, "maxLength": 512 }, "duration": { "description": "Duration of this shot in seconds.", "type": "integer", "minimum": 1, "maximum": 15 } }, "required": ["prompt", "duration"], "additionalProperties": false } }, "version": { "description": "Workflow version. Use a dated version (e.g. \"2026-06\") to pin behavior, or \"unsafe-latest\" to track the newest stable version (may break without notice).", "type": "string", "enum": ["2026-06", "unsafe-latest"] }, "firstFrame": { "description": "Optional image used as the first frame of the output video. See [our docs](/assets/inputs#images) on image inputs.", "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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": ["uri"], "additionalProperties": false }, "ratio": { "description": "Output dimensions as width:height. 720p ratios (`1280:720`, `720:1280`, `960:960`) use the standard tier; 1080p ratios (`1920:1080`, `1080:1920`, `1440:1440`) use the pro tier. Defaults to `1280:720`.", "type": "string", "enum": [ "1280:720", "720:1280", "960:960", "1920:1080", "1080:1920", "1440:1440" ] }, "duration": { "description": "Total duration of the output video in seconds. Defaults to 10 seconds.", "type": "number", "enum": [5, 10, 15] }, "audio": { "description": "Whether to generate audio for the video.", "default": true, "type": "boolean" } }, "required": ["mode", "shots", "version"], "additionalProperties": false } ], "discriminator": { "propertyName": "mode" } } } } }, "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/recipes/product_ugc": { "post": { "tags": ["Recipes"], "summary": "Create a product UGC video", "description": "Generate a vertical user-generated content ad from a character image, product image, product details, and optional creative direction.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "// npm install --save @runwayml/sdk\nimport RunwayML from '@runwayml/sdk';\n\nconst client = new RunwayML();\n\nconst task = await client.recipes.productUgc({\n version: '2026-06',\n characterImage: { uri: 'https://example.com/creator.jpg' },\n productImage: { uri: 'https://example.com/product.jpg' },\n productInfo: 'Wireless game controller with haptic feedback triggers',\n userConcept: 'Enthusiastic creator tone, demonstrate the product in hand',\n duration: 15,\n});\n\nconsole.log(task);" }, { "lang": "Python", "label": "Python SDK", "source": "# pip install runwayml\nfrom runwayml import RunwayML\n\nclient = RunwayML()\n\ntask = client.recipes.product_ugc(\n version='2026-06',\n character_image={'uri': 'https://example.com/creator.jpg'},\n product_image={'uri': 'https://example.com/product.jpg'},\n product_info='Wireless game controller with haptic feedback triggers',\n user_concept='Enthusiastic creator tone, demonstrate the product in hand',\n duration=15,\n)\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": { "version": { "description": "Workflow version. Use a dated version (e.g. \"2026-06\") to pin behavior, or \"unsafe-latest\" to track the newest stable version (may break without notice).", "type": "string", "enum": ["2026-06", "unsafe-latest"] }, "characterImage": { "description": "Image of the character who will appear on camera in the UGC video. Aspect ratio (width / height) must be between 0.4 and 4. See [our docs](/assets/inputs#images) for image input requirements.", "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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": ["uri"], "additionalProperties": false }, "productImage": { "description": "Image of the product being promoted. Aspect ratio (width / height) must be between 0.4 and 4. See [our docs](/assets/inputs#images) for image input requirements.", "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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": ["uri"], "additionalProperties": false }, "productInfo": { "description": "Product details and creative brief - what the product is, key benefits, and any specifics the script should reference.", "default": "", "type": "string", "maxLength": 2500 }, "userConcept": { "description": "Optional creative direction for the UGC video - tone, voice register, specific message, or an entire dialog script.", "default": "", "type": "string", "maxLength": 3500 }, "duration": { "description": "Duration of the output video in seconds (4-15). Defaults to 15 seconds.", "type": "integer", "minimum": 4, "maximum": 15 }, "ratio": { "description": "The resolution of the output video.", "type": "string", "enum": ["720:1280", "1080:1920"] }, "audio": { "description": "Whether to generate audio for the video.", "default": true, "type": "boolean" } }, "required": ["version", "characterImage", "productImage"], "additionalProperties": false } } } }, "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/routers": { "get": { "tags": ["Model Router"], "summary": "List Model Routers", "description": "List Model Router configurations 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\nconst client = new RunwayML();\nconst routers = await client.routers.list();\nfor await (const router of routers) {\n console.log(router);\n}" } ], "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": "A paginated list of Model Router configurations.", "content": { "application/json": { "schema": { "title": "ModelRouterList", "type": "object", "properties": { "data": { "description": "The list of items for the current page.", "type": "array", "items": { "title": "ModelRouter", "description": "A named Model Router configuration.", "type": "object", "properties": { "id": { "description": "The Model Router's primary key ID (UUID). Use it to manage this router via the API; use the slug to reference the router in generation requests.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "slug": { "description": "Immutable slug used to reference this Model Router in generation requests (for example, production-video). Unique within the API project. The UUID id remains the canonical management identifier.", "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,63}$" }, "name": { "description": "Human-friendly Model Router display name shown in the dev portal. Mutable, and not used to reference the router in requests.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "description": "An optional Model Router description.", "anyOf": [{ "type": "string" }, { "type": "null" }] }, "version": { "description": "Current settings version. Increments when settings change; name and description updates do not create a new version.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "settings": { "type": "object", "properties": { "schemaVersion": { "description": "Settings JSON schema version used when this snapshot was written.", "type": "number", "const": 1 }, "models": { "description": "When mode is allow_new_except, ids are excluded; when allowlist_only, ids are the only allowed values. Each id must be a known public video or image model name (unknown ids are rejected on create/update).", "type": "object", "properties": { "mode": { "type": "string", "enum": [ "allow_new_except", "allowlist_only" ] }, "ids": { "type": "array", "items": { "type": "string" } } }, "required": ["mode", "ids"], "additionalProperties": false }, "maxCreditsPerGeneration": { "description": "Optional per-modality credit caps, applied per generated output. Models whose estimated per-output cost exceeds the cap are excluded.", "type": "object", "properties": { "video": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "image": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "audio": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "optimizeFor": { "description": "Soft preference among eligible models: cost, latency, or quality.", "type": "string", "enum": ["cost", "latency", "quality"] } }, "required": ["schemaVersion"], "additionalProperties": false }, "createdAt": { "description": "When the Model Router 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 Model Router 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", "slug", "name", "description", "version", "settings", "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 } } } } } }, "post": { "tags": ["Model Router"], "summary": "Create Model Router", "description": "Create a Model Router configuration.", "x-codeSamples": [ { "lang": "TypeScript", "label": "Node SDK", "source": "import RunwayML from '@runwayml/sdk';\n\nconst client = new RunwayML();\nconst router = await client.routers.create({\n slug: 'preview-fast',\n name: 'Preview (fast)',\n settings: {\n optimizeFor: 'cost',\n },\n});" } ], "parameters": [{ "$ref": "#/components/parameters/X-Runway-Version" }], "requestBody": { "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ModelRouterCreateRequest", "type": "object", "properties": { "slug": { "description": "Immutable slug used to reference this Model Router in generation requests (for example, production-video). Unique within the API project. The UUID id remains the canonical management identifier.", "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,63}$" }, "name": { "description": "Optional human-readable display name for this router. Defaults to the slug when omitted.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "description": "An optional Model Router description.", "type": "string", "maxLength": 2000 }, "settings": { "description": "Model Router routing preferences. Defaults to cost-optimized allow-all when omitted. Modality is implied by the generate endpoint used with this Model Router.", "title": "ModelRouterSettings", "type": "object", "properties": { "schemaVersion": { "description": "Settings JSON schema version. Omit on write to use the current version; responses and stored snapshots always include it.", "type": "number", "const": 1 }, "models": { "description": "When mode is allow_new_except, ids are excluded; when allowlist_only, ids are the only allowed values. Each id must be a known public video or image model name (unknown ids are rejected on create/update).", "type": "object", "properties": { "mode": { "type": "string", "enum": ["allow_new_except", "allowlist_only"] }, "ids": { "type": "array", "items": { "type": "string" } } }, "required": ["mode", "ids"], "additionalProperties": false }, "maxCreditsPerGeneration": { "description": "Optional per-modality credit caps, applied per generated output. Models whose estimated per-output cost exceeds the cap are excluded.", "type": "object", "properties": { "video": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "image": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "audio": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "optimizeFor": { "description": "Soft preference among eligible models: cost, latency, or quality.", "type": "string", "enum": ["cost", "latency", "quality"] } }, "additionalProperties": false } }, "required": ["slug"] } } } }, "responses": { "200": { "description": "A named Model Router configuration.", "content": { "application/json": { "schema": { "title": "ModelRouter", "type": "object", "properties": { "id": { "description": "The Model Router's primary key ID (UUID). Use it to manage this router via the API; use the slug to reference the router in generation requests.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "slug": { "description": "Immutable slug used to reference this Model Router in generation requests (for example, production-video). Unique within the API project. The UUID id remains the canonical management identifier.", "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,63}$" }, "name": { "description": "Human-friendly Model Router display name shown in the dev portal. Mutable, and not used to reference the router in requests.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "description": "An optional Model Router description.", "anyOf": [{ "type": "string" }, { "type": "null" }] }, "version": { "description": "Current settings version. Increments when settings change; name and description updates do not create a new version.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "settings": { "type": "object", "properties": { "schemaVersion": { "description": "Settings JSON schema version used when this snapshot was written.", "type": "number", "const": 1 }, "models": { "description": "When mode is allow_new_except, ids are excluded; when allowlist_only, ids are the only allowed values. Each id must be a known public video or image model name (unknown ids are rejected on create/update).", "type": "object", "properties": { "mode": { "type": "string", "enum": ["allow_new_except", "allowlist_only"] }, "ids": { "type": "array", "items": { "type": "string" } } }, "required": ["mode", "ids"], "additionalProperties": false }, "maxCreditsPerGeneration": { "description": "Optional per-modality credit caps, applied per generated output. Models whose estimated per-output cost exceeds the cap are excluded.", "type": "object", "properties": { "video": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "image": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "audio": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "optimizeFor": { "description": "Soft preference among eligible models: cost, latency, or quality.", "type": "string", "enum": ["cost", "latency", "quality"] } }, "required": ["schemaVersion"], "additionalProperties": false }, "createdAt": { "description": "When the Model Router 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 Model Router 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", "slug", "name", "description", "version", "settings", "createdAt", "updatedAt" ], "additionalProperties": false } } } } } } }, "/v1/routers/{id}": { "get": { "tags": ["Model Router"], "summary": "Retrieve Model Router", "description": "Retrieve a Model Router configuration by ID.", "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 Model Router's primary key ID (UUID)." }, { "$ref": "#/components/parameters/X-Runway-Version" } ], "responses": { "200": { "description": "A named Model Router configuration.", "content": { "application/json": { "schema": { "title": "ModelRouter", "type": "object", "properties": { "id": { "description": "The Model Router's primary key ID (UUID). Use it to manage this router via the API; use the slug to reference the router in generation requests.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "slug": { "description": "Immutable slug used to reference this Model Router in generation requests (for example, production-video). Unique within the API project. The UUID id remains the canonical management identifier.", "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,63}$" }, "name": { "description": "Human-friendly Model Router display name shown in the dev portal. Mutable, and not used to reference the router in requests.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "description": "An optional Model Router description.", "anyOf": [{ "type": "string" }, { "type": "null" }] }, "version": { "description": "Current settings version. Increments when settings change; name and description updates do not create a new version.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "settings": { "type": "object", "properties": { "schemaVersion": { "description": "Settings JSON schema version used when this snapshot was written.", "type": "number", "const": 1 }, "models": { "description": "When mode is allow_new_except, ids are excluded; when allowlist_only, ids are the only allowed values. Each id must be a known public video or image model name (unknown ids are rejected on create/update).", "type": "object", "properties": { "mode": { "type": "string", "enum": ["allow_new_except", "allowlist_only"] }, "ids": { "type": "array", "items": { "type": "string" } } }, "required": ["mode", "ids"], "additionalProperties": false }, "maxCreditsPerGeneration": { "description": "Optional per-modality credit caps, applied per generated output. Models whose estimated per-output cost exceeds the cap are excluded.", "type": "object", "properties": { "video": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "image": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "audio": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "optimizeFor": { "description": "Soft preference among eligible models: cost, latency, or quality.", "type": "string", "enum": ["cost", "latency", "quality"] } }, "required": ["schemaVersion"], "additionalProperties": false }, "createdAt": { "description": "When the Model Router 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 Model Router 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", "slug", "name", "description", "version", "settings", "createdAt", "updatedAt" ], "additionalProperties": false } } } } } }, "patch": { "tags": ["Model Router"], "summary": "Update Model Router", "description": "Update a Model Router configuration. Settings changes append a new version; name and description updates do not. Settings are merged with the current snapshot - omitted fields keep their existing values.", "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 Model Router's primary key ID (UUID)." }, { "$ref": "#/components/parameters/X-Runway-Version" } ], "requestBody": { "content": { "application/json": { "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "ModelRouterUpdateRequest", "type": "object", "properties": { "name": { "description": "Display name. The slug is immutable and cannot be changed after creation.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "settings": { "description": "Nested merge: omitted settings fields keep their current values. When models is present, omitted models.mode or models.ids are preserved (sending only optimizeFor does not clear the model allowlist or credit ceiling).", "title": "ModelRouterSettings", "type": "object", "properties": { "schemaVersion": { "description": "Settings JSON schema version. Omit on write to use the current version; responses and stored snapshots always include it.", "type": "number", "const": 1 }, "models": { "description": "When mode is allow_new_except, ids are excluded; when allowlist_only, ids are the only allowed values. Each id must be a known public video or image model name (unknown ids are rejected on create/update).", "type": "object", "properties": { "mode": { "type": "string", "enum": ["allow_new_except", "allowlist_only"] }, "ids": { "type": "array", "items": { "type": "string" } } }, "required": ["mode", "ids"], "additionalProperties": false }, "maxCreditsPerGeneration": { "description": "Optional per-modality credit caps, applied per generated output. Models whose estimated per-output cost exceeds the cap are excluded.", "type": "object", "properties": { "video": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "image": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "audio": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "optimizeFor": { "description": "Soft preference among eligible models: cost, latency, or quality.", "type": "string", "enum": ["cost", "latency", "quality"] } }, "additionalProperties": false } } } } } }, "responses": { "200": { "description": "A named Model Router configuration.", "content": { "application/json": { "schema": { "title": "ModelRouter", "type": "object", "properties": { "id": { "description": "The Model Router's primary key ID (UUID). Use it to manage this router via the API; use the slug to reference the router in generation requests.", "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "slug": { "description": "Immutable slug used to reference this Model Router in generation requests (for example, production-video). Unique within the API project. The UUID id remains the canonical management identifier.", "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,63}$" }, "name": { "description": "Human-friendly Model Router display name shown in the dev portal. Mutable, and not used to reference the router in requests.", "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "description": "An optional Model Router description.", "anyOf": [{ "type": "string" }, { "type": "null" }] }, "version": { "description": "Current settings version. Increments when settings change; name and description updates do not create a new version.", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "settings": { "type": "object", "properties": { "schemaVersion": { "description": "Settings JSON schema version used when this snapshot was written.", "type": "number", "const": 1 }, "models": { "description": "When mode is allow_new_except, ids are excluded; when allowlist_only, ids are the only allowed values. Each id must be a known public video or image model name (unknown ids are rejected on create/update).", "type": "object", "properties": { "mode": { "type": "string", "enum": ["allow_new_except", "allowlist_only"] }, "ids": { "type": "array", "items": { "type": "string" } } }, "required": ["mode", "ids"], "additionalProperties": false }, "maxCreditsPerGeneration": { "description": "Optional per-modality credit caps, applied per generated output. Models whose estimated per-output cost exceeds the cap are excluded.", "type": "object", "properties": { "video": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "image": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "audio": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false }, "optimizeFor": { "description": "Soft preference among eligible models: cost, latency, or quality.", "type": "string", "enum": ["cost", "latency", "quality"] } }, "required": ["schemaVersion"], "additionalProperties": false }, "createdAt": { "description": "When the Model Router 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 Model Router 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", "slug", "name", "description", "version", "settings", "createdAt", "updatedAt" ], "additionalProperties": false } } } } } }, "delete": { "tags": ["Model Router"], "summary": "Delete Model Router", "description": "Delete a Model Router configuration. Deleted Model Routers cannot be used for generation.", "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 Model Router's primary key ID (UUID)." }, { "$ref": "#/components/parameters/X-Runway-Version" } ], "responses": { "204": { "description": "Success" } } } }, "/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": 1024 }, { "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, Runway upload URI, or base64 data URI (e.g. `data:audio/mp3;base64,...`, up to 16MB) containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information.", "example": "https://example.com/audio.mp3", "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": 1024 }, { "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, Runway upload URI, or base64 data URI (e.g. `data:image/png;base64,...`, up to 5MB) containing an encoded image. See [our docs](/assets/inputs#images) on image inputs for more information.", "example": "https://example.com/image.jpg", "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, Runway upload URI, or base64 data URI (e.g. `data:video/mp4;base64,...`, up to 16MB) containing an encoded video. See [our docs](/assets/inputs#videos) on video inputs for more information.", "example": "https://example.com/video.mp4", "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, Runway upload URI, or base64 data URI (e.g. `data:audio/mp3;base64,...`, up to 16MB) containing an encoded audio. See [our docs](/assets/inputs#audio) on audio inputs for more information.", "example": "https://example.com/audio.mp3", "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" }] }