JSON 输出

转录与模型使用稳定、明确的 JSON 契约。

概览

地址与鉴权见快速开始。转录、对齐和分句沿用桌面端与 CLI 的结构化文稿约定；模型与兼容 API 各自遵循对应的响应契约，不强行共用同一种 JSON 格式。

POST /v1/audio/transcriptions (verbose_json) → {task:"transcribe", duration, language?, text, segments[], usage}
POST /v1/audio/alignments      →  {task:"align", duration, language?, text, segments[], normalization_regions?, usage}
POST /v1/text/segmentations    →  {task:"segment", text, segments[]}
POST /v1/text/normalizations   →  {task:"normalize", model, language, mode, text, alternatives[]}
GET  /v1/models                →  {object:"list", data[]}

POST /v1/audio/transcriptions

使用 Multipart 表单上传。response_format 支持 json、verbose_json、text 与 diarized_json；verbose_json 和 diarized_json 可通过 timestamp_granularities[] 请求词级或片段级时间戳。流式输出使用 JSON 模式 SSE，不支持 text 或 diarized_json，且仅桌面网关支持；Headless 服务对 stream=true 返回 400。

各输出模式的结构不同：json 返回 {text,start,duration,language?,usage}；verbose_json 返回 {task:"transcribe",duration,language?,text,segments?,usage}；diarized_json 返回 {text,segments,usage}，段落带 type:"transcript.text.segment"，ID 为 "seg_0" 等字符串，说话人标签可能为 null。下方示例展示 verbose_json，并非所有模式的统一结构。各模式的完整请求与返回见转录示例。

curl "$EDGESPEAK_BASE_URL/audio/transcriptions" \
  -F file=@meeting.m4a \
  -F model="EdgeSpeak/Lattice-2" \
  -F response_format=verbose_json \
  -F "timestamp_granularities[]=word"

输出示例（节选）：

{
  "task": "transcribe",
  "duration": 19.69,
  "language": "en",
  "text": "EdgeSpeak AI is a high-performance engine ...",
  "segments": [
    {
      "id": 0,
      "start": 0.0,
      "end": 6.44,
      "text": "EdgeSpeak AI is a high-performance engine designed for ...",
      "words": [
        { "word": "EdgeSpeak", "start": 0.22, "end": 0.64, "score": 0.991 }
      ]
    }
  ],
  "usage": { "type": "duration", "seconds": 19.69 }
}

POST /v1/audio/alignments

强制对齐：提供文稿并获取词级时间。请求参数见对齐参数。完整请求与响应示例见强制对齐。响应可包含归一化后的语言代码 language，score 为 [0, 1] 置信度。文本归一化可将书面形式转换成实际读法；normalization_regions 给出区域与候选，词级 provenance 含 source_start_byte、source_end_byte、normalizations[]，偏移相对于原始 UTF-8 文稿。

curl "$EDGESPEAK_BASE_URL/audio/alignments" \
  -F model="EdgeSpeak/Lattice-2" \
  -F file=@meeting.m4a \
  -F text="EdgeSpeak is a high performance engine ..."

输出示例（节选）：

{
  "task": "align",
  "duration": 19.6909375,
  "text": "EdgeSpeak is a high performance engine ...",
  "segments": [
    {
      "id": 0,
      "start": 0.22,
      "end": 19.52,
      "text": "EdgeSpeak is a high performance engine ...",
      "words": [
        { "word": "EdgeSpeak", "start": 0.22, "end": 1.04, "score": 0.8463 }
      ]
    }
  ],
  "usage": { "type": "duration", "seconds": 19.6909375 }
}

POST /v1/text/segmentations

支持语义分句。JSON 请求体中，纯文本传入 text，带时间戳传入 segments[]。speaker、start 和 end 仅在输入携带时返回。指定 paragraph_threshold 后，segments[] 每项对应一个段落，顶层 text 用 \n\n（空行）连接段落。可选参数与段落模式限制见分句与段落切分。

curl "$EDGESPEAK_BASE_URL/text/segmentations" \
  -H "Content-Type: application/json" \
  -d '{"text": "EdgeSpeak is a high-performance engine designed for the structuring of audio and video content assets. It runs entirely on local compute, ensuring your data security."}'

输出示例（节选）：

{
  "task": "segment",
  "text": "EdgeSpeak is a high-performance engine ... It runs entirely on local compute ...",
  "segments": [
    { "text": "EdgeSpeak is a high-performance engine designed for the structuring of audio and video content assets." },
    { "text": "It runs entirely on local compute, ensuring your data security." }
  ]
}

POST /v1/text/normalizations

文本归一化使用独立的响应契约。不要将 spans[] 中的 UTF-8 字节偏移当作字符索引。

字段	说明
`text`	顶层字段，保留输入原文。
`alternatives[].rank`	候选序号，`0` 为首选。
`alternatives[].text`	该候选的整段读法或书面形式。
`alternatives[].spans[]`	包含 `start_byte`、`end_byte`、`class`、`source`、`output`。

候选读法与排序取决于语言、类别和归一化规则。完整 TN / ITN 请求与响应示例见文本处理。

GET /v1/models

列出可用模型。每条模型记录提供 supported_endpoints、features、execution_location 与 default_for。模型 ID 以运行时返回的值为准，调用方应直接读取响应，不要自行拼接或硬编码。

curl "$EDGESPEAK_BASE_URL/models"

输出示例（节选）：

