获取支持的语言列表（语言码 -> 显示名）。请在调用 translate_document 之前调用此工具，让用户选择源语言和目标语言。

获取当前用户可用的翻译模型列表。请在调用 translate_document 之前调用此工具，并让用户选择一个模型。返回的 data 是对象列表：model 是提交时要填的模型名，coefficient 是计费倍率——倍率 3 的模型翻同样的量扣三倍额度，请把倍率一并告诉用户再让他选。locked 里是当前会员档位还用不了的模型，不要拿它们去提交。

查询账户的可用额度、会员档位和各项限额。要报余额、要判断「够不够翻这一单」时用它——额度数字必须来自本工具，不要从之前某一单的实扣去推算，两者不是一回事（那是本次消耗，不是余额）。返回里 quota.wallet 是可用额度，报余额就报它——它已经含了今日免费的消耗，别再拿 freeUsed/freeTotal 去加。freeUsed/freeTotal 是今日免费额度的用量计数，ocrWallet/ocrFreeUsed 是上游单独发的一组 OCR 数字（实测和 wallet 同步增减，走不走 OCR 都一样），这两组都不是另一份余额。advanced 是高级模型额度（get_model_list 里 coefficient>1 的那几个），归属还没实测过。limits 是当前会员档的硬限制：videoDurationMinutes 单个视频最长多少分钟、videoConcurrency 视频任务能同时跑几个、uploadFileSizeMB 单文件多大。这些限制服务端会真的按它拒绝提交，所以准备翻一个长视频之前先看一眼。注意免费用户另有「每月累计视频时长」上限，本接口看不到，只有提交时才会撞上。查不到时返回 code=500，请如实告诉用户查不到，不要拿估算值顶上。

取文档的预签名上传链接。拿到链接后原样执行返回的 uploadCommand（只替换其中的文件路径，Content-Disposition 一个字符都不能改，否则 S3 报 SignatureDoesNotMatch）。上传是访问外网，你那边默认没有网络权限的话，第一次执行就把联网权限一起要上，别先试一次失败再补申请。上传成功后用返回的 objectKey 作为 fileObjectKey 调 translate_document。

判断一个已经传上去的 PDF 是不是扫描件（图片版）。PDF 传完就调它——看到「上传结果 HTTP 200」之后、提交翻译之前，把 objectKey 传进来。只有 PDF 需要，其他格式不用调。返回 isOcr=1 表示扫描件、翻译要走 OCR（扣的是 OCR 额度，和普通翻译不是同一本账，请把这点告诉用户），isOcr=0 是文本版 PDF；isDoubleDeck=1 表示双层 PDF（扫描图上盖了一层文字）——这种直接翻会翻到那层往往是错的文字上，返回的 msg 里会给出拍平工具的链接，请原样转述给用户，让他先拍平再重新上传。结果会被记住，随后 translate_document 直接复用、不会重复检测，也不用你把 is_ocr 填回去（检测只负责把扫描件标出来，不会去关掉别人显式打开的 OCR）。大文件可能要等十几秒到一分钟，那是服务端在下载并分析整个 PDF，属正常。测不出来时返回 code=500——那不影响提交，照常翻就是了。

提交文档翻译任务。请先调用 get_model_list 获取可用模型，调用 get_supported_languages 获取支持的语言列表，然后让用户选择模型和目标语言。返回中的 orders[].translateOrderNo 即订单号，直接用它调 wait_for_translation，无需再查列表。图片（png/jpg/jpeg）也走这个工具——服务端把它们当 IMAGE 类型，按 1 页计费，且一律走 OCR（扣的是 OCR 额度），不需要另外的图片翻译接口。支持的格式：PDF / DOCX / PPTX / XLSX / TXT / EPUB / 图片。提交前本工具会对 file_list 里的 PDF 自动判定是不是扫描件（只有 PDF 有这个概念），据此填 OCR 开关，结果在返回的 msg 和 ocrDetection 里——请把「走没走 OCR」原样告诉用户，那关系到扣哪一本额度。若返回 code=202，表示判定还没出来，本次没有提交、没有扣费（data.submitted / data.charged 都是 false，data.detecting 是还在测的文件）：等十几秒用完全相同的参数再调一次本工具即可，不要重新上传文件、也不要改参数。这一步挡着是因为判错两边都要付代价：扫描件按普通 PDF 翻会出一片空白，OCR 又扣另一本额度。确实等不及、或者反复 202 一直不出结果，就显式传 is_ocr（0=按普通 PDF 翻，1=强制整批走 OCR）绕过它。若返回非 200（如 600 系统繁忙），说明是翻译服务侧的问题而非上传问题：用相同参数重试本工具即可，不要重新上传文件。

查询文档翻译任务状态。返回里不带下载地址——详情给的是上游默认生成的带水印版本，水印开关只对 get_document_translation_result 生效，要下载一律走那个工具。

