ElevenLabs Python SDK语音转文字功能中additional_formats参数的正确使用方法

在语音处理领域，将音频转换为文字并生成多种格式的字幕文件是常见需求。ElevenLabs Python SDK的speech_to_text功能提供了这一能力，但开发者在使用additional_formats参数时可能会遇到类型错误问题。

问题现象

当开发者尝试使用additional_formats参数导出SRT等字幕格式时，系统会抛出TypeError，提示"Invalid type for value. Expected primitive type, got <class 'dict'>"。这表明SDK在处理参数时遇到了类型不匹配的问题。

根本原因

这个问题源于HTTP请求构建过程中对复杂数据类型的处理方式。HTTP协议本身对multipart/form-data格式的数据传输有严格要求，当遇到嵌套的字典结构时，标准的HTTP客户端库无法自动将其序列化为有效的表单数据。

解决方案

正确的做法是将additional_formats参数转换为JSON字符串格式。以下是具体实现方法：

import json
from elevenlabs import speech_to_text

transcription = await client.speech_to_text.convert(
    file=buffer,
    model_id='scribe_v1',
    tag_audio_events=True,
    timestamps_granularity="word",
    diarize=True,
    request_options=RequestOptions(timeout_in_seconds=180),
    language_code=iso639_1_to_2(language),
    additional_formats=json.dumps([{
        "format": "srt",
        "max_characters_per_line": 40,
        "include_speakers": True,
        "include_timestamps": True,
        "segment_on_silence_longer_than_s": 1.1,
        "max_segment_chars": 80
    }])
)

技术细节

1. 参数序列化：通过json.dumps()方法将字典结构转换为JSON字符串，确保数据能够被HTTP客户端正确处理。

2. 格式规范：additional_formats接受一个数组，每个元素代表一种导出格式的配置。对于SRT格式，可配置参数包括：

   • 每行最大字符数
   • 是否包含说话人信息
   • 是否包含时间戳
   • 静音分段阈值
   • 段落最大字符数

3. 多格式支持：如果需要同时导出多种格式，只需在数组中添加多个配置对象即可。

最佳实践

1. 始终对复杂参数进行JSON序列化
2. 在开发环境中先测试小片段音频
3. 合理设置超时参数，特别是处理长音频时
4. 根据目标语言选择合适的语言代码

通过遵循这些指导原则，开发者可以充分利用ElevenLabs Python SDK强大的语音转文字功能，同时避免常见的参数处理问题。