Spark-Audio-1.0-Preview 短音频先跑通、长音频再拆段，输入长度决定处理路径

遇到 Spark-Audio-1.0-Preview 这类音频接口，业务侧最容易踩的坑是拿一段十几分钟的会议录音一次性提交，超时或失败后再回头拆，结果无从判断问题出在音频本身还是输入太长。更稳妥的做法是先固定一段短音频把请求、鉴权和返回结构跑通，形成可回看的基线；长音频再交给 ffmpeg 切片，逐段调用、逐段记录，最后按时间戳偏移拼接。整段提交和切片提交不是优劣关系，而是由输入长度、超时容忍度和尾部对齐成本共同决定的路径选择。

短音频先跑通的目的是确认请求字段、状态码和返回结构可用，属于接入验证，不代表识别质量结论。长音频切片的默认切入点通常落在静音或停顿处，切片后每段的起始时间必须显式记录，拼接时按起始时间排序并做时间戳偏移，同时去掉相邻片段首尾的重复文本。如果接口本身支持较长的输入上限，且网络稳定、超时余量充足，整段提交仍然可以保留为优先路径；只有超时、返回结构异常或长度被拒时，才需要回退到切片流程。

用一段短音频建立最小成功基线

选一段可以公开、内容简单、时长大致在几秒到几十秒之间的短音频，比如自己录的一段朗读。先把鉴权和请求跑通，重点看三件事：请求字段名是否与接口文档一致、返回状态码是否是成功态、返回结构里有没有文本字段和时间戳字段。下面是一个通用接入骨架，端点、字段名和鉴权头都需要按官方文档替换，未确认的字段用占位符。

curl -X POST "https://<api-host>/v1/audio/transcriptions" \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@short_sample.wav" \
  -F "model=<MODEL_NAME>" \
  -F "response_format=<json|verbose_json>" \
  -o baseline_resp.json -w "%{http_code} %{time_total}\n"

Python 侧可以用 requests 走同一份参数，把状态码、耗时和返回体一起写进基线记录表。表格字段建议固定为：音频文件名、时长、请求字段组合、状态码、返回体长度、耗时、返回结构里出现的键名。这张基线表不是性能报告，而是后续切片结果出现异常时的对照物——切片调用返回结构如果和基线对不上，优先怀疑参数或音频格式，而不是先怀疑模型。

用 ffmpeg 把长音频切成带时间戳的片段

长音频进入可测试粒度的手段是切片。切片有两个基本要求：文件名里带上起始时间和序号，避免后续排序靠目录顺序；每段切完后用 ffprobe 复核实际时长，避免首尾片段过短或为空。

Spark-Audio-1.0-Preview 短音频先跑通、长音频再拆段，输入长度决定处理路径

# 按固定时长切片，起点信息写进文件名
ffmpeg -i long_audio.wav \
  -f segment -segment_time 60 -reset_timestamps 0 \
  -c copy "seg_%04d.wav"

# 复核每段时长
for f in seg_*.wav; do
  ffprobe -v error -show_entries format=duration \
    -of default=noprint_wrappers=1:nokey=1 "$f"
done

按固定时长切最简单，但切点可能落在词中间，导致相邻两段各出现半句话。如果音频本身有停顿，可以先尝试用静音检测切分，让切点落在停顿区域，代价是每段长度不均匀，需要额外记录每段真实起止时间。无论用哪种方式，每段的起始偏移都要单独落盘，可以按 <序号, 起始秒, 时长> 写成一行，后续拼接只认这张表，不认文件名以外的任何推测。

逐段调用并记录每段返回

用同一个占位符函数循环提交切片，每次记录四件事：状态码、返回文本长度、耗时、该段对应的起始偏移。这一步只做观测，不评价识别准确率，因为切片本身会破坏上下文，短片段的结果好坏不能直接外推。

def call_one(path, start_offset):
    r = transcribe_api(path)  # 占位：按官方文档实现
    return {
        "file": path,
        "start_offset": start_offset,
        "status": r.status_code,
        "text_len": len(r.json().get("text", "")),
        "elapsed": r.elapsed.total_seconds(),
        "text": r.json().get("text", ""),
    }

records = []
for idx, (path, start, dur) in enumerate(segments):
    records.append(call_one(path, start))

逐段记录的价值在于可观察差异：如果整段调用是超时或直接报错，而切片后每段都返回成功状态，说明限制很可能来自输入长度或超时阈值，而不是音频内容本身。反过来，如果切片后某些段稳定失败，就要回头看那段音频的格式、采样率或时长是否异常。所有判断都基于状态码和返回体，不要靠主观听感下结论。

拼接结果时处理时间戳偏移和重复边界

拼接不是简单把文本连起来。正确的顺序是先按起始偏移排序，再把每段文本里的时间戳统一加上该段的偏移，最后处理相邻段落的重复边界——固定时长切片时，切点两侧常常出现重复的字词或半句话。

records.sort(key=lambda r: r["start_offset"])

merged = []
for r in records:
    text = r["text"].strip()
    if merged and merged[-1]["tail"] == text[:len(merged[-1]["tail"])]:
        text = text[len(merged[-1]["tail"]):]
    merged.append({"start": r["start_offset"], "text": text})

final = "".join(m["text"] for m in merged)

时间戳偏移的原则是每段内部保持相对时间，输出时统一加上起始偏移。重复边界的处理更保守一些：可以先按最长公共前缀做截断，再人工抽查几处切点。如果接口返回的是带词级时间戳的结构，合并时以词级时间戳去重通常比按文本前缀更稳，但需要先确认返回结构里确实有词级字段。

整理输入长度处理路径决策表

下面四类场景覆盖了多数接入初期的判断需求。表里的验证记录指的是你能自己跑出来、能回看的东西，不是别人给的经验值。

短音频：推荐路径是直接整段提交，不做切片；验证记录为基线表里的状态码和返回结构键名是否稳定；风险边界是短音频成功不能说明长音频也能成功。
长音频：推荐路径是先按停顿或固定时长切片，逐段调用后再拼接；验证记录为每段时长、每段状态码、每条起始偏移；风险边界是切点造成的上下文丢失，可能在专有名词和连续语句上显现。
网络不稳定：推荐路径是保持切片粒度、增加单段重试记录，不建议在一次请求里堆长音频；验证记录为失败段的序号和重试后的状态码；风险边界是重试可能放大重复提交，需要在记录里保留原始请求标识。
返回超时：推荐路径是先确认是否命中长度上限或超时阈值，再决定整段重试还是回退切片；验证记录为超时发生时的音频时长和耗时字段；风险边界是超时原因可能来自服务端排队，未必是长度问题，需要结合同长度音频的多次结果再判断。

把这张表和前面的基线表、切片记录放在同一个目录里，后续接口版本更新或音频来源变化时，先重跑一遍短音频基线，再对照切片记录看差异出现在哪一步。接入阶段的重点不是一次调对，而是每一步都留下可核对的痕迹。