{
  "object": "list",
  "data": [
    {
      "id": "EdgeSpeak/Lattice-2-Flash",
      "object": "model",
      "created": 0,
      "owned_by": "EdgeSpeak",
      "supported_endpoints": ["/v1/audio/transcriptions"],
      "features": [],
      "execution_location": "local",
      "default_for": ["/v1/audio/transcriptions"]
    },
    {
      "id": "Qwen/Qwen3.5-4B",
      "object": "model",
      "created": 0,
      "owned_by": "EdgeSpeak",
      "supported_endpoints": ["/v1/chat/completions", "/v1/responses", "/v1/messages", "/v1/tokenize"],
      "features": ["reasoning", "vision", "tool_calling"],
      "execution_location": "local",
      "default_for": []
    }
  ]
}

字段语义

语音文稿中的时间单位均为秒。segments[] 常见元素为 {id, start, end, text, words?}；词级时间戳位于 segments[].words，单个词条目为 {word, start, end, score?}，其中 score 为 [0, 1] 置信度。转录和对齐通常以 {"type": "duration", "seconds": …} 表示 usage；其他 API 使用各自契约。可选键可能省略，JSON 键序不作保证，请按键名取值。

译文

桌面端导出的结构化文稿会把译文和原文放在一起。只要这份结果没被翻译过，下面这些键一个都不会写出来，导出字节与没有翻译功能之前完全一致。

文档级：

键	类型	缺省时
`target_langs`	`string[]`，有序唯一，BCP-47 小写标签	没选目标语言时不落键
`speaker_source`	`"transcript"`、`"script"` 或 `"none"`	不落键，按 `"transcript"` 读
`translation_settings_revision`	`string`	没有翻译要求时不落键

哪些语言是用户选的，target_langs 是唯一来源。不要用各段 translations 的键求并集反推：某个语言一段都还没翻时并集里没有它，这个语言就悄悄消失了。

段级：

键	类型	缺省时
`translations`	以 BCP-47 小写标签为键的对象，值是一个译文单元	该段没有译文时不落键
`no_translate`	`boolean`	不落键，即 `false`

target_langs 里列出的语言，在某一段的 translations 下仍可能没有条目。每个译文单元都要当可选值处理，取用前先判空。标了 no_translate 的段落不带 translations。

每个译文单元：

字段	类型	说明
`text`	`string`	失败的单元是空串
`status`	`string`，可选	派生值快照：`translated`、`reviewed`、`stale` 或 `failed`
`source_revision`	`string`	译文对应那一版原文的指纹，空串表示未知
`settings_revision`	`string`	翻译时生效的翻译要求指纹，空串表示未知
`reviewed`	`boolean`	人工确认过译文即为 true
`updated_at`	`string`	ISO 8601，空串表示未知
`error_code`	`string`，可选	稳定的 snake_case 错误码，例如 `translation_request_failed`

status 是 App 派生值的快照，不是持久状态；原文或翻译要求一变，它立刻就会失效。读回方应按 source_revision、settings_revision 和 error_code 对当前文档重算，不要采信写出来的那个值。

输出示例（节选；revision 值是不透明指纹）：

{
  "language": "en",
  "target_langs": ["ja", "zh-hans"],
  "speaker_source": "transcript",
  "translation_settings_revision": "s3f9c1d4",
  "duration": 19.69,
  "num_segments": 2,
  "segments": [
    {
      "id": "seg_000",
      "text": "EdgeSpeak AI is a high-performance engine ...",
      "start": 0.0,
      "end": 6.44,
      "translations": {
        "ja": {
          "text": "EdgeSpeak AI は高性能なエンジンです ...",
          "status": "reviewed",
          "source_revision": "r91b0c27",
          "settings_revision": "s3f9c1d4",
          "reviewed": true,
          "updated_at": "2026-09-13T08:21:04Z"
        },
        "zh-hans": {
          "text": "EdgeSpeak AI 是一款高性能引擎 ...",
          "status": "translated",
          "source_revision": "r91b0c27",
          "settings_revision": "s3f9c1d4",
          "reviewed": false,
          "updated_at": "2026-09-13T08:21:04Z"
        }
      }
    },
    {
      "id": "seg_001",
      "text": "It runs entirely on your device ...",
      "start": 6.44,
      "end": 11.02,
      "translations": {
        "ja": {
          "text": "",
          "status": "failed",
          "source_revision": "r4d8ae13",
          "settings_revision": "s3f9c1d4",
          "reviewed": false,
          "updated_at": "2026-09-13T08:21:06Z",
          "error_code": "translation_request_failed"
        },
        "zh-hans": {
          "text": "它完全在你的设备上运行 ...",
          "status": "stale",
          "source_revision": "r2c07f5a",
          "settings_revision": "s3f9c1d4",
          "reviewed": false,
          "updated_at": "2026-09-13T08:19:52Z"
        }
      }
    }
  ]
}

旧的单语言形状。 多语言翻译之前导出的文件用文档级 target_lang 配 segments[].translation，两者都已废弃。两种形状不会出现在同一个文件里，现在写出的一律是多语言形状。旧文件在读入时迁移：标签归一成 BCP-47 小写，段级标签优先于文档级，每条译文变成一个 source_revision、settings_revision 和 updated_at 都为空串的单元。这三个空指纹是有意为之：旧文件从没记录译文对应哪一版原文，于是该单元会被判成待更新，而不是当前有效。两级都没有标签时，旧字段原样保留，不猜一个语言塞进去。