> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# 创建语音引擎

POST https://api.elevenlabs.io/v1/speech-engine
Content-Type: application/json

创建新的 Speech Engine 资源

Reference: https://elevenlabs.io/docs/api-reference/speech-engine/create

## Servers

- `https://api.elevenlabs.io` (Production, default)
- `https://api.us.elevenlabs.io` (Production US)
- `https://api.eu.residency.elevenlabs.io` (Production EU)
- `https://api.in.residency.elevenlabs.io` (Production India)
- `https://api.sg.residency.elevenlabs.io` (Production Singapore)

## Request

### Body (application/json)

This endpoint expects a CreateSpeechEngineRequest.

- `speech_engine` (SpeechEngineConfig, required) — 语音引擎 WebSocket 配置
- `name` (string, optional, default: Speech Engine) — 语音引擎名称
- `asr` (ASRConversationalConfig, optional) — ASR configuration
- `tts` (TTSConversationalConfig-Input, optional) — TTS 配置。
- `turn` (BaseTurnConfig, optional) — 轮次检测配置。
- `vad` (VADConfig, optional) — Configuration for voice activity detection
- `conversation` (ConversationConfig-Input, optional) — 对话配置（客户端事件等）
- `privacy` (PrivacyConfig-Input, optional) — 隐私设置（录音、保留、零保留模式）
- `call_limits` (AgentCallLimits, optional) — Concurrency and daily conversation limits for this speech engine
- `language` (string, optional, default: en) — 语音引擎语言
- `cascade_timeout_seconds` (double, optional, default: 4) — 放弃当前尝试并重试前，等待上游语音引擎端点响应的秒数。必须介于 2 至 15 秒。
- `tags` (list of string, optional) — 分类标签
- `overrides` (SpeechEngineConversationInitiationClientDataConfig, optional) — 客户端可在发起对话时设置的覆盖选项

## Response

### 201

成功响应

- `speech_engine_id` (string, required) — 语音引擎资源 ID
- `name` (string, required) — 语音引擎的人类可读名称
- `speech_engine` (SpeechEngineConfig, required) — 上游转写服务器的 WebSocket 连接设置
- `asr` (ASRConversationalConfig, required) — Automatic speech recognition configuration
- `tts` (TTSConversationalConfig-Output, required) — 文本转语音输出配置
- `turn` (BaseTurnConfig, required) — 轮次检测配置。
- `vad` (VADConfig, required) — Configuration for voice activity detection
- `conversation` (ConversationConfig-Output, required) — 对话级设置，包括客户端事件和时长限制
- `privacy` (PrivacyConfig-Output, required) — 控制录音、保留和 PII 处理的隐私设置
- `call_limits` (AgentCallLimits, required) — Concurrency and daily conversation limits for this speech engine
- `language` (string, required) — 语音引擎使用的 ISO 语言代码（例如 'en'）
- `cascade_timeout_seconds` (double, required) — 放弃当前尝试并重试前，等待上游语音引擎端点响应的秒数。必须介于 2 至 15 秒。
- `tags` (list of string, required) — 用于分类和筛选的任意标签
- `overrides` (SpeechEngineConversationInitiationClientDataConfig, required) — 客户端可在发起对话时设置的覆盖选项
- `metadata` (AgentMetadataDBModel, required) — 包含来源信息的创建和更新时间戳
- `access_info` (ResourceAccessInfo, optional, nullable) — 用户对语音引擎的访问信息

## Errors

### 422 Unprocessable Entity Error

验证错误。

- `detail` (list of ValidationError, optional)

## Types

### SpeechEngineConfig

- `ws_url` (string, required) — 转录服务器的 WebSocket URL。
- `request_headers` (map from string to SpeechEngineConfigRequestHeaders, optional) — WebSocket 连接请求中应包含的请求头

### ASRConversationalConfig

- `quality` (enum, optional, default: high) — 转录质量
  - Allowed values: `high`
