EdgeSpeak
中文
语言
English中文

把已知文本对齐到音频

POST /v1/audio/alignments

在音频里定位已知的词，而不是识别未知语音。传 file 和对应的 text；桌面网关还接受绝对路径 text_path，Headless 服务必须传 text。时间戳始终相对原始音频：duration 是整段媒体时长，usage.seconds 是处理窗口。带 progress: 1 请求头会返回 NDJSON 进度流，结果行带 task: "align"；逐行独立解析，不要当 SSE。见 /docs/api-align#align 和 /docs/api#alignment-options 。对齐失败返回 422 和 error.alignment 对象，不返回结果；search_effort 选择搜索范围，并可自动扩大范围重试一次。

指南与示例强制对齐全部接口

参数

progressstring设为 1 返回 NDJSON 对齐进度流。普通请求返回单个 JSON 响应。1

请求体

multipart/form-data必填

filefile必填音频文件。
textstring要对齐的文稿。Headless 服务下必填。
text_pathstring仅桌面网关：文稿在本机的绝对路径。
modelstring可选的对齐模型。默认的 EdgeSpeak/Lattice-2 覆盖目录里全部语言、混合语言文本和 und；EdgeSpeak/Lattice-1 只覆盖中文、英文和德文，需要显式传 model=EdgeSpeak/Lattice-1 才会使用。传转录或播报模型返回 400 model_capability_unsupported，ID 不存在返回 404 model_not_found，两者都带 param: "model"。
languagestring可选提示。不传则由运行时检测语言；传 zh、yue 这类代码可以钉死一门语言；传 und 表示跳过检测、当作没有语言。EdgeSpeak/Lattice-1 对 und 和列表外的代码返回 400 bad_request，对它不覆盖的语言返回 422 language_unsupported。见 /docs/languages#alignment 。
startnumber窗口起点，单位秒。与 end 一起传，需满足 0 <= start < end 且落在音频范围内。
endnumber窗口终点，单位秒。
search_effortstring搜索范围。standard 按标准范围搜索一次，传空值（""）也按它处理；extended 按更大的范围搜索一次，更慢，更耗内存；auto 先跑 standard，仅当它失败且 error.alignment.retry_recommended: true 时再跑一次 extended。其他取值返回 400 bad_request，param 为 "search_effort"。standard | extended | auto | 默认 "standard"
protected_terms[]string[]让产品名、术语这类词在对齐时当作一个整词，不被拆开。重复传这个字段，或者在 protected_terms 里传一个 JSON 数组。
text_normalizationstringmultipart 里是一个 JSON 字符串。整个字段不传表示开启归一化；{"enabled":false} 或空对象表示关闭。字段有 enabled、top_k（默认 8，范围 1–16）、classes、apply_dictionary（默认 false）、dictionary_ids，以及 pins：{source_start_byte, source_end_byte, rank}，按原始 UTF-8 文稿计算，rank: null 表示保留原文。关闭时不要传 top_k、classes 或非空的 pins。
audio_trackinteger从 0 开始的可解码音轨号。重复传互相冲突的值返回 400。
audio_channelstringmix，或从 0 开始的声道号。重复传互相冲突的值返回 400。
semantic_sentence_enabledboolean控制语义处理。显式传 false 与长度或余量字段冲突，返回 400。
min_charsinteger默认长度 12。长度约束默认关闭，传任一长度字段即开启，并同时请求语义处理。
max_charsinteger默认长度 42。
start_marginnumber秒；默认余量 0.2。
end_marginnumber秒；默认余量 0.2。

响应

200对齐结果。带 progress: 1 时返回体是 NDJSON：先是进度行；search_effort=auto 开始扩大搜索时有一行 {"stage":"extended_search"}，之后进度从 0 重新计；最后一行要么是结果（task: "align"），要么是与 422 响应体相同的 {"error": {...}} 信封。数据流的 HTTP 状态始终是 200；进度到 1.0 本身不能证明成功，数据流关闭时既没有结果行也没有错误行也按失败处理。
taskstringalign
durationnumber整段媒体时长。
languagestring运行时解析出语言时给出的规范语言代码。
language_candidatesstring[]本次对齐实际使用的候选语言，有序，首选在前。来自请求的 language 或参考文本，用于选择读法，不是对音频语言的声学判定。候选列表为空时省略，例如请求传了 und 或判定不出语言。
textstring
segmentsobject[]
idinteger该段在结果中的序号。
startnumber段落起点，单位秒。
endnumber段落终点，单位秒。
textstring段落文本。
speakerstring | null说话人标签；没有判定说话人时为 null。
wordsobject[]词级时间戳。只有请求了词级时间戳才会出现。
normalization_regionsobject[]文本归一化产生的区域和候选。词级 provenance 带 source_start_byte、source_end_byte 和 normalizations[]，都相对原始 UTF-8 文稿。
search_effort_usedstring实际运行的搜索档位。服务报告了才出现。standard | extended
search_retriedbooleansearch_effort=auto 在首次失败后确实跑了扩大搜索时为 true，否则省略。
usageobject转录与对齐的音频时长计量。
typestringduration
secondsnumber已处理的音频秒数。窗口对齐时这是处理窗口的长度，不是整段媒体时长。
JSON
{
  "task": "align",
  "duration": 2.5,
  "text": "Hello world.",
  "segments": [
    {
      "id": 0,
      "start": 0.2,
      "end": 1.4,
      "text": "Hello world.",
      "words": [
        {
          "word": "Hello",
          "start": 0.2,
          "end": 0.6,
          "score": 0.98
        },
        {
          "word": "world.",
          "start": 0.7,
          "end": 1.4,
          "score": 0.96
        }
      ]
    }
  ],
  "usage": {
    "type": "duration",
    "seconds": 2.5
  }
}
400请求不合法。先改请求再重试：error.code 用于程序判断，error.param 用于定位是哪个输入。
401API Key 缺失或无效。
403Host 或 Origin 不被允许，或 License 被拒。按 error.code 区分这两种情况。
404模型 ID 不存在（model_not_found）。
413请求体超过 512 MiB。
422alignment_failed：对齐跑了但没能完成。alignment_search_budget_exceeded：扩大搜索范围所需的内存超出本机可用范围，因此没有运行。两者都带 error.alignment，字段有 reason（no_path、no_words、collapsed、search_incomplete）、search_effort_used、search_path（whole_audio、streaming）、search_limit（none、budget、graph_size、estimate_overflow、streaming）、retry_recommended（始终出现）和 estimated_extra_bytes（扩大搜索预计额外占用的内存，是估算，不是上限）；服务不知道的字段会省略。对齐失败不计入用量。同一状态码也用于 language_unsupported（请换模型，而不是改语言代码）和 normalization_class_unsupported。
JSON
{
  "error": {
    "message": "Alignment could not be completed; the search stopped before the end of the text.",
    "type": "invalid_request_error",
    "code": "alignment_failed",
    "alignment": {
      "reason": "search_incomplete",
      "search_effort_used": "standard",
      "search_path": "whole_audio",
      "search_limit": "none",
      "retry_recommended": true,
      "estimated_extra_bytes": 3221225472
    }
  }
}
503所需的本地模型仍在准备（model_downloading），或服务正忙（service_busy）。带 Retry-After 时按它退避。