创建转录文本

POST

/v1/speech-to-text

转录音频或视频文件。若 webhook 设为 true，请求将异步处理，结果会发送到已配置的 webhook。若 use_multi_channel 为 true 且提供的音频包含多个声道，将返回一个 ‘transcripts’ 对象，其中包含每个声道的独立转录；设置 multichannel_output_style=‘combined’ 则会返回按时间合并排序的单份转录。否则返回单份转录。可选参数 webhook_metadata 可附加自定义数据，这些数据将包含在 webhook 响应中，用于请求关联和跟踪。

转录音频或视频文件。若 webhook 设为 true，请求将异步处理，结果会发送到已配置的 webhook。若 use_multi_channel 为 true 且提供的音频包含多个声道，将返回一个 'transcripts' 对象，其中包含每个声道的独立转录；设置 multichannel_output_style='combined' 则会返回按时间合并排序的单份转录。否则返回单份转录。可选参数 webhook_metadata 可附加自定义数据，这些数据将包含在 webhook 响应中，用于请求关联和跟踪。

查询参数

tokenstring or null可选

通过 POST /v1/single-use-token/batch_scribe 创建的一次性身份验证令牌。该令牌只能使用一次，并会在 15 分钟后过期。可作为前端客户端 API 密钥或 bearer 令牌身份验证的替代方案。

enable_loggingboolean可选默认为 true

当 enable_logging 设为 false 时，此请求将使用零留存模式。这意味着该请求无法使用日志和转写存储功能。零留存模式仅限企业版客户使用。

请求

This endpoint expects a multipart form containing an optional file.

model_idstring必需

用于转录的模型 ID。

filefile可选

要转录的文件（音频最短 100ms）。支持所有主流音频和视频格式。必须且只能提供 file 或 cloud_storage_url 参数之一。文件大小必须小于 5.0GB。

language_codestring or null可选

与音频文件语言对应的 ISO-639-1 或 ISO-639-3 language_code。如能预先确定，有时可提升转录性能。默认值为 null，此时会自动预测语言。

transcript_editstring or null可选

应用于最终转录文本的自然语言指令（最多 2000 个字符）。编辑后的文本会在 ‘edited_transcript’ 中与原始转录文本一并返回。不能与 entity_detection、entity_redaction 或 use_multi_channel 结合使用。使用此参数将产生基础转录费用额外 30% 的附加费，按至少 10 秒音频计费。

应用于最终转录文本的自然语言指令（最多 2000 个字符）。编辑后的文本会在 'edited_transcript' 中与原始转录文本一并返回。不能与 entity_detection、entity_redaction 或 use_multi_channel 结合使用。使用此参数将产生基础转录费用额外 30% 的附加费，按至少 10 秒音频计费。

tag_audio_eventsboolean可选默认为 true

是否在转录中标记（笑声）、（脚步声）等音频事件。

num_speakersinteger or null可选1-32

上传文件中同时说话的最大说话人数。可帮助预测各人说话的时间。最多可预测 32 位说话人。默认值为 null，此时说话人数将设为模型支持的最大值。

timestamps_granularityenum可选默认为 word

转录中时间戳的粒度。‘word’ 提供单词级时间戳，‘character’ 为每个单词提供字符级时间戳。

允许的值:

diarizeboolean可选默认为 false

是否标注上传文件中当前正在说话的说话人。

diarization_thresholddouble or null可选0.1-0.4

说话人分离时应用的阈值。较高的值会降低将同一说话人分为两个不同说话人的概率，但会提高将两个不同说话人分为同一说话人的概率（预测的说话人总数更少）。较低的值会提高将同一说话人分为两个不同说话人的概率，但会降低将两个不同说话人分为同一说话人的概率（预测的说话人总数更多）。仅当 diarize=True 且 num_speakers=None 时可设置。默认为 None，此时将根据 model_id 选择阈值（通常为 0.22）。

additional_formatslist of objects可选

要导出转录文本的其他格式列表。

file_formatenum可选默认为 other