- `provider` (enum, optional, default: scribe_realtime) — 转录服务提供商
  - Allowed values: `elevenlabs`, `scribe_realtime`, `scribe_v2_turbo`
- `user_input_audio_format` (enum, optional, default: pcm_16000) — 要转录音频的格式
  - Allowed values: `pcm_8000`, `pcm_16000`, `pcm_22050`, `pcm_24000`, `pcm_44100`, `pcm_48000`, `ulaw_8000`
- `keywords` (list of string, optional) — 用于提高预测概率的关键词

### TTSConversationalConfig-Input

- `model_id` (enum, optional, default: eleven_v4_turbo) — 用于 TTS 的模型
  - Allowed values: `eleven_turbo_v2`, `eleven_turbo_v2_5`, `eleven_flash_v2`, `eleven_flash_v2_5`, `eleven_multilingual_v2`, `eleven_v3_conversational`, `eleven_v4`, `eleven_v4_turbo`
- `voice_id` (string, optional, default: cjVigY5qzO86Huf0OWal) — 用于 TTS 的音色 ID。
- `supported_voices` (list of SupportedVoice, optional) — 智能体额外支持的音色
- `expressive_mode` (boolean, optional, default: true) — 启用后，应用富表现力音频标签提示词。非 v3 模型会自动禁用。
- `suggested_audio_tags` (list of SuggestedAudioTag, optional) — 用于增强富有表现力语音的建议音频标签（适用于 eleven_v3 和 eleven_v3_conversational 模型）。智能体仍可使用此处未列出的其他标签。
- `agent_output_audio_format` (enum, optional, default: pcm_16000) — TTS 使用的音频格式
  - Allowed values: `pcm_8000`, `pcm_16000`, `pcm_22050`, `pcm_24000`, `pcm_44100`, `pcm_48000`, `ulaw_8000`
- `stability` (double, optional, default: 0.5) — 生成语音的稳定性
- `speed` (double, optional, default: 1) — 生成语音的速度
- `similarity_boost` (double, optional, default: 0.8) — 生成语音的相似度增强
- `text_normalisation_type` (enum, optional, default: system_prompt) — 将文本转为语音前把数字转换为文字的方法。设为 SYSTEM_PROMPT 时，系统提示词会更新为包含规范化说明。设为 ELEVENLABS 时，文本会在生成后规范化，这会略微增加延迟。
  - Allowed values: `system_prompt`, `elevenlabs`
- `pronunciation_dictionary_locators` (list of PydanticPronunciationDictionaryVersionLocator, optional) — 发音词典定位器
- `enable_phoneme_tags` (boolean, optional, default: true) — 选择为 V3 模型启用 SSML 音素标签处理。启用后，音素标签（内联及来自发音词典的标签）会先解析为内联 IPA，再发送给模型。
- `audio_effects` (EffectsSpec-Input, optional, nullable) — 可选的 TTS 效果规格：滤镜预设、距离（近讲 EQ）和环境（卷积混响）。
- `optimize_streaming_latency` (enum, optional, deprecated) — 已弃用：此字段无效，将被忽略。
  - Allowed values: `0`, `1`, `2`, `3`, `4`

### BaseTurnConfig

- `turn_timeout` (double, optional, default: 7) — 再次联系用户前等待用户回复的最长时间
- `initial_wait_time` (double, optional, nullable) — How long the agent will wait for the user to start the conversation if the first message is empty. If not set, uses the regular turn_timeout.
- `silence_end_call_timeout` (double, optional, default: -1) — 用户最后一次说话后终止通话前的最长等待时间
- `turn_eagerness` (enum, optional, default: normal) — 控制智能体的响应积极程度。Low = 较不积极（等待更久），Standard = 默认积极程度，High = 更积极（响应更快）。
  - Allowed values: `patient`, `normal`, `eager`
- `spelling_patience` (enum, optional, default: auto) — 控制用户逐个拼读数字和命名实体时，智能体是否应更耐心等待。Auto = 基于模型判断，Off = 不额外等待。
  - Allowed values: `auto`, `off`
