> ## Documentation Index > Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt > Use this file to discover all available pages before exploring further. # Generate Runway speech from text > Convert text into speech with a preset voice or reference audio using the Runway API. Use `POST /runwayml/v1/text_to_speech` to create a speech task from text. Send your CometAPI API key with Bearer authentication and a JSON request body. ## Choose a model and voice Every request requires `model`, `promptText`, and `voice`. | Model ID | Text limit | Voice configuration | | ------------------------ | ---------------------- | ------------------------------------------------------ | | `eleven_multilingual_v2` | 1000 UTF-16 code units | `type: runway-preset` and a `presetId`, such as `Maya` | | `eleven_v3` | 5000 characters | `type: runway-preset` and a `presetId`, such as `Maya` | | `seed_audio` | 2048 characters | `type: reference-audio` and an `audioUri` | For preset voices, select a `presetId` from the request schema. For `seed_audio`, replace the example `audioUri` with an accessible HTTPS URL of your voice reference. Do not omit `voice` or send `null` for this field. ## Adjust speech expression With `eleven_v3`, `promptText` can include expressive tags such as `[whispers]` or `[laughs]`. The model also accepts these controls: | Field | Values | Meaning | | ------------------------ | ---------------------------- | ----------------------------------------------------------------------- | | `stability` | Number from 0 to 1 | Lower nonzero values allow more expression; higher values are steadier. | | `similarityBoost` | Number from 0 to 1 | Higher values follow the selected voice more closely. | | `style` | Number from 0 to 1 | Higher values emphasize the voice style. | | `speed` | Number from 0.7 to 1.2 | `1` uses normal speed. | | `useSpeakerBoost` | `true` | Request greater similarity to the selected voice. | | `languageCode` | ISO 639-1 language code | Guide pronunciation and text normalization. | | `applyTextNormalization` | `auto`, `on`, `off` | Control how text such as numbers becomes spoken words. | | `seed` | Integer from 1 to 4294967295 | Set the sampling seed. | For `stability`, `similarityBoost`, and `style`, a value of `0` uses the model default, as does omitting the field. `useSpeakerBoost: false` also uses the model default. To set a sampling seed, use a positive integer; `seed: 0` chooses a seed automatically. ## Adjust speech speed and format With `seed_audio`, use `speechRate` and `loudnessRate` from -50 to 100, or `pitchRate` from -12 to 12 semitones. These controls accept integers; omission or `0` keeps the normal value. Set `sampleRate` to `8000`, `16000`, `24000`, `32000`, `44100`, or `48000` Hz. Set `outputFormat` to `wav`, `mp3`, or `ogg_opus`. Do not include `duration`, `referenceAudios`, or Eleven v3 controls with `seed_audio` on this endpoint. ## Retrieve the result Save the returned `id`, then use [Get a Runway task](./runway-to-get-task-details) to retrieve task status. When `status` is `SUCCEEDED`, read the audio URLs in `output`. If the task fails, inspect `failure` and `failureCode`. ## OpenAPI ````yaml api/openapi/video/runway/official-format/post-generate-speech-from-text.openapi.json POST /runwayml/v1/text_to_speech openapi: 3.1.0 info: title: Generate Runway speech from text API version: 1.0.0 description: >- Convert text into speech with a preset voice or reference audio using the Runway API. servers: - url: https://api.cometapi.com security: - bearerAuth: [] paths: /runwayml/v1/text_to_speech: post: summary: Generate Runway speech from text description: >- Convert text into speech with a preset voice or reference audio using the Runway API. Save the returned id and retrieve the task to obtain its output. operationId: runway_text_to_speech requestBody: required: true content: application/json: schema: oneOf: - title: eleven_multilingual_v2 type: object properties: model: type: string const: eleven_multilingual_v2 enum: - eleven_multilingual_v2 description: Model ID for this request. promptText: description: Text to speak, from 1 to 1000 UTF-16 code units. 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 enum: - runway-preset description: Input type. Use 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 additionalProperties: false discriminator: propertyName: type required: - promptText - voice - model additionalProperties: false description: Request settings for eleven_multilingual_v2. default: model: eleven_multilingual_v2 promptText: Welcome to our audio guide. Let us begin the tour. voice: type: runway-preset presetId: Maya - title: eleven_v3 type: object properties: model: type: string const: eleven_v3 enum: - eleven_v3 description: Model ID for this request. promptText: description: >- The text to convert to speech. You can include expressive audio tags like [laughs] or [whispers] in the script. type: string minLength: 1 maxLength: 5000 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 enum: - runway-preset description: Input type. Use 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 additionalProperties: false discriminator: propertyName: type stability: description: >- Voice stability from 0 to 1. Lower nonzero values allow more expression; higher values are steadier. Omit or use 0 for the model default. type: number minimum: 0 maximum: 1 similarityBoost: description: >- Voice similarity from 0 to 1. Higher values follow the selected voice more closely. Omit or use 0 for the model default. type: number minimum: 0 maximum: 1 style: description: >- Style intensity from 0 to 1. Higher values emphasize the selected voice style. Omit or use 0 for the model default. type: number minimum: 0 maximum: 1 speed: description: >- Speech speed multiplier from 0.7 to 1.2. A value of 1 uses normal speed. type: number minimum: 0.7 maximum: 1.2 useSpeakerBoost: description: >- Set true to request greater similarity to the selected voice. Omit or use false for the model default. type: boolean languageCode: description: >- ISO 639-1 language code to enforce pronunciation and normalization. type: string minLength: 2 maxLength: 5 applyTextNormalization: description: >- How to normalize spoken text, such as reading numbers as words: auto, on, or off. type: string enum: - auto - 'on' - 'off' seed: description: >- Sampling seed from 1 to 4294967295. Omit or use 0 for an automatically chosen seed. type: integer minimum: 0 maximum: 4294967295 required: - promptText - voice - model additionalProperties: false description: Request settings for eleven_v3. default: model: eleven_v3 promptText: '[whispers] The adventure begins at sunrise.' voice: type: runway-preset presetId: Maya stability: 0.5 speed: 1 - title: seed_audio type: object properties: model: type: string const: seed_audio enum: - seed_audio description: Model ID for this request. promptText: description: Text to speak. type: string minLength: 1 maxLength: 2048 voice: description: >- Required reference audio that supplies the speaking voice. title: SeedReferenceVoice type: object properties: type: type: string const: reference-audio enum: - reference-audio description: Input type. Use reference-audio. audioUri: description: >- Audio input as an accessible HTTPS URL or base64 data URI. anyOf: - description: Accessible HTTPS URL of the audio file. type: string minLength: 13 maxLength: 2048 pattern: ^https:\/\/.* - description: Base64 audio data URI, up to 5 MB. type: string minLength: 13 maxLength: 5242880 pattern: ^data:audio\/.* required: - type - audioUri additionalProperties: false speechRate: description: >- Relative speech speed: negative values slow speech, positive values speed it up. Omit or use 0 for normal speed. type: integer minimum: -50 maximum: 100 loudnessRate: description: >- Relative loudness: negative values reduce volume, positive values increase it. Omit or use 0 for normal loudness. type: integer minimum: -50 maximum: 100 pitchRate: description: >- Pitch shift in semitones: negative values lower pitch, positive values raise it. Omit or use 0 for unchanged pitch. type: integer minimum: -12 maximum: 12 sampleRate: description: Output sample rate in Hz. type: integer enum: - 8000 - 16000 - 24000 - 32000 - 44100 - 48000 outputFormat: description: Output audio container/format. type: string enum: - wav - mp3 - ogg_opus required: - promptText - model - voice additionalProperties: false description: Request settings for seed_audio. default: model: seed_audio promptText: Welcome to our audio guide. Let us begin the tour. voice: type: reference-audio audioUri: https://your-audio-host/voice-reference.mp3 sampleRate: 44100 outputFormat: mp3 discriminator: propertyName: model default: model: eleven_multilingual_v2 promptText: Welcome to our audio guide. Let us begin the tour. voice: type: runway-preset presetId: Maya examples: eleven_multilingual_v2: summary: eleven_multilingual_v2 value: model: eleven_multilingual_v2 promptText: Welcome to our audio guide. Let us begin the tour. voice: type: runway-preset presetId: Maya eleven_v3: summary: eleven_v3 value: model: eleven_v3 promptText: '[whispers] The adventure begins at sunrise.' voice: type: runway-preset presetId: Maya stability: 0.5 speed: 1 seed_audio: summary: seed_audio value: model: seed_audio promptText: Welcome to our audio guide. Let us begin the tour. voice: type: reference-audio audioUri: https://your-audio-host/voice-reference.mp3 sampleRate: 44100 outputFormat: mp3 responses: '200': description: Task created. Save the returned id to retrieve task status. content: application/json: schema: type: object properties: id: type: string description: Task ID for GET /runwayml/v1/tasks/{id}. status: type: string description: Task state, when returned. createdAt: type: string description: Task submission timestamp, when returned. format: date-time output: type: array description: Result URLs, when returned. items: type: string format: uri failure: type: string description: Failure explanation, when returned. failureCode: type: string description: Machine-readable failure code, when returned. estimatedCost: type: object description: Task estimate metadata, when returned. properties: credits: type: integer description: Credit value reported with the task. required: - credits additionalProperties: false cost: type: object description: Task cost metadata, when returned. properties: credits: type: integer description: Credit value reported with the task. required: - credits additionalProperties: false required: - id additionalProperties: false example: id: 123e4567-e89b-42d3-a456-426614174000 '400': description: Invalid request or unavailable task ID. content: application/json: schema: oneOf: - type: object description: Task request error. properties: code: type: - string - integer description: Machine-readable task error code. message: type: string description: Error explanation. data: description: Additional error details, when returned. required: - code - message additionalProperties: true - type: object description: Request authentication or validation error. properties: error: type: object description: Error details. properties: message: type: string description: Error explanation. type: type: string description: Error category. code: type: - string - integer - 'null' description: Error code, when returned. required: - message additionalProperties: true required: - error additionalProperties: true '401': description: Authentication failed. content: application/json: schema: type: object description: Request authentication or validation error. properties: error: type: object description: Error details. properties: message: type: string description: Error explanation. type: type: string description: Error category. code: type: - string - integer - 'null' description: Error code, when returned. required: - message additionalProperties: true required: - error additionalProperties: true x-codeSamples: - lang: Shell label: eleven_multilingual_v2 source: | curl https://api.cometapi.com/runwayml/v1/text_to_speech \ --request POST \ --header "Authorization: Bearer $COMETAPI_KEY" \ --header "Content-Type: application/json" \ --data '{ "model": "eleven_multilingual_v2", "promptText": "Welcome to our audio guide. Let us begin the tour.", "voice": { "type": "runway-preset", "presetId": "Maya" } }' - lang: Python label: eleven_multilingual_v2 source: | import os import requests payload = { 'model': 'eleven_multilingual_v2', 'promptText': 'Welcome to our audio guide. Let us begin the tour.', 'voice': {'type': 'runway-preset', 'presetId': 'Maya'}} response = requests.post( "https://api.cometapi.com/runwayml/v1/text_to_speech", headers={"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]}, json=payload, ) response.raise_for_status() print(response.json()["id"]) - lang: JavaScript label: eleven_multilingual_v2 source: | const payload = { "model": "eleven_multilingual_v2", "promptText": "Welcome to our audio guide. Let us begin the tour.", "voice": { "type": "runway-preset", "presetId": "Maya" } }; const response = await fetch( "https://api.cometapi.com/runwayml/v1/text_to_speech", { method: "POST", headers: { Authorization: `Bearer ${process.env.COMETAPI_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify(payload), }, ); if (!response.ok) throw new Error(await response.text()); const task = await response.json(); console.log(task.id); - lang: Shell label: eleven_v3 source: | curl https://api.cometapi.com/runwayml/v1/text_to_speech \ --request POST \ --header "Authorization: Bearer $COMETAPI_KEY" \ --header "Content-Type: application/json" \ --data '{ "model": "eleven_v3", "promptText": "[whispers] The adventure begins at sunrise.", "voice": { "type": "runway-preset", "presetId": "Maya" }, "stability": 0.5, "speed": 1 }' - lang: Python label: eleven_v3 source: | import os import requests payload = { 'model': 'eleven_v3', 'promptText': '[whispers] The adventure begins at sunrise.', 'voice': {'type': 'runway-preset', 'presetId': 'Maya'}, 'stability': 0.5, 'speed': 1} response = requests.post( "https://api.cometapi.com/runwayml/v1/text_to_speech", headers={"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]}, json=payload, ) response.raise_for_status() print(response.json()["id"]) - lang: JavaScript label: eleven_v3 source: | const payload = { "model": "eleven_v3", "promptText": "[whispers] The adventure begins at sunrise.", "voice": { "type": "runway-preset", "presetId": "Maya" }, "stability": 0.5, "speed": 1 }; const response = await fetch( "https://api.cometapi.com/runwayml/v1/text_to_speech", { method: "POST", headers: { Authorization: `Bearer ${process.env.COMETAPI_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify(payload), }, ); if (!response.ok) throw new Error(await response.text()); const task = await response.json(); console.log(task.id); - lang: Shell label: seed_audio source: | curl https://api.cometapi.com/runwayml/v1/text_to_speech \ --request POST \ --header "Authorization: Bearer $COMETAPI_KEY" \ --header "Content-Type: application/json" \ --data '{ "model": "seed_audio", "promptText": "Welcome to our audio guide. Let us begin the tour.", "voice": { "type": "reference-audio", "audioUri": "https://your-audio-host/voice-reference.mp3" }, "sampleRate": 44100, "outputFormat": "mp3" }' - lang: Python label: seed_audio source: | import os import requests payload = { 'model': 'seed_audio', 'promptText': 'Welcome to our audio guide. Let us begin the tour.', 'voice': { 'type': 'reference-audio', 'audioUri': 'https://your-audio-host/voice-reference.mp3'}, 'sampleRate': 44100, 'outputFormat': 'mp3'} response = requests.post( "https://api.cometapi.com/runwayml/v1/text_to_speech", headers={"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]}, json=payload, ) response.raise_for_status() print(response.json()["id"]) - lang: JavaScript label: seed_audio source: | const payload = { "model": "seed_audio", "promptText": "Welcome to our audio guide. Let us begin the tour.", "voice": { "type": "reference-audio", "audioUri": "https://your-audio-host/voice-reference.mp3" }, "sampleRate": 44100, "outputFormat": "mp3" }; const response = await fetch( "https://api.cometapi.com/runwayml/v1/text_to_speech", { method: "POST", headers: { Authorization: `Bearer ${process.env.COMETAPI_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify(payload), }, ); if (!response.ok) throw new Error(await response.text()); const task = await response.json(); console.log(task.id); components: securitySchemes: bearerAuth: type: http scheme: bearer description: Use your CometAPI API key. ````