> ## 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. # 텍스트로 Runway 음성 생성 > Runway API를 사용하여 프리셋 음성 또는 참조 오디오로 텍스트를 음성으로 변환합니다. `POST /runwayml/v1/text_to_speech`을 사용하여 텍스트에서 음성 작업을 생성합니다. Bearer 인증과 JSON 요청 본문으로 CometAPI API 키를 전송합니다. ## 모델 및 음성 선택 모든 요청에는 `model` 및 `promptText`가 필요합니다. `voice` 필드는 `eleven_multilingual_v2`, `eleven_v3`, `eleven_v4`에는 필수이며 `seed_audio`에는 선택 사항입니다. | 모델 ID | 텍스트 제한 | 음성 구성 | | - | - | - | | `eleven_multilingual_v2` | UTF-16 코드 단위 1000개 | `type: runway-preset` 및 `presetId`(예: `Maya` | | `eleven_v3` | 문자 5000개 | `type: runway-preset` 및 `presetId`(예: `Maya` | | `eleven_v4` | 비어 있지 않은 텍스트 | `type: runway-preset` 및 `presetId`(예: `Maya` | | `seed_audio` | 문자 2048개 | 기본 음성을 사용하려면 `voice`을 생략하거나 `type: reference-audio` 및 `audioUri` | 프리셋 음성의 경우 요청 스키마에서 `presetId`을 선택합니다. `seed_audio`의 경우 예시 `audioUri`을 음성 참조에 접근할 수 있는 HTTPS URL로 바꿉니다. ## 음성 표현 조정 `eleven_v3`에서 `promptText`는 `[whispers]` 같은 표현 태그를 포함할 수 있으며 `[laughs]`도 사용할 수 있습니다. 모델은 다음 제어도 지원합니다: | 필드 | 값 | 의미 | | - | - | - | | `stability` | 0\~1의 숫자 | 0이 아닌 낮은 값은 더 많은 표현을 허용하고, 높은 값은 더 안정적입니다. | | `similarityBoost` | 0\~1의 숫자 | 값이 높을수록 선택한 음성을 더 충실하게 따릅니다. | | `style` | 0\~1의 숫자 | 값이 높을수록 음성 스타일을 더 강조합니다. | | `speed` | 0.7\~1.2의 숫자 | `1` 일반 속도를 사용합니다. | | `useSpeakerBoost` | `true` | 선택한 음성과의 유사도를 더 높게 요청합니다. | | `languageCode` | ISO 639-1 언어 코드 | 발음과 텍스트 정규화를 안내합니다. | | `applyTextNormalization` | `auto`, `on`, `off` | 숫자와 같은 텍스트가 음성 단어로 변환되는 방식을 제어합니다. | | `seed` | 1\~4294967295의 정수 | 샘플링 시드를 설정합니다. | `stability`, `similarityBoost`, `style`의 경우 `0` 값은 모델 기본값을 사용하며, 필드를 생략해도 마찬가지입니다. `useSpeakerBoost: false`도 모델 기본값을 사용합니다. 샘플링 시드를 설정하려면 양의 정수를 사용하세요. `seed: 0`은 시드를 자동으로 선택합니다. ## Eleven v4 음성 조정 `eleven_v4`에서 `promptText`가 지원하는 표현 태그에는 `[laughs]`, `[whispers]`, 그리고 `[pause]`가 포함됩니다. 다음 선택적 제어를 사용하세요: | 필드 | 값 | 의미 | | - | - | - | | `stability` | 0\~1의 숫자 | 낮은 값은 더 넓은 감정 범위를 허용하고, 높은 값은 더 안정적입니다. | | `similarityBoost` | 0\~1의 숫자 | 출력이 선택한 음성을 얼마나 충실하게 따를지 설정합니다. | | `style` | 0\~1의 숫자 | 값이 높을수록 화자 스타일을 강화합니다. | | `speed` | 0.7\~1.2의 숫자 | 1 미만 값은 음성을 느리게 하고, 1 초과 값은 빠르게 합니다. | | `useSpeakerBoost` | `true` 또는 `false` | 선택한 음성과의 유사도를 높입니다. | | `languageCode` | 2\~16자 | 예를 들어 `en` 또는 `pt-BR`처럼 발음을 강제합니다. | | `previousText` | 문자열 | 이 요청 전에 생성된 텍스트에서 음성을 이어갑니다. | | `nextText` | 문자열 | 이 요청 후에 생성될 텍스트로 음성을 연결합니다. | | `seed` | 0\~4294967295의 정수 | 더 일관된 출력을 위해 시드를 선택합니다. | `eleven_v4`는 `applyTextNormalization`을 사용하지 않습니다. `previousText` 및 `nextText` 필드는 인접 세그먼트를 생성하면서 모델이 전환을 일관되게 유지하게 하려는 경우 유용합니다. ## 음성 속도 및 형식 조정 `seed_audio`에서는 `speechRate` 및 `loudnessRate`에 -50~~100 범위의 값을 사용하거나 `pitchRate` 에는 -12~~12세미톤 값을 사용합니다. 이 컨트롤은 정수만 허용하며, 이를 생략 하거나 `0`로 설정하면 기본값이 유지됩니다. `sampleRate` 값은 `8000`, `16000`, `24000`, `32000`, `44100` 또는 `48000` Hz로 설정합니다. `outputFormat`에는 `wav`, `mp3` 또는 `ogg_opus` 중 하나를 설정합니다. 이 엔드포인트에서는 `duration`, `referenceAudios`또는 `seed_audio`를 사용한 Eleven v3 컨트롤을 포함하지 마세요. ## 결과 가져오기 반환된 `id`를 저장한 다음 [Runway 작업 가져오기](https://apidoc.cometapi.com/ko/api/video/runway/official-format/runway-to-get-task-details.md) 을 사용하여 작업 상태를 가져옵니다. `status` 값이 `SUCCEEDED`이면 오디오 URL은 다음 위치에서 확인: `output`. 작업이 실패하면 `failure` 및 `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: eleven_v4 type: object properties: model: type: string const: eleven_v4 enum: - eleven_v4 description: Model ID for this request. promptText: description: >- The text to convert to speech. You can include expressive audio tags like [laughs], [whispers], or [pause] in the script. type: string minLength: 1 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 values allow broader emotional range; higher values are steadier. type: number minimum: 0 maximum: 1 similarityBoost: description: >- How closely the output tracks the selected voice, from 0 to 1. type: number minimum: 0 maximum: 1 style: description: >- Style exaggeration from 0 to 1. Higher values amplify the speaker style. type: number minimum: 0 maximum: 1 speed: description: >- Speech speed multiplier from 0.7 to 1.2. Values below 1 slow the speech down, and values above 1 speed it up. type: number minimum: 0.7 maximum: 1.2 useSpeakerBoost: description: >- Set true to boost similarity to the selected voice at a small latency cost. type: boolean languageCode: description: >- Language code from 2 to 16 characters to enforce pronunciation, such as en or pt-BR. type: string minLength: 2 maxLength: 16 seed: description: >- Optional seed from 0 to 4294967295 for more consistent output. type: integer minimum: 0 maximum: 4294967295 previousText: description: >- Text that comes before this request, so speech can continue from an earlier generation. type: string nextText: description: >- Text that comes after this request, so speech can lead into a later generation. type: string required: - promptText - voice - model additionalProperties: false description: Request settings for eleven_v4. default: model: eleven_v4 promptText: '[pause] The museum opens at nine.' voice: type: runway-preset presetId: Maya stability: 0.5 speed: 1 languageCode: en previousText: The guide takes a breath. nextText: Visitors enter through the west door. - 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: >- Optional reference audio that supplies the speaking voice. Omit this field to use a default 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 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 eleven_v4: summary: eleven_v4 value: model: eleven_v4 promptText: '[pause] The museum opens at nine.' voice: type: runway-preset presetId: Maya stability: 0.5 speed: 1 languageCode: en previousText: The guide takes a breath. nextText: Visitors enter through the west door. 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: eleven_v4 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_v4", "promptText": "[pause] The museum opens at nine.", "voice": { "type": "runway-preset", "presetId": "Maya" }, "stability": 0.5, "speed": 1, "languageCode": "en", "previousText": "The guide takes a breath.", "nextText": "Visitors enter through the west door." }' - lang: Python label: eleven_v4 source: | import os import requests payload = { "model": "eleven_v4", "promptText": "[pause] The museum opens at nine.", "voice": {"type": "runway-preset", "presetId": "Maya"}, "stability": 0.5, "speed": 1, "languageCode": "en", "previousText": "The guide takes a breath.", "nextText": "Visitors enter through the west door.", } 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_v4 source: | const payload = { "model": "eleven_v4", "promptText": "[pause] The museum opens at nine.", "voice": { "type": "runway-preset", "presetId": "Maya" }, "stability": 0.5, "speed": 1, "languageCode": "en", "previousText": "The guide takes a breath.", "nextText": "Visitors enter through the west door." }; 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.