- `speculative_turn` (boolean, optional, default: false) — 启用后，在达到完整轮次置信度前的静音期间开始生成 LLM 回复，以降低感知延迟。可能增加 LLM 成本。
- `retranscribe_on_turn_timeout` (boolean, optional, default: false) — 启用后，如果 VAD 未检测到语音，会在轮次超时时尝试重新转录累计音频。为当前智能体或 workflow 节点启用期间，将停用静音折扣计费。
- `turn_model` (enum, optional, default: turn_v3) — 要使用的轮次检测模型版本。
  - Allowed values: `turn_v2`, `turn_v3`
- `interruption_ignore_terms` (list of string, optional) — 用户说出时不应触发打断的词条列表（例如“gotcha”“understood”）。使用不区分大小写的精确匹配。
- `interruption_ignore_term_languages` (list of string, optional) — 已启用预设忽略词类别的语言代码。明确存储，避免根据词条重叠推断显示内容。
- `merge_with_default_ignore_terms` (boolean, optional, default: false) — 启用后，除 interruption_ignore_terms 外，还会使用为 interruption_ignore_term_languages 精选的默认词条。
- `transcribe_on_disabled_interruptions` (boolean, optional, default: false) — 禁用打断时，仍会转写用户所说内容，以便带入下一轮。关闭后，不可打断轮次期间的用户语音将被忽略，且不会触发新一轮。

### VADConfig

### ConversationConfig-Input

- `text_only` (boolean, optional, default: false) — 启用后将不处理音频，仅使用文本，可避免音频计费。
- `max_duration_seconds` (integer, optional, default: 600) — 单次对话的最长时长，单位为秒
- `client_events` (list of enum, optional) — 将发送至客户端的事件
  - Allowed values: `conversation_initiation_metadata`, `asr_initiation_metadata`, `ping`, `audio`, `interruption`, `user_transcript`, `tentative_user_transcript`, `agent_response`, `agent_response_correction`, `client_tool_call`, `mcp_tool_call`, `mcp_connection_status`, `agent_tool_request`, `agent_tool_response`, `agent_tool_response_full_payload`, `agent_response_metadata`, `vad_score`, `agent_chat_response_part`, `client_error`, `guardrail_triggered`, `dtmf_request`, `agent_response_complete`, `context_usage`, `internal_turn_probability`, `internal_tentative_agent_response`
- `file_input` (FileInputConfig, optional) — Configuration for file input (image/PDF uploads) during conversations.
- `monitoring_enabled` (boolean, optional, default: false) — 通过 WebSocket 启用对话实时监控
- `monitoring_events` (list of enum, optional) — 将发送至监控连接的事件。
  - Allowed values: `conversation_initiation_metadata`, `asr_initiation_metadata`, `ping`, `audio`, `interruption`, `user_transcript`, `tentative_user_transcript`, `agent_response`, `agent_response_correction`, `client_tool_call`, `mcp_tool_call`, `mcp_connection_status`, `agent_tool_request`, `agent_tool_response`, `agent_tool_response_full_payload`, `agent_response_metadata`, `vad_score`, `agent_chat_response_part`, `client_error`, `guardrail_triggered`, `dtmf_request`, `agent_response_complete`, `context_usage`, `internal_turn_probability`, `internal_tentative_agent_response`
- `dtmf_input_settings` (DTMFInputConfig, optional, nullable) — Configure DTMF (keypad) input collection during phone calls
- `background_sound` (BackgroundSoundConfig, optional) — Configuration for background sound during conversations.
- `source_attribution` (boolean, optional, default: false) — 启用后，若存在知识库内容，将要求 LLM 报告所使用的来源。

### PrivacyConfig-Input