获取文档翻译结果下载链接。url_type 决定版式：1=原文、2=纯译文（默认）、3=横向对照（左右并排，仅 PDF）、4=纵向对照（原文与译文上下排列，仅 PDF 与 EPUB）。对照版是取的时候现合成的，第一次取可能要多等一会儿——慢是正常的，别当成失败去重试，更不要因此改回纯译文；也正因为要合成，翻译完成时不会替用户预先取好，用户点名要哪一版再来调。要译文不要传 1。返回的 url 走 CloudFront，url2 为国内兜底线路。两条链接都带签名参数，转述给用户时必须连问号后面的 Signature/Key-Pair-Id/expires/sign 一起原样给全，截断或缩短会导致 403 MissingKey。

查询文档翻译任务列表。只用来找单号和看状态，不带下载地址；要下载用 get_document_translation_result，它才认 is_watermark，链接也是现签发的。

通过批次号查询翻译任务

取视频的预签名上传地址。拿到地址后原样执行返回的 uploadCommand（只替换文件路径，Content-Disposition 一个字符都不能改，否则 S3 报 SignatureDoesNotMatch）。预签名地址仅 10 分钟有效，取到就传。注意视频和文档走的是不同端点、不同存储路径，视频不能用 upload_document 取链接。上传成功后用返回的 objectKey 作为 source_file_object_key 调 translate_video。

提交视频翻译任务。⚠️ 本工具会真实扣减账户额度并计入调用次数，所以提交是一次两步调用，第一次一定不会提交： (1) 先用文件的真实时长调 calculate_video_translation_quota 试算，voice_role / subtitle_type 必须和接下来提交的值完全一致（对不上会被拒绝提交）； (2) 带 voice_role 和 user_confirmed=true 调本工具，但不带 confirm_token——本工具此时不提交、不扣费，只返回 409、一段 data.userPrompt 和一张 data.options 菜单（配音 × 字幕的全部组合，每格带自己的额度和 confirmToken）； (3) 把 data.userPrompt 原样发给用户，等他在菜单里挑一项或选放弃。做成什么样、扣多少额度是用户的决定，不要替他选，也不要只转述你自己那一组； (4) 用户挑了第几项，就用 data.options 里那一项的 voiceRole / subtitleType / confirmToken 三个值（必须同属一项，不能混、不能造菜单外的组合）重调一次，这一次才真的提交扣费；用户选放弃就到此为止。 （客户端支持 elicitation 时服务端会直接弹窗问用户，此时省去 3-4 步，一次调用即可。） voice_role 与 subtitle_type 决定这次翻译到底做什么：两者都关（voice_role 传 No 且 subtitle_type=0）等于既不配音也不嵌字幕，产出的视频和原片没有区别，但一样扣费——上游不拦这个组合，请在提交前自行拦下并问用户。返回 data.videoTranslateOrderNo 是后续所有查询用的订单号。同一份文件、同一目标语言 30 分钟内再次提交会被直接拒绝，除非带上 retry_of_order_no（上一单单号）和 retry_confirmed=true——任务失败后不要自己改个参数就重提，先把失败原因告诉用户、问过再说。限制：免费用户单个视频最长 10 分钟、每月累计 10 分钟、单文件 200MB、同时只能有 1 个进行中的任务（Pro 为 60 分钟/1024MB/2 个）；这些是默认档位的值，账号实际的限额用 get_account_status 查，本工具提交前也会拿真实限额比一次，超了会直接拒绝（不提交、不扣费），到那时再重传剪短的文件就白传了一次。若 target_language 传 ar（阿拉伯语）且账号不是付费会员，上游要求人机验证 token，外部调用无法提供，会直接失败。

试算视频翻译要消耗多少额度，不扣费。提交 translate_video 前应当先调这个并把结果告诉用户。video_duration 必须是从文件里真实读出来的时长（ffprobe 等），不能按文件大小猜——服务端核实不了这个输入，猜错就等于给用户报了个假预算。计费规则：按 30 秒为一个计费单位向上取整，每单位 4 额度；voice_role 为 clone 且 subtitle_type≠0 时额度翻倍（实测 10 分钟视频：不配音 80 额度，开克隆配音 160 额度）。返回里如果带 limitWarning（视频超出会员档的时长上限）或 quotaWarning（余额不够），请先把那句话原样告诉用户再往下走——这两种情况提交上去会被服务端直接拒，白传一次文件。

查询单个视频翻译任务的状态。上游是 SSE 流，本工具取第一帧数据就返回，不会挂住。状态：0 未开始 / 1 进行中 / 2 成功 / 3 失败 / 4 已取消——注意 2 就是完成，和文档翻译的状态码不是一套，别混用。进行中时 step 表示阶段（1 语音识别 / 2 字幕翻译 / 3 语音生成）。任务通常要几分钟，建议 10-30 秒查一次，并把进度转述给用户。