输入音频的格式。可选值为 ‘pcm_s16le_16’ 或 ‘other’。对于 pcm_s16le_16，输入音频必须是采样率为 16kHz、单声道、采用小端字节序的 16 位 PCM。延迟将低于传入编码波形。

允许的值:

cloud_storage_urlstring or null可选Deprecated

[Deprecated] 此参数已弃用，未来将移除。请改用 ‘source_url’。要转录文件的 HTTPS URL。必须且只能提供 file 或 cloud_storage_url 参数之一。文件必须可通过 HTTPS 访问，且大小小于 2GB。接受任何有效的 HTTPS URL，包括云存储提供商（AWS S3、Google Cloud Storage、Cloudflare R2 等）、CDN 或其他 HTTPS 来源的 URL。URL 可以是预签名 URL，也可以在查询参数中包含身份验证令牌。

[Deprecated] 此参数已弃用，未来将移除。请改用 'source_url'。要转录文件的 HTTPS URL。必须且只能提供 file 或 cloud_storage_url 参数之一。文件必须可通过 HTTPS 访问，且大小小于 2GB。接受任何有效的 HTTPS URL，包括云存储提供商（AWS S3、Google Cloud Storage、Cloudflare R2 等）、CDN 或其他 HTTPS 来源的 URL。URL 可以是预签名 URL，也可以在查询参数中包含身份验证令牌。

source_urlstring or null可选

要转录的音频或视频文件 URL。支持托管的视频或音频文件、YouTube 视频 URL、TikTok 视频 URL 及其他视频托管服务。

webhookboolean可选默认为 false

是否将转录结果发送到已配置的语音转文本 webhook。设置后，请求会提前返回且不包含转录结果，结果将稍后通过 webhook 发送。

webhook_idstring or null可选

用于接收转录结果的可选指定 webhook ID。仅当 webhook 设为 true 时有效。未提供时，转录结果将发送到所有已配置的语音转文本 webhook。

temperaturedouble or null可选0-2

控制转录输出的随机性。可接受 0.0 至 2.0 之间的值，值越高，结果越多样且确定性越低。省略时，将根据所选模型使用温度值，通常为 0。

seedinteger or null可选0-2147483647

指定后，系统会尽力进行确定性采样，使使用相同种子和参数的重复请求返回相同结果。但不保证完全确定。必须是介于 0 和 2147483647 之间的整数。

use_multi_channelboolean可选默认为 false

音频文件是否包含多个声道，且每个声道只有一位说话人。启用后，将独立转录每个声道。默认每个声道返回一份单独的转录文本；设置 multichannel_output_style=‘combined’ 则会返回一份合并所有声道并按时间排序的转录文本。响应中的每个词都包含 ‘channel_index’ 字段，用于标识其所在声道。最多支持 5 个声道。每个声道均按完整音频时长独立计费，因此费用会随声道数量线性增长。

音频文件是否包含多个声道，且每个声道只有一位说话人。启用后，将独立转录每个声道。默认每个声道返回一份单独的转录文本；设置 multichannel_output_style='combined' 则会返回一份合并所有声道并按时间排序的转录文本。响应中的每个词都包含 'channel_index' 字段，用于标识其所在声道。最多支持 5 个声道。每个声道均按完整音频时长独立计费，因此费用会随声道数量线性增长。

multichannel_output_styleenum可选默认为 separate

启用 use_multi_channel 时，控制响应结构。‘separate’（默认）会在 ‘transcripts’ 下为每个声道返回一份转录。‘combined’ 会将所有声道合并为一份转录，其中的词语按开始时间排序，每个词都带有 ‘channel_index’，与单声道响应结构一致。‘combined’ 需要时间戳（timestamps_granularity 不得为 ‘none’），且不支持实体检测或脱敏。

启用 use_multi_channel 时，控制响应结构。'separate'（默认）会在 'transcripts' 下为每个声道返回一份转录。'combined' 会将所有声道合并为一份转录，其中的词语按开始时间排序，每个词都带有 'channel_index'，与单声道响应结构一致。'combined' 需要时间戳（timestamps_granularity 不得为 'none'），且不支持实体检测或脱敏。