- `record_voice` (boolean, optional, default: true) — 是否录制会话
- `retention_days` (integer, optional, default: -1) — 对话保留天数。-1 表示不限制保留时间
- `delete_transcript_and_pii` (boolean, optional, default: false) — 是否删除转录文本和 PII
- `delete_audio` (boolean, optional, default: false) — 是否删除音频
- `apply_to_existing_conversations` (boolean, optional, default: false) — 是否将隐私设置应用于现有对话
- `zero_retention_mode` (boolean, optional, default: false) — 是否启用零保留模式，即不存储 PII 数据
- `conversation_history_redaction` (ConversationHistoryRedactionConfig, optional) — Config for PII redaction in the conversation history

### AgentCallLimits

- `agent_concurrency_limit` (integer, optional, default: -1) — 最大并发对话数。-1 表示无上限
- `daily_limit` (integer, optional, default: 100000) — 每天最大对话数
- `bursting_enabled` (boolean, optional, default: true) — 是否启用突发并发。如果为 true，则允许超出工作区并发限制，最高可达限制的 3 倍。超出限制时，调用将按双倍费率收费。

### SpeechEngineConversationInitiationClientDataConfig

- `first_message` (boolean, optional, default: false) — 客户端是否可覆盖首条消息

### TTSConversationalConfig-Output

- `model_id` (enum, optional, default: eleven_v4_turbo) — 用于 TTS 的模型
  - Allowed values: `eleven_turbo_v2`, `eleven_turbo_v2_5`, `eleven_flash_v2`, `eleven_flash_v2_5`, `eleven_multilingual_v2`, `eleven_v3_conversational`, `eleven_v4`, `eleven_v4_turbo`
- `voice_id` (string, optional, default: cjVigY5qzO86Huf0OWal) — 用于 TTS 的音色 ID。
- `supported_voices` (list of SupportedVoice, optional) — 智能体额外支持的音色
- `expressive_mode` (boolean, optional, default: true) — 启用后，应用富表现力音频标签提示词。非 v3 模型会自动禁用。
- `suggested_audio_tags` (list of SuggestedAudioTag, optional) — 用于增强富有表现力语音的建议音频标签（适用于 eleven_v3 和 eleven_v3_conversational 模型）。智能体仍可使用此处未列出的其他标签。
- `agent_output_audio_format` (enum, optional, default: pcm_16000) — TTS 使用的音频格式
  - Allowed values: `pcm_8000`, `pcm_16000`, `pcm_22050`, `pcm_24000`, `pcm_44100`, `pcm_48000`, `ulaw_8000`
- `stability` (double, optional, default: 0.5) — 生成语音的稳定性
- `speed` (double, optional, default: 1) — 生成语音的速度
- `similarity_boost` (double, optional, default: 0.8) — 生成语音的相似度增强
- `text_normalisation_type` (enum, optional, default: system_prompt) — 将文本转为语音前把数字转换为文字的方法。设为 SYSTEM_PROMPT 时，系统提示词会更新为包含规范化说明。设为 ELEVENLABS 时，文本会在生成后规范化，这会略微增加延迟。
  - Allowed values: `system_prompt`, `elevenlabs`
- `pronunciation_dictionary_locators` (list of PydanticPronunciationDictionaryVersionLocator, optional) — 发音词典定位器
- `enable_phoneme_tags` (boolean, optional, default: true) — 选择为 V3 模型启用 SSML 音素标签处理。启用后，音素标签（内联及来自发音词典的标签）会先解析为内联 IPA，再发送给模型。
- `audio_effects` (EffectsSpec-Output, optional, nullable) — 可选的 TTS 效果规格：滤镜预设、距离（近讲 EQ）和环境（卷积混响）。
- `optimize_streaming_latency` (enum, optional, deprecated) — 已弃用：此字段无效，将被忽略。
  - Allowed values: `0`, `1`, `2`, `3`, `4`

### ConversationConfig-Output

