批量上传术语

把术语批量写入项目术语库。异步接口 —— 和创建翻译任务一样，API 立刻返回一个 upload_id，真实写入在后台执行，完成后通过 callback_url 回调通知成功或失败。

关键特性

• 只接受 JSON 参数，不支持文件 URL
• 单次最多 1000 条
• 按 (team, project, content, source_language) upsert：同样内容同样源语言再上传，会合并覆盖旧记录
• 完成 / 失败都回调：term_upload.completed / term_upload.failed
• 向量同步：入库后自动排队同步到检索索引（非阻塞）

请求地址

POST {BASE_URL}/api/open/v1/terms/create

鉴权 Header

和 创建翻译任务 完全一样。

请求参数（Body）

参数	类型	必填	说明
terms	array	是	术语数组，最多 1000 条
callback_url	string	否	http(s) URL；上传结果会回调到这里。不传 → 不回调
callback_events	string[]	否	订阅的事件子集（term_upload.completed / term_upload.failed）。不传 → 两个都发

terms[] 条目字段

字段	类型	必填	说明
content	string	是	源语言下的术语文本（去前后空白后非空）
source_language	string	是	源语言码，必须在平台支持列表中（和 /languages 返回一致）
category	string	否	分类标签，例如 Item / Character
pic	string	否	关联图片 URL（如有业务需求）
translations	object	否	目标语言映射：{ "en": "Combat Power", "ja": "戦闘力" }；key 必须是支持的语言码；空串表示清空该语言翻译

响应（同步）

成功（HTTP 200）：

{
  "success": true,
  "code": 0,
  "msg": "ok",
  "trace_id": "d3f98b2c...",
  "data": {
    "upload_id": "d3f98b2c...",
    "accepted_at": "2026-04-23T08:00:01.234Z",
    "terms_count": 42
  }
}

• upload_id == trace_id，用于在集成侧关联本次上传 + 对应的回调
• terms_count：提交的术语条数（经过形状校验，未做 upsert）

回调（异步）

两个事件（status、detail 字段随事件变化）：

term_upload.completed（成功）

{
  "event": "term_upload.completed",
  "task_id": "",
  "project_id": "...",
  "trace_id": "d3f98b2c...",
  "delivery_id": "...",
  "timestamp": "2026-04-23T08:00:03.891Z",
  "status": "SUCCEEDED",
  "detail": {
    "upload_id": "d3f98b2c...",
    "terms_count": 42,
    "upserted_count": 35,
    "modified_count": 7
  },
  "error": null
}

• upserted_count：新插入的术语数量
• modified_count：已存在、本次有字段变化的术语数量
• terms_count - upserted_count - modified_count：已存在但本次无变化的数量

term_upload.failed（失败）

{
  "event": "term_upload.failed",
  "trace_id": "d3f98b2c...",
  "status": "FAILED",
  "detail": {
    "upload_id": "d3f98b2c...",
    "terms_count": 42,
    "failure_code": 500
  },
  "error": "..."
}

回调签名

和 /tasks/create 的回调完全一样 —— MD5 签名放 X-Loxily-Sign，有 4 次内联重试（立即 / 16s / 32s / 64s），2xx 即视为成功。

task_id 字段为空字符串，因为本事件不绑定到特定任务。

错误码

code	说明
400	参数缺失 / 非法（terms 超过 1000 / 形状不对 / source_language 不在白名单 / callback_url 格式错 / translations 键值异常）
401	签名校验失败 / 时间戳过期
404	appKey 无效
403	App Secret 未配置
500	系统错误（同步阶段）

注意：后台上传阶段的失败不会改变同步响应的 success: true，只会通过 term_upload.failed 回调通知。

示例

APP_KEY="5685414646a54423c891d87194d87f3f"
APP_SECRET="<你的 App Secret>"
BASE_URL="https://api.loxily.com"

TIMESTAMP=$(date +%s)
BODY=$(cat <<'EOF'
{
  "terms": [
    {
      "content": "战斗力",
      "source_language": "zh-cn",
      "category": "Item",
      "translations": { "en": "Combat Power", "ja": "戦闘力" }
    },
    {
      "content": "兔窝工头",
      "source_language": "zh-cn",
      "category": "Character",
      "translations": { "en": "Rabbit Den Foreman" }
    }
  ],
  "callback_url": "https://your.hook/terms-upload"
}
EOF
)
SIGN=$(printf '%s' "${TIMESTAMP}${BODY}${APP_SECRET}" | md5)

curl -s -X POST "${BASE_URL}/api/open/v1/terms/create" \
  -H "Content-Type: application/json" \
  -H "X-Loxily-AppKey: ${APP_KEY}" \
  -H "X-Loxily-Timestamp: ${TIMESTAMP}" \
  -H "X-Loxily-Sign: ${SIGN}" \
  --data "${BODY}"

幂等

本接口没有幂等键 —— 重复上传同一组术语是安全的（会被 upsert 合并），但每次都会产生一条 upload_id + 对应回调。若要彻底避免重复工作，请在集成侧做去重后再调用。