在鸿渐里调用 LingoFlow：一条 Key 跑通意群翻译与配音

LingoFlow 是异步工作流（提交作业 → 轮询状态 → 取结果），和同步的 chat 接口形态不同。鸿渐把它作为服务暴露在独立命名空间下，鉴权、配额、审计全部复用鸿渐的 API Key。

1. 为什么是异步

一次作业要经历：意群切分 → 逐块翻译 → 语音合成 → 时间轴对齐 → 组装。几秒到几分钟不等，所以接口返回 202 + job_id，由你轮询（或订阅 SSE）。

sequenceDiagram
  participant C as 你的应用
  participant H as hugen.tydash.net
  participant L as LingoFlow
  C->>H: POST /v1/lingoflow/jobs (sk-hj-…)
  H->>H: 校验 Key / 配额 / 封禁
  H->>L: 以服务身份提交（无需你的 LingoFlow 账号）
  L-->>H: 202 {job_id}
  H-->>C: 202 {job_id}
  loop 轮询
    C->>H: GET /v1/lingoflow/jobs/{job_id}
    H-->>C: {status, stage, progress, result?}
  end

2. 先估算，再提交

curl -X POST https://hugen.tydash.net/v1/lingoflow/estimate \
  -H "Authorization: Bearer $HUGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"The quick brown fox jumps over the lazy dog.","options":{"audio":true}}'

返回 {chars, credits, audio_minutes_est, available, allowed}。 allowed=false 时 reason 会说明原因（超长、额度不足、并发上限）。

3. 提交作业

curl -X POST https://hugen.tydash.net/v1/lingoflow/jobs \
  -H "Authorization: Bearer $HUGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "demo",
    "content": "你想学习的原文……",
    "source_language": "auto",
    "target_language": "zh-CN",
    "options": {"audio": true, "lgf": false}
  }'

{"job_id":"job_ab12…","article_id":"…","status":"pending","estimate":{"credits":0.1,"chars":57}}

4. 轮询状态

curl https://hugen.tydash.net/v1/lingoflow/jobs/job_ab12… \
  -H "Authorization: Bearer $HUGEN_API_KEY"

关键字段：

字段	含义
`status`	`pending` / `running` / `succeeded` / `failed` / `canceled`
`stage`	`queued` → `plan` → `tts` → `align` → `assemble` → `done`
`progress`	0–100
`result.chunks_count`	意群块数量
`result.has_audio`	是否产出音频
`error_code` / `error_message`	失败原因（`LLM_ERROR` / `TTS_ERROR` / …）

5. 失败重试的姿势

retryable=true → 指数退避后重试同一 job_id 所在的新作业（当前 API 不支持原地重试）。
LLM_ERROR 多为上游模型不可用或额度耗尽；TTS_ERROR 多为语音服务配额。
作业是幂等的：重复提交相同内容会产生新作业，请用你自己的业务 id 做去重。

6. 身份与计费

你不需要 LingoFlow 账号：鸿渐用服务身份代你提交，并按你的 Key 归属计费。
同一个鸿渐用户始终映射到同一个 LingoFlow 主体，便于额度与审计对齐。
想直接用 LingoFlow 的完整 Web 界面：https://app.tydash.net/lingoflow（同一套 TyDash 账号登录）。

计费与额度：两种模式

按次计费（默认） —— 未订阅 LingoFlow 套餐时，每个作业按 estimate 返回的 credits 折算人民币，提交时冻结、成功结算、作业失败自动退款（记一笔 CREDIT）。

订阅含额度 —— 购买「LingoFlow Studio」后，该组织在额度内不再按次扣费：

项	说明
额度	每月 120 个作业（按 UTC 月初重置）
扣费	额度内 0 元（仍会记录用量，便于对账与额度统计）
超额	返回 429，不会静默扣钱

// 超额时的响应（实测）
HTTP/1.1 429 Too Many Requests
{"error":{"message":"本月作业额度已用完（8/8），请下月再试或升级套餐",
          "type":"job_quota_exceeded","retryable":false,"used":8,"limit":8}}

注意 retryable: false —— 额度用完重试没有意义，等下个月或升级套餐。（对照：重试与幂等里讲了哪些错误该重试。）