← API 接入指南与教程

完成第一次文档翻译

把一份 Word 文档翻译为德语,先查看报价,再授权执行并下载结果。使用下载包里的 Node.js 客户端即可调用公开 HTTP API,需要 Node.js 22+,无需安装 npm 包。

1. 配置 API 密钥

在 Skills / API 页面下载并解压 Skill。登录本站,从头像菜单的 API keys 创建 read、write 密钥,保存在环境变量中,不要写进脚本或聊天。

export SIMPLIFYAI_API_URL=https://simplifyai.cn/api/v1
# 通过自己的环境或密钥管理工具设置 SIMPLIFYAI_API_KEY。
node simplifyai-translate/scripts/cli.mjs config
node simplifyai-translate/scripts/cli.mjs capabilities

查看 capabilities 中当前格式、语言、模型和 formats[format].analysis_credits。本例使用 1 点分析上限;若公布价格更高,先取得增加预算的授权。

2. 上传并创建分析任务

在解压目录旁保存 first-translation.mjs,把输入文件放到同目录。示例接受当前公布的分析费在 1 点以内;成功分析会扣费,尚未授权翻译执行。

import { Client, translate } from './simplifyai-translate/scripts/client.mjs';
const client = new Client({
  url: process.env.SIMPLIFYAI_API_URL,
  key: process.env.SIMPLIFYAI_API_KEY,
});
const result = await translate(client, {
  file: './manual.docx', to: 'de',
  analysisBudget: '1',
});
console.log(JSON.stringify(result, null, 2));
node first-translation.mjs

客户端依次调用 POST /uploads、PUT 上传地址、POST /uploads/{id}/complete、POST /jobs。任务创建的核心请求如下,document_id 来自完成上传的响应。

{"document_id":"<document_id>","client_reference":"manual-de-001","options":{"target_lang":"de"}}

客户端根据 API 根地址、文件内容、operation、选项和两项上限算出 client_reference。任务仍在运行时,用相同命令再执行一次,或继续查询原任务。文件、选项或预算变了就是新任务。只有有意再跑一次时才自己指定 client_reference。

HTTP 最简示例省略分析上限,表示接受当前分析价格;上方客户端示例则明确把分析费限制为 1 点。确认执行时,HTTP 可发送空对象 {} 来接受已查看的固定报价;CLI 的 --max-credits 可选。

不提供执行上限时,付费报价等待确认,零执行报价自动执行。CLI 的分析与确认上限均可省略:省略分析上限接受当前分析费;运行 jobs confirm JOB_ID 不带上限表示接受固定报价。

3. 查看报价并确认

将下面的 JOB_ID 换成返回的 job.id。等待到 awaiting_intervention 后,查看 price、required_action 和 billing。可用 analysis 命令查看术语或待译句段。

node simplifyai-translate/scripts/cli.mjs jobs get JOB_ID
node simplifyai-translate/scripts/cli.mjs jobs analysis JOB_ID

确认执行预算后再运行以下命令。本例授权最多 10 点执行费,分析费另计;这不是保证实际报价为 10 点。

node simplifyai-translate/scripts/cli.mjs jobs confirm JOB_ID --max-credits 10
node simplifyai-translate/scripts/cli.mjs jobs wait JOB_ID

对应 HTTP 接口为 POST /jobs/{id}/confirmation,请求为 {}。超预算时先停止,不自行抬高上限。若还在运行,继续 wait,不要再次创建。

4. 下载与检查

completed 后按 result.filename 的真实扩展名指定新路径。本例输入 DOCX,所以下载为 DOCX。

node simplifyai-translate/scripts/cli.mjs jobs download JOB_ID --output manual.de.docx

下载命令处理官网代理前缀与签名跳转,不向外部存储转发 API 密钥,也不覆盖现有文件。检查译文、数字和版面,并查看 billing.analysis_charged 与 billing.charged;charged 是包含分析费的总已扣金额,不能再把两者相加。

遇到错误时

402 表示创建时余额不足,或 API key 的每日/总上限已满(api_key_limit_exceeded)。功能任务余额不足会暂停而不是拒绝。409 可能是预算超限或同一引用请求不同;429 按 Retry-After 等待。next_cursor 原样传回。保留 Job ID 和 request_id。失败任务的 error.retryable 说明能不能用新引用重试;分析费已经记在 billing 里。只有 queued 或 awaiting_intervention 的任务可取消,成功分析的费用仍保留。

下一步:使用术语库和记忆库。