允许的值:

webhook_metadatastring or map from strings to any or null可选

要包含在 webhook 响应中的可选元数据。应为表示对象的 JSON 字符串，最大深度为 2 层、最大大小为 16KB。可用于追踪内部 ID、任务引用或其他上下文信息。

entity_detectionstring or list of strings or null可选

检测转录文本中的实体。可以设为 ‘all’ 以检测所有实体，也可以设为单个实体类型或类别字符串，或实体类型／类别列表。类别包括 ‘pii’、‘phi’、‘pci’、‘other’、‘offensive_language’。启用后，检测到的实体将通过 ‘entities’ 字段返回其文本、类型和字符位置。使用此参数将按基础转录费用额外收取 30% 的费用。

检测转录文本中的实体。可以设为 'all' 以检测所有实体，也可以设为单个实体类型或类别字符串，或实体类型／类别列表。类别包括 'pii'、'phi'、'pci'、'other'、'offensive_language'。启用后，检测到的实体将通过 'entities' 字段返回其文本、类型和字符位置。使用此参数将按基础转录费用额外收取 30% 的费用。

no_verbatimboolean可选默认为 false

如果为 true，转录文本不会包含填充词、起句错误和非语音声音。仅支持 scribe_v2 模型。

use_speaker_libraryboolean可选默认为 false

是否在说话人分离期间使用说话人库识别已知说话人。启用且 diarize 为 true 时，检测到的说话人将与工作区说话人库中已注册的说话人进行匹配。

detect_speaker_rolesboolean可选默认为 false

是否检测说话者角色（智能体或客户）。需要 diarize=true。不能与 use_multi_channel=true 同时使用。启用后，speaker_id 的值将为 ‘agent’ 和 ‘customer’，而非 ‘speaker_0’、‘speaker_1’ 等。使用此功能将额外收取基础转录费用的 10%。

entity_redactionstring or list of strings or null可选

从转录文本中脱敏实体。接受与 entity_detection 相同的格式：‘all’、类别（‘pii’、‘phi’）或特定实体类型。必须是 entity_detection 的子集。启用脱敏后，不会返回 entities 字段。使用此参数会在基础转录费用上额外加收 30%。

entity_redaction_modestring可选默认为 enumerated_entity_type

如何格式化已脱敏实体。‘redacted’ 替换为 {REDACTED}，‘entity_type’ 替换为 {ENTITY_TYPE}，‘enumerated_entity_type’ 替换为 {ENTITY_TYPE_N}，其中 N 为每次出现编号。仅在设置 entity_redaction 时使用。

keytermslist of strings可选默认为 []

A list of keyterms to bias the transcription towards. The keyterms are words or phrases you want the model to recognise more accurately. The number of keyterms cannot exceed 1000. The length of each keyterm must be less than 50 characters. Keyterms can contain at most 5 words (after normalisation). For example [“hello”, “world”, “technical term”]. The following characters are not supported: <, >, {, }, [, ], \. Usage of this parameter will incur an additional 20% surcharge on the base transcription cost. When more than 100 keyterms are provided, a minimum billable duration of 20 seconds applies per request.

A list of keyterms to bias the transcription towards. The keyterms are words or phrases you want the model to recognise more accurately. The number of keyterms cannot exceed 1000. The length of each keyterm must be less than 50 characters. Keyterms can contain at most 5 words (after normalisation). For example ["hello", "world", "technical term"]. The following characters are not supported: `<`, `>`, `{`, `}`, `[`, `]`, `\`. Usage of this parameter will incur an additional 20% surcharge on the base transcription cost. When more than 100 keyterms are provided, a minimum billable duration of 20 seconds applies per request.

响应

同步转录结果

SpeechToTextChunkResponseModelobject

Chunk-level detail of the transcription with timing information.

MultichannelSpeechToTextResponseModelobject

多声道语音转文本转录的响应模型。

SpeechToTextWebhookResponseModelobject

错误

422

Unprocessable Entity Error

请求头

查询参数

请求

响应

错误