- `text_only` (boolean, optional, default: false) — 启用后将不处理音频，仅使用文本，可避免音频计费。
- `max_duration_seconds` (integer, optional, default: 600) — 单次对话的最长时长，单位为秒
- `client_events` (list of enum, optional) — 将发送至客户端的事件
  - Allowed values: `conversation_initiation_metadata`, `asr_initiation_metadata`, `ping`, `audio`, `interruption`, `user_transcript`, `tentative_user_transcript`, `agent_response`, `agent_response_correction`, `client_tool_call`, `mcp_tool_call`, `mcp_connection_status`, `agent_tool_request`, `agent_tool_response`, `agent_tool_response_full_payload`, `agent_response_metadata`, `vad_score`, `agent_chat_response_part`, `client_error`, `guardrail_triggered`, `dtmf_request`, `agent_response_complete`, `context_usage`, `internal_turn_probability`, `internal_tentative_agent_response`
- `file_input` (FileInputConfig, optional) — Configuration for file input (image/PDF uploads) during conversations.
- `monitoring_enabled` (boolean, optional, default: false) — 通过 WebSocket 启用对话实时监控
- `monitoring_events` (list of enum, optional) — 将发送至监控连接的事件。
  - Allowed values: `conversation_initiation_metadata`, `asr_initiation_metadata`, `ping`, `audio`, `interruption`, `user_transcript`, `tentative_user_transcript`, `agent_response`, `agent_response_correction`, `client_tool_call`, `mcp_tool_call`, `mcp_connection_status`, `agent_tool_request`, `agent_tool_response`, `agent_tool_response_full_payload`, `agent_response_metadata`, `vad_score`, `agent_chat_response_part`, `client_error`, `guardrail_triggered`, `dtmf_request`, `agent_response_complete`, `context_usage`, `internal_turn_probability`, `internal_tentative_agent_response`
- `dtmf_input_settings` (DTMFInputConfig, optional, nullable) — Configure DTMF (keypad) input collection during phone calls
- `background_sound` (BackgroundSoundConfig, optional) — Configuration for background sound during conversations.
- `source_attribution` (boolean, optional, default: false) — 启用后，若存在知识库内容，将要求 LLM 报告所使用的来源。

### PrivacyConfig-Output

- `record_voice` (boolean, optional, default: true) — 是否录制会话
- `retention_days` (integer, optional, default: -1) — 对话保留天数。-1 表示不限制保留时间
- `delete_transcript_and_pii` (boolean, optional, default: false) — 是否删除转录文本和 PII
- `delete_audio` (boolean, optional, default: false) — 是否删除音频
- `apply_to_existing_conversations` (boolean, optional, default: false) — 是否将隐私设置应用于现有对话
- `zero_retention_mode` (boolean, optional, default: false) — 是否启用零保留模式，即不存储 PII 数据
- `conversation_history_redaction` (ConversationHistoryRedactionConfig, optional) — Config for PII redaction in the conversation history

### AgentMetadataDBModel

- `created_at_unix_secs` (integer, required)
- `updated_at_unix_secs` (integer, required)
- `created_from` (enum, optional, default: unknown)
  - Allowed values: `cli`, `ui`, `api`, `template`, `unknown`
- `last_updated_from` (enum, optional, default: unknown)
  - Allowed values: `cli`, `ui`, `api`, `template`, `unknown`

### ResourceAccessInfo

- `is_creator` (boolean, required) — 发出请求的用户是否为该智能体的创建者
- `creator_name` (string, required) — 智能体创建者名称
- `creator_email` (string, required) — 智能体创建者的邮箱
- `role` (enum, required) — 发出请求的用户角色
  - Allowed values: `admin`, `editor`, `commenter`, `viewer`
- `anonymous_access_level_override` (enum, optional, nullable) — 匿名用户的访问级别。若为 None，该资源不会公开共享。
  - Allowed values: `admin`, `editor`, `commenter`, `viewer`
