OneSky External API v1

Programmatically upload XLIFF / XLSX / DOCX / PPTX files for machine translation, poll job progress, and download the translated results.

通过 API 上传 XLIFF / XLSX / DOCX / PPTX 文件进行机器翻译，轮询任务进度，并下载翻译结果。

Overview概述

The API exposes four endpoints under the base path /v1. A typical integration uploads a file, receives a jobId, polls job status until it is Done, then downloads the returned files.

该 API 在基础路径 /v1 下提供四个端点。典型集成流程为：上传文件，获得 jobId，轮询任务状态直到变为 Done，然后下载返回的文件。

All requests and responses use application/json unless noted (file uploads use multipart/form-data). All endpoints must be called on the ext-api host above — requests to any other OneSky host are rejected.

除特别说明外，所有请求和响应均使用 application/json（文件上传使用 multipart/form-data）。所有端点必须通过上方的 ext-api 主机调用——发往其他 OneSky 主机的请求会被拒绝。

Authentication身份验证

Every request must include your API key in the x-api-key header. Keys are generated in the OneSky MTPE Portal (one-time reveal on creation) and scope which projects and languages you may access.

每个请求都必须在 x-api-key 请求头中携带你的 API key。Key 在 OneSky MTPE Portal 生成（创建时仅显示一次），并决定你可访问的项目与语言范围。

curl https://ext-api.oneskyai.net/v1/projects \
  -H "x-api-key: osk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Create an API key创建 API key

API keys are self-managed in the OneSky MTPE Portal.

API key 由你在 OneSky MTPE Portal 自助管理。

1. Sign in to the MTPE Portal with your OneSky account, then open the API Keys page from the top navigation (or go directly to the URL above).
2. Click Generate Key, enter a descriptive label (e.g. integration-prod) to identify the key later, and confirm.
3. The full key (osk_…) is shown once. Copy it immediately and store it in a secret manager — it is never displayed again and cannot be recovered.
4. Send it in the x-api-key header of every request.

1. 用你的 OneSky 账号登录 MTPE Portal，从顶部导航打开 API Keys 页面（或直接访问上方 URL）。
2. 点击 Generate Key，填写一个便于识别的 label（例如 integration-prod），然后确认。
3. 完整的 key（osk_…）只会显示一次。请立即复制并保存到密钥管理工具——之后不会再显示，且无法找回。
4. 在每个请求的 x-api-key 请求头中携带它。

Conventions约定

HTTP status codesHTTP 状态码

Error body shapes错误响应结构

Errors raised during authentication use a message field; errors raised by an endpoint use an error field.

身份验证阶段产生的错误使用 message 字段；端点产生的错误使用 error 字段。

// auth-layer error (401 / 403 / 500 before reaching an endpoint)
{ "message": "Unauthorized" }

// endpoint error (validation, not found, etc.)
{ "error": "projectId is required" }

Typical workflow典型流程

1.  GET  /v1/projects      → pick a projectId
2.  GET  /v1/languages     → confirm supported languages
3.  POST /v1/upload        → returns { "jobId": "..." }
4.  GET  /v1/jobs/status?jobId=...   (poll every ~5s)
       status: Pending → Processing → Done
5.  When status = Done, download each URL in the "files" array

1.  GET  /v1/projects      → 选择一个 projectId
2.  GET  /v1/languages     → 确认支持的语言
3.  POST /v1/upload        → 返回 { "jobId": "..." }
4.  GET  /v1/jobs/status?jobId=...   （约每 5 秒轮询一次）
       status: Pending → Processing → Done
5.  当 status = Done 时，下载 "files" 数组中的每个 URL

List projects列出项目

Returns the projects accessible to your API key. Use a returned id as the projectId when uploading.

返回你的 API key 可访问的项目。上传时使用返回的 id 作为 projectId。

{
  "projects": [
    { "id": "recGItPC9oapMIyyX", "name": "My Project" }
  ]
}

{ "message": "Unauthorized" }

List languages列出语言

Returns the source → target language pairs allowed for your account (the pairs array — the source of truth), plus flattened sourceLanguages / targetLanguages lists for convenience (e.g. dropdowns). Codes are lowercase and must be used when uploading XLSX files. (XLIFF files carry their own language attributes.) An account whose organization configured no pairs gets empty lists — meaning no pair restriction on upload.

返回你账号允许的源 → 目标语言语言对（pairs 数组——以此为准）， 另外附带扁平化的 sourceLanguages / targetLanguages 列表以便使用（例如下拉框）。语言代码为小写， 上传 XLSX 文件时必须使用。（XLIFF 文件自带语言属性。）若你的组织未配置任何语言对，则返回空列表—— 即上传时不做语言对限制。

{
  "pairs": [
    { "source": { "code": "en",    "name": "English" },             "target": { "code": "zh-cn", "name": "Chinese Simplified" } },
    { "source": { "code": "en",    "name": "English" },             "target": { "code": "ja",    "name": "Japanese" } },
    { "source": { "code": "zh-tw", "name": "Chinese Traditional" }, "target": { "code": "ko",    "name": "Korean" } }
  ],
  "sourceLanguages": [
    { "code": "en",    "name": "English" },
    { "code": "zh-tw", "name": "Chinese Traditional" }
  ],
  "targetLanguages": [
    { "code": "zh-cn", "name": "Chinese Simplified" },
    { "code": "ja",    "name": "Japanese" },
    { "code": "ko",    "name": "Korean" }
  ]
}

{ "error": "Failed to fetch languages" }

Upload a file上传文件

Uploads an XLIFF, XLSX, DOCX or PPTX file and starts the automation pipeline (Source Upload → Word Count → Machine Translation → Export). Provide the file either as a binary multipart/form-data upload or as a public fileUrl (JSON body). Returns a jobId to poll.

