把文档工作流,
接进你的应用。
从上传一份文件,到翻译、查询进度和下载结果。这里按接入顺序说明每一步,也提供文件管理、文档处理与音视频服务的接口入口。
这里介绍云端 HTTP API。需要让 AI 在本地创建、编辑或导出文档?请阅读 桌面 AI / MCP 接口。
01 先完成一次不扣积分的请求
先确认密钥和网络正常,再开始上传文件。余额查询不扣积分,也不会创建翻译任务。
1准备 API Key
登录 API 控制台,创建以 sk_ 开头的密钥。建议为每个应用创建独立 Key,并设置预算。
Key 代表创建它的账号。请只在服务端保存,使用环境变量读取,不要写入网页源码或公开仓库。
2查询余额
设置 OMNIDOC_API_KEY 环境变量,然后运行下面任一示例。
成功时返回 JSON;401 表示需要检查密钥。不要在工单、截图或日志中发送完整 Key。
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"
import os
import requests
response = requests.get(
"https://omnidoc.top/api/v1/billing/credits/balance",
headers={"X-API-Key": os.environ["OMNIDOC_API_KEY"]},
timeout=30,
)
response.raise_for_status()
print(response.json())const apiKey = process.env.OMNIDOC_API_KEY;
if (!apiKey) throw new Error("请设置 OMNIDOC_API_KEY");
const response = await fetch(
"https://omnidoc.top/api/v1/billing/credits/balance",
{
headers: { "X-API-Key": apiKey },
signal: AbortSignal.timeout(30_000),
},
);
if (!response.ok) {
throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.json());02 从文件到翻译结果
上传成功只意味着文件已入库。创建任务后需要等待终态,再查询并下载产物。
申请地址 → PUT 文件 → 确认上传
传入文档 ID 与目标语言
查询、SSE 或 Webhook
列出产物,逐项下载
| 步骤 | 方法与路径 | 保留的结果 |
|---|---|---|
| 申请上传 | POST /upload/presign | upload_url、upload_headers、finalize_token |
| 传输原文件 | PUT 返回的 upload_url | 成功响应;此请求不带 API Key |
| 确认上传 | POST /upload/finalize | document.id |
| 创建翻译 | POST /jobs | 任务 id |
| 查询状态 | GET /jobs/{job_id} | completed 或 failed |
| 列出产物 | GET /artifacts?job_id={job_id} | 产物 ID 与格式 |
| 下载结果 | GET /artifacts/{artifact_id}/download | 文件字节与响应文件名 |
03 按你要完成的事找接口
每个入口包含具体路径、请求字段与示例。账号开放状态与 Key 限制仍然适用。
文件翻译
提交文档、选择目标语言、设置双语输出与术语表,查询任务并获取结果。
/jobs · /artifacts
资源上传与文件库
把本地文件上传到账号,管理文档列表,读取与下载文件。
/upload · /storage/files · /documents
处理PDF、图片与文档工具
查找格式转换、合并、拆分、压缩等文档处理接口与参数。
/document-operations · /file-tools
文本即时翻译与批量片段
翻译短文本或一组片段,适合把翻译接到应用里的文本工作流。
/ai
媒体音视频与音色
创建媒体任务,查询任务状态,管理账号可用的音色资源。
/media-jobs · /media-voices
术语术语表
创建和维护专业术语,导入或导出词条,并在翻译请求中引用。
/glossaries
组织项目、标签与分享
组织文件、检索内容,把相关文档归入项目并管理分享。
项目 · 标签 · 搜索 · 分享
用量积分与结算凭证
查询余额、任务用量,以及冻结、实扣、释放和退款记录。
/usage · /billing/credits04 认证与资源归属
API Key 关联账号身份;它不是某个文件的公开下载口令。
请求头
统一使用 X-API-Key: sk_…,或 Authorization: Bearer sk_…。发送 JSON 时设置 Content-Type: application/json。
每个请求只选择一种认证写法即可。
账号与 Key 的边界
只能访问当前账号有权使用的资源;服务开放状态、Key 预算和允许的翻译配置仍然生效。
账号信息变更及 Key 创建、轮换、撤销在控制台完成。
05 把失败处理写进接入流程
超时不等于任务没创建。区分可重试错误与需要修正的请求,避免重复提交和重复处理。
幂等创建
每次新的创建操作生成一个 Idempotency-Key。重试同一操作时沿用原键及完全相同的请求体。
文档操作、音视频任务和音色创建要求幂等键;其他创建接口以对应参考页为准。
| 状态 | 先检查 | 处理方式 |
|---|---|---|
401 / 403 | 密钥、权限、资源归属 | 修正凭据或权限,不要盲目重试 |
402 | 可用积分 | 补足积分后重新提交 |
409 | 幂等键与请求体、资源状态 | 查询原操作,再决定是否发起新操作 |
422 | 响应中的字段错误 | 修正参数或文件内容 |
429 | 业务 code 与 Retry-After | 频率或排队限制可等待;Key 预算耗尽需先调整预算 |
5xx | 服务暂时性错误 | 有上限的指数退避;创建请求保留幂等键 |
保存响应头 X-Request-Id、请求时间和路径便于排查,不要记录完整密钥。全部错误码与重试示例 →
06 接入前确认计费边界
查询与管理
上传、查询任务、下载结果、查询余额与凭证不扣积分;术语表、项目、标签、搜索及分享也不扣积分。
产生处理用量
文件翻译、文档工具、即时翻译及音视频服务按对应费率和实际用量结算。创建任务不等于最终扣款。
max_credit_millicredits 设置本次扣除上限;通过积分操作记录核对冻结与最终结算。Key 预算用尽后仍可查询其任务、产物和凭证。查看积分单位与响应字段 →