- `access_source` (enum, optional, nullable) — 请求用户拥有此资源访问权限的原因。'creator' = 调用者是所有者。'explicit' = 调用者（或其所属的某个工作区群组）列于 role_to_group_ids 中，且不包括工作区范围的所有人群组。'workspace_default' = 工作区范围的所有人群组列于 role_to_group_ids 中（所有非匿名工作区成员，包括管理员，均可查看此资源）。'workspace_admin' = 调用者是工作区管理员，且管理员席位是 *唯一* 的访问路径；此项仅用于其他人均无法查看的文档。这样 UI 可说明管理员绕过权限的查看者为何能看到未明确向其共享的文档。
  - Allowed values: `creator`, `explicit`, `workspace_admin`, `workspace_default`

### ValidationError

- `loc` (list of ValidationErrorLocItems, required)
- `msg` (string, required)
- `type` (string, required)

### SpeechEngineConfigRequestHeaders

- string
- ConvAISecretLocator: ConvAISecretLocator
- ConvAIDynamicVariable: ConvAIDynamicVariable

### SupportedVoice

- `label` (string, required)
- `voice_id` (string, required)
- `description` (string, optional, nullable)
- `language` (string, optional, nullable)
- `model_family` (enum, optional, nullable)
  - Allowed values: `turbo`, `flash`, `multilingual`, `v3_conversational`, `v4`, `v4_turbo`
- `optimize_streaming_latency` (enum, optional, nullable)
  - Allowed values: `0`, `1`, `2`, `3`, `4`
- `stability` (double, optional, nullable)
- `speed` (double, optional, nullable)
- `similarity_boost` (double, optional, nullable)

### SuggestedAudioTag

- `tag` (string, required) — Audio tag to use (for best performance, 1-2 words, e.g., 'happy', 'excited')
- `description` (string, optional, nullable) — 何时使用此标签的可选说明

### PydanticPronunciationDictionaryVersionLocator

供其他文档引用特定词典及其版本的定位符。 这是 PronunciationDictionaryVersionLocatorDBModel 的 pydantic 版本。 用于确保与其他智能体数据模型兼容。

- `pronunciation_dictionary_id` (string, required) — 发音词典的 ID
- `version_id` (string, required, nullable) — 发音词典版本的 ID

### EffectsSpec-Input

应用于生成语音的音频效果：滤镜预设、感知距离、混响 环境、背景噪声底音和立体声声像。将所有字段保留为默认值， 即可获得未经处理的音频。

- `filter_preset_id` (string, optional, nullable) — 为语音增添音色特征的滤镜预设 ID，例如 `phone` 或 `old_radio`。使用 `GET /v1/audio-effects/catalog` 列出有效 ID。
- `distance` (double, optional, default: 0) — 说话者听起来与麦克风的距离，范围为 0（近，不变）至 1（远）。值越高，低频和高频衰减越多；设置环境后，干声与混响之间的平衡会更偏向混响。
- `environment_id` (string, optional, nullable) — 将语音置于特定空间中的混响环境 ID，例如 `small_room` 或 `hall`。使用 `GET /v1/audio-effects/catalog` 列出有效 ID。混响以立体声渲染，并会在语音结束后添加最长数秒的余响。
- `background_noise_id` (string, optional, nullable) — 在语音下方循环播放的背景噪声底音 ID，例如 `cafe` 或 `keyboard`。使用 `GET /v1/audio-effects/catalog` 列出有效 ID。
- `send_level` (double, optional, default: 1) — 输入混响的语音比例，范围为 0（无）至 1（全部）。仅在设置 `environment_id` 时生效；0 会关闭混响。
- `pan` (double, optional, default: 0) — 音色的立体声位置，范围从 -1（最左）经 0（居中）到 1（最右）。仅音色会进行声像定位；混响和背景噪声保持居中。

### FileInputConfig

- `enabled` (boolean, optional, default: true) — 启用后，如果 LLM 支持多模态输入，用户可在聊天中附加图片、PDF 或文本文件。
- `max_files_in_memory` (integer, optional, default: 10) — 对话期间保留在内存中的最新文件数量。较旧文件会被总结并释放其字节数据。
- `max_files_per_conversation` (integer, optional, default: 10) — 用户在一次对话中可上传的文件总数。上传按文件计费。使用 -1 表示不限，或设为大于等于 max_files_in_memory 的值。