上传 XLIFF、XLSX、DOCX 或 PPTX 文件并启动自动化流程（Source Upload → Word Count → Machine Translation → Export）。文件可通过二进制 multipart/form-data 上传，或提供可公开访问的 fileUrl （JSON body）。返回用于轮询的 jobId。

Parameters参数

Example — by URL (DOCX)示例 — 通过 URL（DOCX）

curl -X POST https://ext-api.oneskyai.net/v1/upload \
  -H "x-api-key: osk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
        "fileUrl": "https://example.com/file.docx",
        "projectId": "recGItPC9oapMIyyX",
        "sourceLanguage": "en",
        "targetLanguages": "zh-CN,ja"
      }'

PPTX is identical — just point fileUrl at a .pptx (or send a .pptx binary via -F "file=@..."). No column or sheet fields apply.

PPTX 完全相同——只需将 fileUrl 指向 .pptx （或用 -F "file=@..." 上传 .pptx 二进制）。不涉及任何列或工作表字段。

Example — binary upload (XLIFF)示例 — 二进制上传（XLIFF）

curl -X POST https://ext-api.oneskyai.net/v1/upload \
  -H "x-api-key: osk_xxx" \
  -F "file=@/path/to/merge_en.xliff" \
  -F "projectId=recGItPC9oapMIyyX" \
  -F "importExistingTranslation=false"

Example — by URL (XLSX)示例 — 通过 URL（XLSX）

curl -X POST https://ext-api.oneskyai.net/v1/upload \
  -H "x-api-key: osk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
        "fileUrl": "https://example.com/file.xlsx",
        "projectId": "recGItPC9oapMIyyX",
        "sourceLanguage": "en",
        "targetLanguages": "zh-CN,ja",
        "columnsSchema": { "en": "A" },
        "sheetNames": ["Sheet1"]
      }'

Source-only mapping (above) is the typical MT case — no target column, MT generates the translations. To import pre-translated text, add the target column(s), e.g. "columnsSchema": { "en": "A", "zh-CN": "B" }, and optionally "keyCol": "D".

仅映射源语言（如上）是常见的 MT 场景——不填目标列，由 MT 生成译文。如需导入预翻译文本， 请加上目标列，例如 "columnsSchema": { "en": "A", "zh-CN": "B" }，并可选填 "keyCol": "D"。

{ "jobId": "20260618153243-8528" }

{ "error": "Language pair(s) not supported: en>fr" }

Each source → target pair must be in your organization's allowed pairs (configured by OneSky). This is separate from the project auto-MT check below — a pair can be allowed for your account yet still be rejected if the project itself does not support MT for it. When your organization configured no pairs, this check is skipped.

每个源 → 目标语言对都必须在你组织的允许语言对内（由 OneSky 配置）。这与下方的项目自动 MT 校验是两回事——某语言对可能在你账号允许范围内，但若项目本身不支持该语言对的 MT，仍会被拒绝。若你的组织未配置任何语言对，则跳过此校验。

{ "error": "Project not found: rectMWcKtHHymDygX" }

{ "error": "MT not support for en to ja" }

Every upload is an auto-MT job, and auto-MT support is project-specific. The request is rejected up front if the resolved project does not support machine translation for a requested source → target pair.

每次上传都是自动 MT 任务，而自动 MT 的支持范围因项目而异。若所解析的项目不支持某个 源 → 目标语言对的机器翻译，请求会被提前拒绝。

{ "error": "projectId is not accessible" }

{ "error": "File too large. Max 30MB for binary upload. Use fileUrl for larger files." }

Check job status查询任务状态

Polls the automation job returned by POST /upload. Poll roughly every 5 seconds until status is a terminal value.

轮询 POST /upload 返回的自动化任务。约每 5 秒轮询一次，直到 status 变为终态。

{
  "jobId": "20260618153243-8528",
  "status": "Done",
  "languages": [
    { "sourceLanguage": "en", "targetLanguage": "zh-cn", "status": "Done" }
  ],
  "files": [
    "https://file.oneskyai.net/mtpe-export/f02cd3b9-.../merge-en.xliff"
  ],
  "serverTime": "2026-06-24T08:15:30.123Z"
}

{
  "jobId": "20260618153243-8528",
  "status": "Processing",
  "languages": [
    { "sourceLanguage": "en", "targetLanguage": "zh-cn", "status": "Done" },
    { "sourceLanguage": "en", "targetLanguage": "ja",    "status": "Processing" }
  ],
  "serverTime": "2026-06-24T08:15:30.123Z"
}

{
  "jobId": "20260618153243-8528",
  "status": "Failed",
  "languages": [
    { "sourceLanguage": "en", "targetLanguage": "zh-cn", "status": "Done" },
    { "sourceLanguage": "en", "targetLanguage": "ja",    "status": "Failed",
      "errorMessage": "MT is not supported for this language pair" }
  ],
  "serverTime": "2026-06-24T08:15:30.123Z"
}

{ "error": "Job not found" }

Job statuses任务状态

Each per-language task and the aggregate job carry one of these statuses:

每个分语言任务以及聚合任务都会是以下状态之一：

The aggregate status is derived from all per-language tasks: Stopped if any is stopped, else Failed if any failed, else Processing if any is still running, else Done when all are done.

聚合 status 由所有分语言任务推导：任一为 Stopped 则为 Stopped； 否则任一为 Failed 则为 Failed；否则任一仍在运行则为 Processing； 全部完成则为 Done。

Error reference错误参考

Authentication (all endpoints)身份验证（所有端点）

POST /upload

GET /jobs/status