合作方 API 文档

Novo Translator B2B API

Novo Translator 把长篇小说翻译封装成异步任务。合作方通过 action 创建任务，轮询状态，然后下载结果。同一套任务模型支持字符/Token 估算、术语抽取、预览生成和全文翻译。

Base URL

https://xsfyj.com/api/b2b/v1

OpenAPI JSON

/api/b2b/v1/openapi.json

版本

1.0.0-draft

快速接入

1把分配给你的 API key 放在服务端，并以 Bearer token 发送。
2先调用 GET /usage 确认 Key 可用、余额和 RPM 限制。
3报价前用 action=token_estimate 或 action=preview_metadata 做字符/Token/元数据评估。
4需要预览时，用 action=glossary_extraction 或 action=translation 搭配 char_limit。
5正式全文任务不要传 char_limit；上传文件时传 estimated_chars 用于预扣额度校验。
6轮询 GET /tasks/{task_id}；任务完成后用 GET /tasks/{task_id}/download 下载文件。

鉴权和账号映射

每个 API key 都映射到一个 Novo Translator 托管合作方账号。计费、余额和限速都由这个映射账号控制，所以 API 调用不需要浏览器登录。

请求头	Authorization	Bearer nt_live_xxxxxxxxxxxxxxxxx
额度单位	1 credit	处理 1 个源文本字符
试点余额	按套餐配置	用 /usage 查询当前余额。示例试点额度：1000000 credits。
限速	按 Key 配置	用 /usage 查询当前 RPM。

action 用法

目标	action	结果
全文翻译	translation	翻译完整文本或上传文件。
翻译预览	preview_translation	通过 char_limit 翻译开头样本。
成本估算	token_estimate	返回系统侧字符/Token 估算，用于报价。
术语抽取	glossary_extraction	抽取人名、设定名、专有术语和建议译名。
元数据预览	preview_metadata	不跑全文任务，只识别语言和源文件元数据。

用 char_limit 做预览和范围控制

char_limit 决定本次任务处理多少源文本。合作方可以用它生成预览，或在不处理完整文件的情况下给客户报价。

translation 不传 char_limit 表示全文翻译；传 char_limit 表示只翻译指定开头范围。
glossary_extraction 传 char_limit 时，只抽取指定开头范围内的术语。
token_estimate 和 preview_metadata 也可以传 char_limit，用于局部估算。
上传文件时，如果没有 char_limit，需要提供 estimated_chars，让网关先做余额校验。

合作方自带术语

glossary 以 JSON object 传入，glossary_strategy 决定自带术语和系统抽取术语冲突时如何处理。

merge

默认策略

合并系统抽取术语和合作方术语；冲突时合作方术语优先。

override

权威术语

冲突时以合作方术语为准。

append

补充提示

只在不冲突时追加合作方术语。

none

不用自带术语

忽略传入术语。

查询余额和 RPM

curl https://xsfyj.com/api/b2b/v1/usage \
  -H "Authorization: Bearer nt_live_xxxxxxxxxxxxxxxxx"

{
  "success": true,
  "data": {
    "api_key_prefix": "nt_live_ab12",
    "balance_credits": 10000000,
    "period_used_credits": 0,
    "period_start": "2026-06-01T00:00:00Z",
    "period_end": null,
    "rate_limit_per_minute": 120
  }
}

核心操作示例

1. 上传文件，统计字符并估算成本

报价或创建全文任务前，使用 action=token_estimate。试点阶段上传文件时，estimated_chars 用于预付额度校验；任务完成后会返回系统侧字符数、Token 估算等统计。

继续轮询 https://xsfyj.com/api/b2b/v1/tasks/{task_id}。估算任务完成后，可能返回 total_characters、estimated_tokens、detected_language 和 estimated credits 等字段，具体取决于文件类型。

Request

curl https://xsfyj.com/api/b2b/v1/tasks \
  -H "Authorization: Bearer nt_live_xxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: partner-estimate-001" \
  -F "action=token_estimate" \
  -F "target_lang=en" \
  -F "estimated_chars=120000" \
  -F "[email protected]"

Typical response

{
  "success": true,
  "data": {
    "task_id": "TSK_EST_01HV8W...",
    "status": "pending",
    "action": "token_estimate",
    "file_name": "novel.txt",
    "target_lang": "en",
    "char_count": 120000,
    "estimated_credits": 120000,
    "created_at": "2026-06-16T10:30:00Z"
  }
}

2. 创建术语抽取任务

使用 action=glossary_extraction 创建只抽术语的任务。需要预览或局部报价时，传 char_limit 只处理开头范围。

Request

curl https://xsfyj.com/api/b2b/v1/tasks \
  -H "Authorization: Bearer nt_live_xxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: partner-glossary-001" \
  -F "action=glossary_extraction" \
  -F "target_lang=en" \
  -F "char_limit=20000" \
  -F "[email protected]"