### DTMFInputConfig

Configuration for DTMF (keypad) input collection during phone calls.

- `dtmf_input_timeout` (double, optional, default: 2) — 等待额外 DTMF 按键的超时时间（秒）。
- `hash_terminator` (boolean, optional, default: true) — 如果为 true，按下 # 会立即完成 DTMF 输入。
- `redact_input` (boolean, optional, default: false) — 如果为 true，将在转录文本、对话日志和分析中用脱敏标记替换来电者的 DTMF（键盘）输入。智能体复述或传递给工具的数字不受影响。

### BackgroundSoundConfig

- `source_type` (enum, optional, nullable) — 背景声音源类型。
  - Allowed values: `preset`
- `source_id` (enum, optional, nullable) — 声音源标识符。
  - Allowed values: `office2`, `office1`, `restaurant`, `city`, `typing`, `elevator1`, `elevator2`, `elevator3`, `elevator4`
- `volume` (double, optional, default: 0.15) — 背景音量级别（0.01 至 1.0）。
- `crossfade_loop` (boolean, optional, default: true) — 在循环边界应用交叉淡化，避免声音循环时出现爆音。

### ConversationHistoryRedactionConfig

- `enabled` (boolean, optional, default: false) — 是否启用对话历史记录脱敏
- `entities` (list of enum, optional) — 要从对话转录、音频和分析中脱敏的实体。使用顶级类型，如 'name'、'email_address'，或使用点表示法指定子类型，如 'name.full_name'。
  - Allowed values: `name`, `name.name_given`, `name.name_family`, `name.name_other`, `email_address`, `contact_number`, `dob`, `age`, `religious_belief`, `political_opinion`, `sexual_orientation`, `ethnicity_race`, `marital_status`, `occupation`, `physical_attribute`, `language`, `username`, `password`, `url`, `organization`, `financial_id`, `financial_id.payment_card`, `financial_id.payment_card.payment_card_number`, `financial_id.payment_card.payment_card_expiration_date`, `financial_id.payment_card.payment_card_cvv`, `financial_id.bank_account`, `financial_id.bank_account.bank_account_number`, `financial_id.bank_account.bank_routing_number`, `financial_id.bank_account.swift_bic_code`, `financial_id.financial_id_other`, `location`, `location.location_address`, `location.location_city`, `location.location_postal_code`, `location.location_coordinate`, `location.location_state`, `location.location_country`, `location.location_other`, `date`, `date_interval`, `unique_id`, `unique_id.government_issued_id`, `unique_id.account_number`, `unique_id.vehicle_id`, `unique_id.healthcare_number`, `unique_id.healthcare_number.medical_record_number`, `unique_id.healthcare_number.health_plan_beneficiary_number`, `unique_id.device_id`, `unique_id.unique_id_other`, `medical`, `medical.medical_condition`, `medical.medication`, `medical.medical_procedure`, `medical.medical_measurement`, `medical.medical_other`
- `excluded_data_collection_ids` (list of string, optional) — 提取值未脱敏的数据收集项 ID。其理由仍会脱敏。

### EffectsSpec-Output

应用于生成语音的音频效果：滤镜预设、感知距离、混响 环境、背景噪声底音和立体声声像。将所有字段保留为默认值， 即可获得未经处理的音频。

