前提
先在译档网页端 API 管理页创建 API key，然后保存到本机环境变量 YD_API_KEY。不要把完整 key 写入代码、提交记录或聊天日志。
API Skill
安装 pdf-translate API Skill
pdf-translate Skill 让 OpenClaw、Hermes、Codex、Claude Code 这类代理工具直接调用译档公开 API。它默认使用 YIDOC_API_BASE=https://translate.qkfintech.cn，不会在本地执行翻译。
Skill 文件
下载 SKILL.md，保存到目标平台的 pdf-translate/SKILL.md。API schema 可从 openapi.yaml 下载。
安装目录
| 平台 | 安装路径 | 说明 |
|---|---|---|
| OpenClaw | ~/.openclaw/skills/pdf-translate/SKILL.md |
创建目录后复制 Skill 文件，重启或刷新 OpenClaw。 |
| Hermes | ~/.hermes/skills/pdf-translate/SKILL.md |
创建目录后复制 Skill 文件，重启或刷新 Hermes。 |
| Codex | ~/.codex/skills/pdf-translate/SKILL.md |
创建目录后复制 Skill 文件，在新会话中调用 pdf-translate。 |
| Claude Code | ~/.claude/skills/pdf-translate/SKILL.md |
创建目录后复制 Skill 文件，在新会话中调用 pdf-translate。 |
安装命令模板
# 选择一个平台目录，把 PLATFORM_HOME 换成 ~/.openclaw、~/.hermes、~/.codex 或 ~/.claude
PLATFORM_HOME="$HOME/.codex"
mkdir -p "$PLATFORM_HOME/skills/pdf-translate"
curl -fsSL https://translate.qkfintech.cn/docs/api/SKILL.md \
-o "$PLATFORM_HOME/skills/pdf-translate/SKILL.md"
export YD_API_KEY="yd_sk_live_***"
export YIDOC_API_BASE="${YIDOC_API_BASE:-https://translate.qkfintech.cn}"Skill 覆盖的接口
| 接口 | Skill 使用场景 |
|---|---|
GET /v1/me | 检查 key、账户和余额。 |
POST /v1/files | 上传本地 PDF。 |
POST /v1/translation-estimates | 生成积分与 token 估算。 |
POST /v1/translations | 携带 Idempotency-Key 确认翻译任务。 |
GET /v1/translations/{translation_id} | 轮询状态、tokens、积分和 artifacts。 |
GET /v1/translations/{translation_id}/events | 读取进度事件。 |
GET /v1/translations/{translation_id}/artifacts/{artifact_id} | 下载译文 PDF。 |
GET /v1/usage | 查看 API/Web 用量归因。 |
安全规则
不要打印完整 key
输出日志时只展示 key 前缀或名称。密钥泄露后应立即在 API 管理页禁用并轮换。
不要错误复用幂等键
同一个 Idempotency-Key 只能带相同 body 重试。逻辑任务不同就生成新的 key。
成功后再下载
任务未 succeeded 或 artifacts 为空时，不要调用下载接口。
默认域名
生产默认使用 https://translate.qkfintech.cn。本地开发时才手动覆盖 YIDOC_API_BASE。