API 使用说明

有开发能力的用户可以通过调用 HTTP API 来翻译文档，把翻译的动作集成到个人或者企业的工作流程中。

目前，调用 API 并不需要支付额外的费用，只是跟网页版一样，翻译文档需要消耗用户的积分。

使用方式

调用 API 前，你需要创建自己的 API 密钥。

登入工作台，点击菜单中的个人头像，选择 “API”，可以进入密钥管理页面。

调用时，密钥以 Authorization Bearer 的方式放在 Header 中。如下面的例子

curl -X POST 'https://translate.simplifyai.cn/api/v1/translations' \
  -H 'Authorization: Bearer at-NjhhZmVlZTktNWNENC0yNGJkLTQ0OWItMWUyY2I5ODBjYzQh' \
  --form 'file=@bitcoin.pdf' \
  --form 'fromLang=English' \
  --form 'toLang=Simplified Chinese' -i

其中 at-NjhhZmVlZTktNWNENC0yNGJkLTQ0OWItMWUyY2I5ODBjYzQh 应该替换为你的密钥。

API - 翻译任务

创建翻译任务

上传文档，指定翻译的语言，创建新的翻译任务

POST https://translate.simplifyai.cn/api/v1/translations

参数：

• file - （必填）需要翻译的文件

• fromLang - (必填）被翻译的语言

• toLang - (必填）翻译成什么语言

• glossary - （非必填）指定的术语表名称，这里的名称是用户在网站上建立术语表时填写的名字

• glossaryId - （非必填）指定的术语表 ID，这个参数比 glossary 优先级更高：当两个参数都提供时，会使用这个参数指定的术语表

• model - (非必填）指定翻译模型，比如 gpt-4

• clientTaskId - （非必填）客户任务 ID，是 API 调用方提供的任务标识，长度不能超过 128，在同一个账户内必须唯一。可以用来查询翻译任务的状态，见“查询翻译任务”，适用于创建翻译任务时出现网络中断以致未能获取任务 ID 的情况。

其中 fromLang 和 toLang 的可选值，可以通过专门的接口获取，见下面的“查询可用语言“

正常返回 201：

• taskId - 翻译任务的 ID，用于查询任务的状态和文件地址

• price - 翻译任务需要的积分

异常返回：

• 401 - 没有提供正确的 API 密钥

• 400 - 参数不全

• 402 - 积分余额不够，此时任务仍然会被创建，会返回 taskId 和 price，但不会像网页端一样部分翻译用作预览。用户购买余额后，可以通过专门的接口来启动任务，见下面的“启动翻译任务”

• 429 - 调用太频繁，默认十秒内最多创建十个翻译任务

• 500 - 服务器端出现的其他错误

查询翻译任务

根据任务 ID ，或者客户任务 ID 来查询翻译任务的状态

GET https://translate.simplifyai.cn/api/v1/translations/:id

// or

GET https://translate.simplifyai.cn/api/v1/translations?id=:id

// or

GET https://translate.simplifyai.cn/api/v1/translations?clientTaskId=:clientTaskId

其中 :id 应替换为具体的 taskId, :clientTaskId 应替换为具体的客户任务ID。

译文的 URL 有时限，最长两小时，过期后要重新使用查询接口获取新的 URL。

正常返回 200：

• taskId - 翻译任务的 ID

• status - 任务状态，可能是 Unpaid, Waiting, Processing, Completed, Cancelled, Terminated, NotSupported

• progress - 进度，0 到 100

• translatedFileUrl - 译文文档的 URL，翻译完成才有。

• bilingualFileUrl - 双语文档的 URL，翻译完成才有。

• price - 此次翻译使用的积分

• totalToken - 需要翻译的 token 总数

异常返回：

• 401 - 没有提供正确的 API 密钥

• 404 - ID 对应的翻译任务不存在，或者已删除，或者不是当前用户创建的

• 500 - 服务器端出现的其他错误

删除翻译任务

根据 ID 删除指定的翻译任务。删除前请确保你已经把译文下载好了。

DELETE https://translate.simplifyai.cn/api/v1/translations/:id

正常返回 204

异常返回：

• 401 - 没有提供正确的 API 密钥

• 404 - ID 对应的翻译任务不存在，或者已删除，或者不是当前用户创建的

• 500 - 服务器端出现的其他错误

启动翻译任务

正常来说，创建翻译任务后会自动消费积分完整翻译。但如果因为积分不足导致 Unpaid，或者因为其他错误导致 Terminated，可以通过这个接口重新启动翻译任务。

如果 Unpaid 会尝试先扣积分再翻译，已经支付的 Terminated 则是直接重新启动翻译。

PUT https://translate.simplifyai.cn/api/v1/translations/:id

参数：

• 无

正常返回 200：

• status - 任务状态，可能是 Unpaid, Waiting, Processing, Completed, Cancelled, Terminated, NotSupported

• progress - 进度，0 到 100

• price - 此次翻译使用的积分

• totalToken - 需要翻译的 token 总数

异常返回：

• 401 - 没有提供正确的 API 密钥

• 404 - ID 对应的翻译任务不存在，或者已删除，或者不是当前用户创建的

• 402 - 积分余额不够

• 500 - 服务器端出现的其他错误

API - 信息查询

查询可用语言

返回可用语言的值，用在“创建翻译任务”中的 fromLang 和 toLang 参数中

GET https://translate.simplifyai.cn/api/v1/languages

// or

GET https://translate.simplifyai.cn/api/v1/languages?names

参数：

• names - 如果提供了这个参数（不需要特定值），则返回值会包含中文名

正常返回 200：

• 字符串的的数组，每个字符串代表一种语言，用于翻译时指定语言，如“Simplified Chinese”；如果请求中提供了 names 参数，则是返回包含 { name, value } 的数组，其中 name 是该语言的中文名，如“简体中文”，value 是用于翻译时指定语言的值，如“Simplified Chinese”。

查询可用文件扩展名

返回支持的文件扩展名，如 .pdf 之类的

GET https://translate.simplifyai.cn/api/v1/filetypes

参数：

• 无

正常返回 200：

• 字符串的的数组，每个字符串代表一种文件的扩展名，如 .pdf, .docx 等

API - 术语表管理

创建术语表

添加新的术语表

POST https://translate.simplifyai.cn/api/v1/glossaries

// Example:

curl -X POST 'https://translate.simplifyai.cn/api/v1/glossaries' \
  -H 'Authorization: Bearer at-...' \
  --form 'name=LLM' \
  --form 'content={"Chain of Thought": "思维链"}' -i

参数：

• name -（必填）术语表名称，不能跟用户之前创建的术语表名称重复

• content - (必填）JSON 字符串，里面所有的 key 是原文，对应的 value 是译文，如 {"chain of thought": "思维链"}

正常返回 201：

• id - 术语表 ID，用于在翻译中指定术语表，或者查询、更改术语表信息

• name - 术语表名称

异常返回：

• 401 - 没有提供正确的 API 密钥

• 400 - 参数不全或者不对

• 500 - 服务器端出现的其他错误

查询用户的所有术语表

查询当前用户的所有术语表

GET https://translate.simplifyai.cn/api/v1/glossaries

请求参数：

• offset -（非必填）按照创建时间的逆序，从第几个开始返回，默认为 0

• limit - (非必填）一次返回多少条记录，默认为 20， 最大为 1000

正常返回 200：

• data - 数组，每条数据都是 { id, name } 包含术语表的 ID 和名称

• count - 该用户总共有多少个术语表

• offset - 这次是从第几个开始查询的

异常返回：

• 401 - 没有提供正确的 API 密钥

• 500 - 服务器端出现的其他错误

查询指定术语表

根据 ID ，查询术语表

GET https://translate.simplifyai.cn/api/v1/glossaries/:id

正常返回 200：

• id - 术语表的 ID

• name: 术语表的名称

• content: 术语表的内容，JSON 格式

异常返回：

• 401 - 没有提供正确的 API 密钥

• 404 - ID 对应的术语表不存在，或者已删除，或者不是当前用户创建的

• 500 - 服务器端出现的其他错误

更改术语表

修改术语表的名称或者内容

PUT https://translate.simplifyai.cn/api/v1/glossaries/:id

参数：

• name -（非必填）术语表名称，不能跟用户之前创建的术语表名称重复

• content - (非必填）JSON 字符串，里面所有的 key 是原文，对应的 value 是译文，如 {"chain of thought": "思维链"}

正常返回 200：

• id - 术语表 ID

异常返回：

• 401 - 没有提供正确的 API 密钥

• 400 - 参数不对

• 404 - ID 对应的术语表不存在，或者已删除，或者不是当前用户创建的

• 500 - 服务器端出现的其他错误

删除术语表

删除指定术语表

DELETE https://translate.simplifyai.cn/api/v1/glossaries/:id

正常返回 204

异常返回：

• 401 - 没有提供正确的 API 密钥

• 404 - ID 对应的术语表不存在，或者已删除，或者不是当前用户创建的

• 500 - 服务器端出现的其他错误

API - 账户信息

获取账户信息

查询当前用户的账户信息，目前只返回余额

GET https://translate.simplifyai.cn/api/v1/me

正常返回 200：

• balance - 积分余额

异常返回：

• 401 - 没有提供正确的 API 密钥

• 500 - 服务器端出现的其他错误