- `filter_preset_id` (string, required, nullable) — 为语音增添音色特征的滤镜预设 ID，例如 `phone` 或 `old_radio`。使用 `GET /v1/audio-effects/catalog` 列出有效 ID。
- `distance` (double, required, default: 0) — 说话者听起来与麦克风的距离，范围为 0（近，不变）至 1（远）。值越高，低频和高频衰减越多；设置环境后，干声与混响之间的平衡会更偏向混响。
- `environment_id` (string, required, nullable) — 将语音置于特定空间中的混响环境 ID，例如 `small_room` 或 `hall`。使用 `GET /v1/audio-effects/catalog` 列出有效 ID。混响以立体声渲染，并会在语音结束后添加最长数秒的余响。
- `background_noise_id` (string, required, nullable) — 在语音下方循环播放的背景噪声底音 ID，例如 `cafe` 或 `keyboard`。使用 `GET /v1/audio-effects/catalog` 列出有效 ID。
- `send_level` (double, required, default: 1) — 输入混响的语音比例，范围为 0（无）至 1（全部）。仅在设置 `environment_id` 时生效；0 会关闭混响。
- `pan` (double, required, default: 0) — 音色的立体声位置，范围从 -1（最左）经 0（居中）到 1（最右）。仅音色会进行声像定位；混响和背景噪声保持居中。

### ValidationErrorLocItems

- string
- integer

### ConvAISecretLocator

用于引用智能体密钥存储中的密钥。

- `secret_id` (string, required)

### ConvAIDynamicVariable

用于引用动态变量。

- `variable_name` (string, required)

## Examples

**Request**

```json
{
  "speech_engine": {
    "ws_url": "string"
  }
}
```

**Response**

```json
{
  "speech_engine_id": "seng_3701k3ttaq12ewp8b7qv5rfyszkz",
  "name": "My Speech Engine",
  "speech_engine": {
    "ws_url": "wss://example.com/transcript",
    "request_headers": {}
  },
  "asr": {
    "quality": "high",
    "provider": "elevenlabs",
    "user_input_audio_format": "pcm_16000",
    "keywords": []
  },
  "tts": {
    "model_id": "eleven_flash_v2",
    "voice_id": "cjVigY5qzO86Huf0OWal",
    "agent_output_audio_format": "pcm_16000",
    "stability": 0.5,
    "speed": 1,
    "similarity_boost": 0.8,
    "optimize_streaming_latency": 3
  },
  "turn": {
    "turn_timeout": 7,
    "silence_end_call_timeout": -1,
    "turn_eagerness": "normal",
    "mode": "turn"
  },
  "vad": {
    "background_voice_detection": false
  },
  "conversation": {
    "max_duration_seconds": 600,
    "client_events": [
      "audio",
      "interruption",
      "agent_response",
      "user_transcript"
    ]
  },
  "privacy": {
    "record_voice": true,
    "retention_days": -1,
    "delete_transcript_and_pii": false,
    "delete_audio": false,
    "apply_to_existing_conversations": false,
    "zero_retention_mode": false
  },
  "call_limits": {
    "agent_concurrency_limit": -1,
    "daily_limit": 100000,
    "bursting_enabled": true
  },
  "language": "en",
  "cascade_timeout_seconds": 4,
  "tags": [
    "production",
    "v1"
  ],
  "overrides": {
    "first_message": false
  },
  "metadata": {
    "created_at_unix_secs": 1714000000,
    "updated_at_unix_secs": 1714000000,
    "created_from": "api",
    "last_updated_from": "api"
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.elevenlabs.io/v1/speech-engine"

payload = { "speech_engine": { "ws_url": "string" } }
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.elevenlabs.io/v1/speech-engine';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"speech_engine":{"ws_url":"string"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.elevenlabs.io/v1/speech-engine"

	payload := strings.NewReader("{\n  \"speech_engine\": {\n    \"ws_url\": \"string\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.elevenlabs.io/v1/speech-engine")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"speech_engine\": {\n    \"ws_url\": \"string\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.elevenlabs.io/v1/speech-engine")
  .header("Content-Type", "application/json")
  .body("{\n  \"speech_engine\": {\n    \"ws_url\": \"string\"\n  }\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.elevenlabs.io/v1/speech-engine', [
  'body' => '{
  "speech_engine": {
    "ws_url": "string"
  }
}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.elevenlabs.io/v1/speech-engine");
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"speech_engine\": {\n    \"ws_url\": \"string\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Content-Type": "application/json"]
let parameters = ["speech_engine": ["ws_url": "string"]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.elevenlabs.io/v1/speech-engine")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```