等待视频翻译任务完成。提交 translate_video 后就用它跟进，不要自己反复调 get_video_translation_status。上游只能轮询、无法推送，本工具有两个返回时机：进度一有变化就立刻返回，否则等满本轮的等待时长（不传 timeout 时由本工具自适应：10 秒起，进度一直不动就逐轮翻倍到 45 秒封顶，省掉那些什么都说不出来的空转往返）。视频任务通常要几分钟。返回里 msg 是念给用户听的那一行、agentNote 是给你的操作指令：要转述就转述 msg，agentNote 一个字都不要念出去。finished=false 表示仍在处理，照 agentNote 的要求办：进度有变化就把 msg 那行原样告诉用户，和上次完全一样时一个字都不要输出（连「继续等待」这类过场话也不要），直接再次调用本工具继续等待，任务不会因此中断。完成后返回里带 translatedVideoUrl / targetSubtitlesUrl，要把它们原样完整交给用户——问号后面的签名参数一字都不能改；有效期以返回的 expiresAt / downloadNote 为准，不要按经验说成一小时。描述产物时请原样照抄 msg 或 outputNote 里那句产出说明（例如「未配音（保留原声），已嵌入译文字幕」），不要凭之前传过的参数自己推断有没有配音。该任务做过字幕改写的话，返回里给的就是改写后那一版（带 rewriteOrderNo），outputNote 会注明，别再回头用改写前的链接。任务失败或被取消时返回 code=500 且 data.failed=true，reason 是原因——请先告诉用户，问过之后再决定是否重新提交，重提会再次扣费。

分页查询视频翻译任务列表，只返回最近 15 天的记录。status 过滤值：0 未开始 / 1 进行中 / 2 成功 / 3 失败 / 4 已取消。列表只用来找单号和看状态，不带下载地址（每条几百字符的签名链接，十条就上万字符，且大多用不上）。要交付某一单的产出，拿它的 videoTranslateOrderNo 调 get_video_translation_status 取链接，那边是现签发的，不必担心列表里的地址过期。

取消视频翻译任务。只能取消 status=0（未开始）的任务，已经开始的会返回 31008。

等待翻译任务完成。上游只能轮询、无法推送，本工具有两个返回时机：进度一有变化就立刻返回，否则等满本轮的等待时长（不传 timeout 时由本工具自适应：10 秒起，进度一直不动就逐轮翻倍到 45 秒封顶，省掉那些什么都说不出来的空转往返）。返回 finished=true 时附带 downloadUrl（纯译文，CloudFront）与 downloadUrlCN（同一文件的国内兜底线路），其他版式用 get_document_translation_result 取。这两条链接带签名，转述时必须把问号后面的参数一起原样给全，截断会 403。返回里 msg 是念给用户听的那一行、agentNote 是给你的操作指令：要转述就转述 msg，agentNote 一个字都不要念出去。finished=false 表示仍在处理，照 agentNote 的要求办：进度有变化就把 msg 那行原样告诉用户，和上次完全一样时一个字都不要输出，直接再次调用本工具继续等待，任务不会因此中断。若任务被服务端取消或失败，返回 code=500 且 data.failed=true，reason 是原因（如 BACKEND_CANCEL）——请先把原因告诉用户，问过用户之后再决定是否用相同参数重试 translate_document，文件不需要重新上传。

获取视频的原文与译文字幕下载地址。任务 status 必须是 2（成功），否则返回 31008「文件翻译中」。若该任务已有改写记录，返回的是最近一次改写后的字幕。地址有有效期，以返回里的说明为准。

试算「用改好的字幕重新生成视频」要花多少额度，不扣费。改写是一单新的翻译任务、按视频时长计价，和第一次翻译同价，不是免费返工。校对字幕之前就可以先问这一句，把数字告诉用户。

用编辑后的字幕重新生成视频。⚠️ 真实扣费，所以和 translate_video 一样是两步调用：第一次不带 confirm_token，本工具不提交、不扣费，只回 409 加一段 data.userPrompt（里面有试算出来的真实额度）和一个 data.confirmToken；把 userPrompt 原样发给用户，等他明确同意，再带上那个 confirmToken 重新调用才会真的提交。客户端支持服务端弹窗时，本工具会直接问用户，同意即提交。确认码绑定「订单号 + 这两份字幕正文」，字幕改一行都要重新确认——用户同意的是他看过的那一版。原任务的 status 必须是 2（成功）。返回 data.videoTranslateRewriteOrderNo 是改写订单号，查进度用 get_video_rewrite_status。改写完成后请重新用原视频订单号去取产物（wait_for_video_translation 或 get_video_translation_status），它们会自动给改写后的那一版；改写前拿到的旧链接仍然有效，别再拿它当最终产物给用户。

连通性自检工具，不翻译、不提交任务、不扣任何额度。用来验证服务端能否通过 MCP elicitation 直接向用户提问（而不是靠模型自己填 user_confirmed 声称问过了）。调用后会返回客户端声明的能力，并在支持时真的弹一次提问。只在排查这个问题时调用，正常翻译流程不要调。

查询字幕改写任务的进度。上游是 SSE 流，本工具取第一帧数据就返回。状态含义同视频翻译：0 未开始 / 1 进行中 / 2 成功 / 3 失败 / 4 已取消。改写成功后回到原视频订单号调 wait_for_video_translation 或 get_video_translation_status 取产物，那边会带上改写版并说明产出。