OmniDocOmniDoc 开发者文档
OMNIDOC / DEVELOPER DOCUMENTATION

把文档工作流,
接进你的应用。

从上传一份文件,到翻译、查询进度和下载结果。这里按接入顺序说明每一步,也提供文件管理、文档处理与音视频服务的接口入口。

BASE URLhttps://omnidoc.top/api/v1
HTTPS · JSON · API Key 认证文件翻译采用异步任务

这里介绍云端 HTTP API。需要让 AI 在本地创建、编辑或导出文档?请阅读 桌面 AI / MCP 接口。

01 先完成一次不扣积分的请求

先确认密钥和网络正常,再开始上传文件。余额查询不扣积分,也不会创建翻译任务。

1准备 API Key

登录 API 控制台,创建以 sk_ 开头的密钥。建议为每个应用创建独立 Key,并设置预算。

Key 代表创建它的账号。请只在服务端保存,使用环境变量读取,不要写入网页源码或公开仓库。

2查询余额

设置 OMNIDOC_API_KEY 环境变量,然后运行下面任一示例。

成功时返回 JSON;401 表示需要检查密钥。不要在工单、截图或日志中发送完整 Key。

Bash / zsh · cURL
export OMNIDOC_API_KEY="sk_your_key"

curl --fail-with-body --silent --show-error \
  'https://omnidoc.top/api/v1/billing/credits/balance' \
  -H "X-API-Key: $OMNIDOC_API_KEY"

02 从文件到翻译结果

上传成功只意味着文件已入库。创建任务后需要等待终态,再查询并下载产物。

01 / UPLOAD上传原文件

申请地址 → PUT 文件 → 确认上传

02 / CREATE创建翻译任务

传入文档 ID 与目标语言

03 / WAIT跟踪处理进度

查询、SSE 或 Webhook

04 / DOWNLOAD下载生成文件

列出产物,逐项下载

步骤方法与路径保留的结果
申请上传POST /upload/presignupload_url、upload_headers、finalize_token
传输原文件PUT 返回的 upload_url成功响应;此请求不带 API Key
确认上传POST /upload/finalizedocument.id
创建翻译POST /jobs任务 id
查询状态GET /jobs/{job_id}completed 或 failed
列出产物GET /artifacts?job_id={job_id}产物 ID 与格式
下载结果GET /artifacts/{artifact_id}/download文件字节与响应文件名
直传时原样使用服务端返回的 upload_headers,不要把 X-API-Key 发给存储地址。上传地址过期或传输失败时,重新申请地址。查看完整上传协议 →

03 按你要完成的事找接口

每个入口包含具体路径、请求字段与示例。账号开放状态与 Key 限制仍然适用。

04 认证与资源归属

API Key 关联账号身份;它不是某个文件的公开下载口令。

请求头

统一使用 X-API-Key: sk_…,或 Authorization: Bearer sk_…。发送 JSON 时设置 Content-Type: application/json。

每个请求只选择一种认证写法即可。

账号与 Key 的边界

只能访问当前账号有权使用的资源;服务开放状态、Key 预算和允许的翻译配置仍然生效。

账号信息变更及 Key 创建、轮换、撤销在控制台完成。

认证、预算与轮换 → 服务权限与记录范围 →

05 把失败处理写进接入流程

超时不等于任务没创建。区分可重试错误与需要修正的请求,避免重复提交和重复处理。

幂等创建

每次新的创建操作生成一个 Idempotency-Key。重试同一操作时沿用原键及完全相同的请求体。

文档操作、音视频任务和音色创建要求幂等键;其他创建接口以对应参考页为准。

异步通知

初次接入可轮询任务;持续跟踪进度可使用 SSE,后台接收终态可使用 Webhook。

SSE 连接说明 · Webhook 验签与回调

状态先检查处理方式
401 / 403密钥、权限、资源归属修正凭据或权限,不要盲目重试
402可用积分补足积分后重新提交
409幂等键与请求体、资源状态查询原操作,再决定是否发起新操作
422响应中的字段错误修正参数或文件内容
429业务 code 与 Retry-After频率或排队限制可等待;Key 预算耗尽需先调整预算
5xx服务暂时性错误有上限的指数退避;创建请求保留幂等键

保存响应头 X-Request-Id、请求时间和路径便于排查,不要记录完整密钥。全部错误码与重试示例 →

06 接入前确认计费边界

查询与管理

上传、查询任务、下载结果、查询余额与凭证不扣积分;术语表、项目、标签、搜索及分享也不扣积分。

产生处理用量

文件翻译、文档工具、即时翻译及音视频服务按对应费率和实际用量结算。创建任务不等于最终扣款。

在翻译请求中可用 max_credit_millicredits 设置本次扣除上限;通过积分操作记录核对冻结与最终结算。Key 预算用尽后仍可查询其任务、产物和凭证。查看积分单位与响应字段 →
下载原生文档OmniDoc 官网客户端下载API 控制台

示例按公开 API 文档整理。字段、格式与限制请以对应接口参考及当前账号设置为准。