Typical response

{
  "success": true,
  "data": {
    "task_id": "TSK_GLO_01HV8W...",
    "action": "glossary_extraction",
    "status": "completed",
    "progress": 1,
    "terms": [
      { "source": "玄天宗", "target": "Xuantian Sect", "confidence": 0.93 },
      { "source": "灵石", "target": "spirit stone", "confidence": 0.9 }
    ],
    "char_count": 20000,
    "credits_charged": 20000
  }
}

3. 创建全文翻译或预览翻译任务

正式翻译使用 action=translation。全文任务不传 char_limit；如果只想翻译开头范围作为预览，则传 char_limit。

如果要用同一个任务类型生成翻译预览，把 estimated_chars 换成 char_limit，例如 char_limit=12000。

Request

curl https://xsfyj.com/api/b2b/v1/tasks \
  -H "Authorization: Bearer nt_live_xxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: partner-file-001" \
  -F "action=translation" \
  -F "target_lang=en" \
  -F "glossary_strategy=merge" \
  -F "estimated_chars=120000" \
  -F "[email protected]" \
  -F 'glossary={"玄天宗":"Xuantian Sect"}'

Typical response

{
  "success": true,
  "data": {
    "task_id": "TSK_01HV8W...",
    "status": "pending",
    "action": "translation",
    "file_name": "novel.txt",
    "source_lang": "auto",
    "target_lang": "en",
    "char_count": 120000,
    "estimated_credits": 120000,
    "created_at": "2026-06-16T10:30:00Z"
  }
}

4. 处理前查看元数据

合作方需要先了解语言、标题/文件信息或源文本统计时，使用 action=preview_metadata，再决定是否继续执行下游任务。

Request

curl https://xsfyj.com/api/b2b/v1/tasks \
  -H "Authorization: Bearer nt_live_xxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: partner-metadata-001" \
  -F "action=preview_metadata" \
  -F "target_lang=en" \
  -F "char_limit=8000" \
  -F "[email protected]"

Typical response

{
  "success": true,
  "data": {
    "task_id": "TSK_META_01HV8W...",
    "action": "preview_metadata",
    "status": "completed",
    "progress": 1,
    "source_lang": "zh",
    "char_count": 8000,
    "detected_language": "zh",
    "metadata": {
      "file_name": "novel.txt",
      "sample_characters": 8000
    }
  }
}

轮询任务状态

任务是异步执行的。普通任务建议每 5-15 秒轮询一次，长文件任务要退避。任务完成后，轻量 action 可能直接返回结果；文件型任务会返回可下载文件信息。

curl https://xsfyj.com/api/b2b/v1/tasks/{task_id} \
  -H "Authorization: Bearer nt_live_xxxxxxxxxxxxxxxxx"

{
  "success": true,
  "data": {
    "task_id": "TSK_01HV8W...",
    "action": "translation",
    "status": "completed",
    "progress": 1,
    "stage": "completed",
    "file_name": "novel.txt",
    "source_lang": "zh",
    "target_lang": "en",
    "char_count": 120000,
    "credits_charged": 120000,
    "download_files": [
      {
        "file_id": "translated",
        "file_name": "novel_translated.txt",
        "url": "/api/tasks/download-file/TSK_01HV8W...",
        "file_size": 348200,
        "type": "translated"
      }
    ]
  }
}

下载完成结果

curl https://xsfyj.com/api/b2b/v1/tasks/{task_id}/download \
  -H "Authorization: Bearer nt_live_xxxxxxxxxxxxxxxxx"

{
  "success": true,
  "data": {
    "download_url": "https://...",
    "expires_in": 3600,
    "file_name": "novel_translated.txt",
    "file_size": 348200
  }
}

错误和重试

HTTP	Code	处理方式
400	BAD_REQUEST	修正参数、输入源或 glossary JSON。
401	UNAUTHORIZED	检查 Bearer API key；已撤销或未知 Key 不能访问任务。
402	PAYMENT_REQUIRED	给映射账号充值，或降低 char_limit 后重试。
409	IDEMPOTENCY_CONFLICT	同一个 Idempotency-Key 只能用于同一个逻辑请求。
429	RATE_LIMITED	按 Retry-After 等待，并使用指数退避。

合作方接入检查表

API key 只放在服务端，不要暴露给浏览器或移动端客户端。
所有可能重试的创建任务请求都带 Idempotency-Key。
把 Novo task_id 和你自己的 external job id 一起保存到 metadata。
向终端客户计费前，先用 token_estimate 和 char_limit 预览评估成本。
大批量任务前先调用 /usage 确认余额和 RPM。
不要依赖内部模型名、prompt 模板或 pipeline 步骤名。