API 接入指南与教程
按场景选择教程
上传文件并创建任务,查看报价后再确认执行。完成后可下载文档、报告或素材包。
API 地址与鉴权
API 根地址为 https://simplifyai.cn/api/v1。使用本站创建的 API key 和账户点数。
登录网站,从头像菜单打开 API keys,创建 read 和 write 权限的密钥。完整密钥只显示一次,保存在运行环境的 SIMPLIFYAI_API_KEY 中。
export SIMPLIFYAI_API_URL=https://simplifyai.cn/api/v1
curl "$SIMPLIFYAI_API_URL/capabilities"
curl "$SIMPLIFYAI_API_URL/jobs" \
-H "Authorization: Bearer $SIMPLIFYAI_API_KEY"
GET /capabilities 公布格式、限制、模型、语言、操作和分析价格。该接口与 GET /openapi.json 可以直接读取。其他请求需要 Bearer 密钥。 formats[format]: extensions, limits, analysis_credits; operations[operation]: formats, analysis_formats.
上传文件
POST /uploads 接受文件名和实际字节数。服务端从文件名识别格式,并校验文件字节。
{"filename":"catalog.pdf","size_bytes":12345}
按响应中 transfer 的 method、url 和 headers 上传原始文件字节。然后调用 POST /uploads/{id}/complete,取得 document_id。
响应中的 /api/v1/... 路径可直接使用本站域名请求。Markdown 文件使用 .md 或 .markdown 扩展名。
翻译与预算
向 POST /jobs 提交以下 JSON,替换其中的示例 ID。
{
"document_id": "<document_id>",
"client_reference": "catalog-ja-001",
"options": {
"target_lang": "ja"
}
}
省略 operation 时默认翻译。成功分析按公布的固定金额收费。max_analysis_credits 限制分析费,省略则接受当前分析价格。
轮询 GET /jobs/{id}。进入 awaiting_intervention 时查看 price.credits,确认后向 POST /jobs/{id}/confirmation 提交。
{}
执行报价为零时自动执行。付费执行等待确认;创建时提供 max_credits,则可在上限内自动执行。分析和执行分别计费。确认时提交 {} 表示接受固定报价,也可附带 max_credits 限制金额。
确认接口支持不带请求体,或发送 {},两者都接受已查看的固定报价。review 中只提交修改的术语或上下文字段,其他内容保留;未提交的术语 status 也保留。清空上下文字段用空字符串。非空 manual_glossary 按词条合并,{} 清空手工映射;库选择和排除列表仍表示完整选择,空列表清空。
任务目录
所有任务共用 POST /jobs。capabilities 中的 operations[operation].formats 声明输入格式。
| operation | 用途 | 主要结果 |
|---|---|---|
document.extract_markdown | 提取文本和图片 | Markdown 或 ZIP |
document.pdf_to_docx | PDF 转 Word | DOCX |
document.pdf_to_pptx | PDF 转 PowerPoint | PPTX |
document.markdown_to_docx | Markdown 排成 Word | DOCX |
document.convert_idml | InDesign 转 IDML | IDML |
document.export_pdf | 导出源文件 PDF | |
document.export_translated_pdf | 导出指定译文 PDF | |
document.export_thumbnails | InDesign 页面缩略图 | ZIP、清单 |
document.export_images | Illustrator 画板图片 | ZIP、清单 |
document.extract_assets | InDesign 链接素材提取 | ZIP、报告 |
document.preflight | InDesign 印前检查 | JSON 报告 |
document.pac_remediate | PDF 无障碍检查与修复 | 报告、修复后 PDF |
document.rebuild | 修订译文后重新生成 | 对应格式文件 |
PDF 转 Word 的请求示例如下。
{
"operation": "document.pdf_to_docx",
"document_id": "<document_id>",
"client_reference": "catalog-word-001"
}
省略执行上限时,付费任务等待确认,零执行报价自动执行。需要先读取页数的 Adobe 任务会先分析,使用同样的分析费和分析预算规则。执行失败会释放仍冻结的执行费用,成功完成的分析按公布规则收费。
Markdown 转 Word 可传 options.style,取值为 default、business、minimal、academic 或 tech。导出译文 PDF 时,通过 options.source_job_id 选择已完成的翻译或修订任务。
PDF 无障碍修复会先检查,再等待确认。GET /jobs/{id}/artifacts 此时可读取检查报告。确认可携带 pac 对象。
{"pac":{"document_language":"en"}}
检查报告的 inputs 提供需要补充文字的注释或图片 ID、页码及提示,可据此填写 pac.annotation_descriptions 或 pac.figure_alt_texts。其他验证参数见 OpenAPI。任务完成表示修复流程完成;是否达到无障碍标准请读取 purpose=verification,仍可能有需要人工处理的项目。
任务专用参数
每种 operation 都有独立的 options 定义。capabilities 的 operations[operation].options_schema 指向 OpenAPI 中对应的参数模型;与任务无关的字段会被拒绝。默认值无需重复提交。
| operation | options |
|---|---|
document.translate | target_lang; source_lang, model, glossary_ids, memory_ids, format_options |
document.extract_markdown | include_page_markers, include_page_chrome, layout_assist (PDF) |
document.pdf_to_docx | page_breaks, style, layout_assist |
document.markdown_to_docx | style |
document.rebuild | source_job_id、changes;可选 base_version_id |
document.export_translated_pdf | source_job_id |
document.pac_remediate | 确认阶段的 pac;创建 options 可省略 |
document.pdf_to_pptx, document.convert_idml, document.export_pdf, document.export_thumbnails, document.export_images, document.extract_assets, document.preflight | 无可调参数,省略 options |
PDF 转 Word:page_breaks 保留源页分页,style 选择文档样式(pdf_reflow/default/business/minimal/academic/tech),layout_assist 选择 off/llm/vlm,并受部署上限约束;省略时使用部署上限。模型版面辅助进入固定执行报价,需确认或预算授权后才运行。Markdown 提取的三个选项仅用于 PDF,版面辅助默认 off。
翻译 PDF 时,options.format_options.pdf 支持 output_format、translate_images,以及仅 Word 输出可用的 page_breaks、style、layout_assist。PDF 转 DOCX/PPTX 时,translate_images 同时控制转换后文件的图片翻译;扫描 PDF 仍可能需要 OCR 才能读取正文。
翻译格式参数写在 options.format_options 下,只提交输入格式对应的对象。未列出的格式不需要格式参数。
| 格式对象 | 可选字段与默认值 |
|---|---|
docx | translate_images=false;mirror_layout=false |
pptx | translate_images=false;mirror_layout=true |
xlsx | translate_hidden_sheets=false |
pdf | output_format=pdf;translate_images=true;mirror_layout 按输出格式取默认值;Word 输出另支持 page_breaks=false、style、layout_assist |
indd | typography_compensation=true |
ai | auto_fit=true、adjust_leading=true、adjust_tracking=true、min_font_scale_pct=70(1–100)、mirror_layout=true |
epub / image | 无需格式对象 |
mirror_layout 只控制几何换位,不控制文字方向。DOCX 默认关闭(只移动浮动对象),PPTX 和 AI 默认开启;它们仅在目标语言为 RTL 时镜像,不比较源语言方向。InDesign 自动按目标 RTL 镜像,没有公开镜像开关。PDF 输出为 PDF/PPTX 时默认开启,Word 时默认关闭:保留版面 PDF 在检测到的源文字方向与目标方向不同时镜像;转成 Word/PPTX 则遵循目标格式的 RTL 条件,显式 PDF 设置会传入。文字方向自动处理,重新生成继承源 Job 的格式选项。
{
"operation":"document.pdf_to_docx",
"document_id":"<document_id>",
"client_reference":"pdf-word-options-001",
"options":{"page_breaks":true,"style":"minimal","layout_assist":"off"}
}
术语库与现有记忆库
GET /glossaries 和 GET /memories 列出当前账号可用的个人及团队资源。列表包含 items 和 next_cursor,继续查询时传 cursor。条目可通过 /glossaries/{id}/entries 和 /memories/{id}/entries 查看。
创建翻译时选择库。
{
"document_id": "<document_id>",
"client_reference": "catalog-with-libraries-001",
"options": {
"target_lang": "de",
"glossary_ids": [
"<glossary_id>"
],
"memory_ids": [
"<memory_id>"
]
}
}
选中的库在确认时应用。确认时可通过 review.glossary_ids 和 review.memory_ids 改变选择,空数组清空选择。服务端保存本次任务的快照,后续库内容变化不会重写已开始的翻译。
POST /glossaries/resolve 预览语言对的术语映射,参数为 glossary_ids、source_lang、target_lang。POST /glossaries 可以创建个人术语库。
{
"name": "产品术语",
"entries": [
{
"translations": {
"en": "Product",
"de": "Produkt"
}
}
]
}
现有记忆库通过网页维护,API 提供发现、查询和翻译中的使用。
审阅并重新生成
翻译完成后,GET /jobs/{id}/translation/segments 返回句段 ID、原文、译文和 version_id。Agent 可以逐段检查术语、数字、单位和漏译。已完成 Job 的译文版本固定;分页时可携带 version_id 作显式校验。
将修改提交为独立任务。
{
"operation": "document.rebuild",
"client_reference": "catalog-review-001",
"options": {
"source_job_id": "<completed_translation_or_revision_job_id>",
"changes": [
{
"segment_id": "s_72",
"target": "修改后的译文"
}
]
}
}
源 Job 已确定文档和译文版本,无需重复提交。document_id 和 options.base_version_id 可作为显式校验。免费重新生成会自动执行;付费时等待确认,或按已授权的执行上限自动执行。
只提交有变化的句段,保留格式标记。服务端保存修订版本并重新生成,原任务的交付物继续保留。基准版本过旧或同一译文已有修订在执行时返回 409。重新生成按所需步骤计费。
默认只改 segment_id 对应的一处。需要同步修改整个复用组时,在该条 change 中增加 "scope":"group";服务端从该句段查找所选版本中的所有同组位置,无需提交原文或组 ID。句段响应中 reuse_count 表示整份版本中的复用处数,没有该字段表示一处。分组沿用已有格式标记,不把视觉文字相同但格式不同的句段强行合并。同一请求中,单处修改优先于组修改,与 changes 的顺序无关。组修改会覆盖组内已有的不同译文;需要保留的单处例外应一并提交。
下载与恢复
GET /jobs/{id}返回状态、阶段、进度、报价、账务和主结果。completed表示完成交付。result.content_url下载主结果。GET /jobs/{id}/artifacts列出可下载的文件和报告。POST /jobs/{id}/cancel取消排队或等待确认的任务。- 每次业务操作保存唯一
client_reference和返回的 Job ID。响应丢失后,重放同一请求取得同一任务。 GET /jobs?client_reference=...可以找回任务。建议每 5 到 30 秒查询一次进度。- 同一引用提交不同内容返回 409 client_reference_conflict。创建时余额不足返回 402。功能任务在报价后余额不足会暂停,required_action 为 insufficient_credits。API key 还可以设置每日上限和总上限。同步请求超限返回 402 api_key_limit_exceeded;后台冻结超限会把任务暂停为同名 required_action,调高上限后再次确认即可继续。超预算返回 409,限流返回 429。游标是不透明字符串,把 next_cursor 原样传回。失败任务带 error.code(timeout、service_unavailable 或 execution_failed)和 error.retryable。分析费已经记在 billing 里。
- 错误包含
error.code、message 和request_id,请保留请求 ID 和 Job ID。
progress 只返回公开 stage、可用时的 fraction(0–1)及页或句段计数。billing.charged 已包含 analysis_charged。交付物通过 role 和 purpose 区分用途;报告保留检查结果,不返回内部路径和修复计划。确认中的 review 可按需提交 terms(source、target、status)、manual_glossary、excluded_segment_ids、document_context。字段错误通过 details.fields 提示公开字段路径和校验代码。
CLI
Skill 包含 CLI,需要 Node.js 22+。下载包默认连接下载站点,可用 SIMPLIFYAI_API_URL 或 --api-url 覆盖。
node simplifyai-translate/scripts/cli.mjs config
node simplifyai-translate/scripts/cli.mjs capabilities
node simplifyai-translate/scripts/cli.mjs --help
字段定义见 OpenAPI JSON,当前支持的功能和价格见 capabilities。