> ## 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 sound effects > Generate sound effects or audio scenes from a text prompt with the Runway API. Use `POST /runwayml/v1/sound_effect` to create an audio task from a text prompt. Send your CometAPI API key with Bearer authentication and a JSON request body. ## Choose a model | Model ID | Required inputs | Optional controls | | ------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------- | | `eleven_text_to_sound_v2` | `promptText` with 1–3000 characters | `duration` in whole seconds from 1 to 30; `loop` | | `seed_audio` | `promptText` with 1–2048 characters | Up to three `referenceAudios`; speech, loudness, and pitch controls; output format | For `eleven_text_to_sound_v2`, omit `duration` to choose the length from the prompt. Set `loop: true` to request a repeating sound effect. For `seed_audio`, refer to `referenceAudios` in the prompt as `@Audio1`, `@Audio2`, and `@Audio3`, in array order. Omit `referenceAudios` when you do not need a reference. Replace each example audio URL with an accessible HTTPS URL of your audio file. Do not include `duration`, `loop`, or `voice` with this model on this endpoint. ## Configure audio controls | Field | Values | Meaning | | -------------- | --------------------------------------------------- | ----------------------------------------------- | | `speechRate` | Integer from -50 to 100 | Negative slows speech; positive speeds it up. | | `loudnessRate` | Integer from -50 to 100 | Negative reduces volume; positive increases it. | | `pitchRate` | Integer from -12 to 12 | Pitch shift in semitones. | | `sampleRate` | `8000`, `16000`, `24000`, `32000`, `44100`, `48000` | Audio sample rate in Hz. | | `outputFormat` | `wav`, `mp3`, `ogg_opus` | Output audio format. | For the three rate controls, omit the field or use `0` to keep its normal value. ## 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-sound-effects.openapi.json POST /runwayml/v1/sound_effect openapi: 3.1.0 info: title: Generate Runway sound effects API version: 1.0.0 description: >- Generate sound effects or audio scenes from a text prompt with the Runway API. servers: - url: https://api.cometapi.com security: - bearerAuth: [] paths: /runwayml/v1/sound_effect: post: summary: Generate Runway sound effects description: >- Generate sound effects or audio scenes from a text prompt with the Runway API. Save the returned id and retrieve the task to obtain its output. operationId: runway_sound_effect requestBody: required: true content: application/json: schema: oneOf: - title: eleven_text_to_sound_v2 type: object properties: model: type: string const: eleven_text_to_sound_v2 enum: - eleven_text_to_sound_v2 description: Model ID for this request. promptText: description: A text description of the sound effect to generate. type: string minLength: 1 maxLength: 3000 duration: description: >- Sound effect duration in whole seconds, from 1 to 30. Omit this field to choose duration from the prompt. type: integer minimum: 1 maximum: 30 loop: description: >- Set true to request a sound effect that loops seamlessly. Defaults to false. default: false type: boolean required: - promptText - model additionalProperties: false description: Request settings for eleven_text_to_sound_v2. default: model: eleven_text_to_sound_v2 promptText: Gentle rain falling on a wooden roof with distant thunder. duration: 5 loop: true - title: seed_audio type: object properties: model: type: string const: seed_audio enum: - seed_audio description: Model ID for this request. promptText: description: >- Audio scene description, including dialogue, music, or sound effects. type: string minLength: 1 maxLength: 2048 referenceAudios: description: >- Up to three audio references. Refer to them in promptText as @Audio1, @Audio2, and @Audio3 in array order. maxItems: 3 type: array items: 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\/.* 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 additionalProperties: false description: Request settings for seed_audio. default: model: seed_audio promptText: A quiet forest with birdsong in the style of @Audio1. referenceAudios: - https://your-audio-host/forest-reference.mp3 sampleRate: 44100 outputFormat: mp3 discriminator: propertyName: model default: model: eleven_text_to_sound_v2 promptText: Gentle rain falling on a wooden roof with distant thunder. duration: 5 loop: true examples: eleven_text_to_sound_v2: summary: eleven_text_to_sound_v2 value: model: eleven_text_to_sound_v2 promptText: Gentle rain falling on a wooden roof with distant thunder. duration: 5 loop: true seed_audio: summary: seed_audio value: model: seed_audio promptText: A quiet forest with birdsong in the style of @Audio1. referenceAudios: - https://your-audio-host/forest-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_text_to_sound_v2 source: | curl https://api.cometapi.com/runwayml/v1/sound_effect \ --request POST \ --header "Authorization: Bearer $COMETAPI_KEY" \ --header "Content-Type: application/json" \ --data '{ "model": "eleven_text_to_sound_v2", "promptText": "Gentle rain falling on a wooden roof with distant thunder.", "duration": 5, "loop": true }' - lang: Python label: eleven_text_to_sound_v2 source: | import os import requests payload = { 'model': 'eleven_text_to_sound_v2', 'promptText': 'Gentle rain falling on a wooden roof with distant thunder.', 'duration': 5, 'loop': True} response = requests.post( "https://api.cometapi.com/runwayml/v1/sound_effect", headers={"Authorization": "Bearer " + os.environ["COMETAPI_KEY"]}, json=payload, ) response.raise_for_status() print(response.json()["id"]) - lang: JavaScript label: eleven_text_to_sound_v2 source: | const payload = { "model": "eleven_text_to_sound_v2", "promptText": "Gentle rain falling on a wooden roof with distant thunder.", "duration": 5, "loop": true }; const response = await fetch( "https://api.cometapi.com/runwayml/v1/sound_effect", { 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/sound_effect \ --request POST \ --header "Authorization: Bearer $COMETAPI_KEY" \ --header "Content-Type: application/json" \ --data '{ "model": "seed_audio", "promptText": "A quiet forest with birdsong in the style of @Audio1.", "referenceAudios": [ "https://your-audio-host/forest-reference.mp3" ], "sampleRate": 44100, "outputFormat": "mp3" }' - lang: Python label: seed_audio source: | import os import requests payload = { 'model': 'seed_audio', 'promptText': 'A quiet forest with birdsong in the style of @Audio1.', 'referenceAudios': ['https://your-audio-host/forest-reference.mp3'], 'sampleRate': 44100, 'outputFormat': 'mp3'} response = requests.post( "https://api.cometapi.com/runwayml/v1/sound_effect", 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": "A quiet forest with birdsong in the style of @Audio1.", "referenceAudios": [ "https://your-audio-host/forest-reference.mp3" ], "sampleRate": 44100, "outputFormat": "mp3" }; const response = await fetch( "https://api.cometapi.com/runwayml/v1/sound_effect", { 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. ````