要调用 helloGPT 翻译 API，先申请并妥善保管 API Key，再在请求头以 Bearer 方式传入；对短文本可直接调用 /v1/translate 同步接口，向 body 提交源语、目标语和文本；对图片、语音或大批量文本则用 multipart 或异步任务（callback 或 task_id 查询）；支持 glossary、style、preserve_format 等参数以保证术语一致与风格；遇到限流、鉴权或格式错误按状态码处理。下面按从易到难、带示例和注意事项一步步讲清楚，让你能马上上手并逐步优化。
先把概念讲清楚（为什么要知道这些）
把调用翻译 API 想象成给一个很聪明的翻译员下单：你要告诉他“你是谁（鉴权）”、“翻译什么（文本或文件）”、“翻成哪种语言（语言码）”、“有没有特殊要求（词汇表、风格）”，以及“希望怎么拿回结果（同步、回调或流式）”。这些是每次请求都要考虑的基本要素。理解它们，后面实际编码会顺很多。
基本流程（一步步来）
- 获取 API Key：注册服务账号，在控制台创建应用并复制 API Key（Secret）。
- 准备请求：构建请求头（Authorization: Bearer <API_KEY>）、选择端点与方法（通常 POST /v1/translate）。
- 提交内容：短文本直接 JSON，图片/语音用 multipart/form-data；支持批量数组。
- 读取结果：同步返回译文或异步返回 task_id，使用 GET /v1/tasks/{id} 查询。
- 错误处理：按 HTTP 状态码和返回的 error.code 做重试或告警。
典型请求头和公约
常见请求头如下：
- Authorization: Bearer <API_KEY>
- Content-Type: application/json 或 multipart/form-data
- Accept: application/json
- X-Request-ID: 可选，用于端到端追踪
核心接口详解
下面以常见的几个端点为例，说明参数与返回值，放在表格里更直观。
| 接口 | /v1/translate |
| 方法 | POST |
| 用途 | 同步短文本翻译，或提交少量文件 |
| 参数（JSON） |
source: 源语言码，auto 可自动识别 target: 目标语言码（必填） text: 字符串或数组 model: 可选，指定翻译模型版本 glossary_id: 可选，术语表 id style: formal|informal，风格偏好 preserve_format: boolean，是否保留原格式 |
| 返回 | 200 OK，body 包含 translations 数组及每段置信度与用时 |
| 接口 | /v1/translate/async |
| 方法 | POST |
| 用途 | 大文件、批量、语音或图片异步任务 |
| 返回 | 202 Accepted，返回 task_id，可轮询 /v1/tasks/{task_id} 或等待回调 |
示例：简单 curl、Python、Node 使用
先给一个最常用的简单场景：把一段中文译成英文。
curl（JSON 同步）
说明：将 <API_KEY>、文本、语言替换成真实值。
curl -X POST “https://api.hellogpt.example.com/v1/translate” \
-H “Authorization: Bearer <API_KEY>” \
-H “Content-Type: application/json” \
-d ‘{“source”:”zh”,”target”:”en”,”text”:”你好，欢迎使用 helloGPT 翻译。”}’
Python（requests）
import requests
url = “https://api.hellogpt.example.com/v1/translate”
headers = {“Authorization”:”Bearer “+API_KEY,”Content-Type”:”application/json”}
data = {“source”:”zh”,”target”:”en”,”text”:[“今天天气很好。”]}
r = requests.post(url, json=data, headers=headers)
print(r.json())
Node (fetch)
const res = await fetch(‘https://api.hellogpt.example.com/v1/translate’, { method:’POST’, headers:{‘Authorization’:`Bearer ${API_KEY}`,’Content-Type’:’application/json’}, body: JSON.stringify({source:’zh’, target:’ja’, text:’早上好’}) });
const j = await res.json(); console.log(j);
处理图片与语音（multipart 与异步）
图片或语音一般体积较大，常用做法是：
- 先上传文件到 API 的 /v1/uploads（或用预签名 URL 上传到存储），获得 file_id。
- 在 /v1/translate/async 中引用 file_id，提交目标语言与回调地址。
- 服务端处理完成后，通过回调（POST 到你的 callback_url）或在 /v1/tasks/{id} 查询结果。
注意点
- 媒体类型要指定 mime，音频可选择自动识别语种或传入强制识别参数。
- 对于语音翻译，通常先做 ASR（转写），再翻译或一体化流水线处理。
可用参数与含义（速查表）
| 参数 | 说明 |
| source | 源语言码，auto 可自动识别 |
| target | 目标语言码，必填 |
| text | 字符串或字符串数组 |
| model | 指定模型版本（mt-v1、mt-v2 等） |
| glossary_id | 术语表 id，保证术语一致 |
| style | 翻译风格（formal/informal） |
| preserve_format | 是否保留源格式（如换行、标点） |
| callback_url | 异步任务完成后回调地址 |
出错与重试策略
常见状态码和应对：
- 400 Bad Request：参数错误，检查 request body 与语言码格式。
- 401 Unauthorized：API Key 错误或过期，重新获取或检查权限。
- 403 Forbidden：没有访问某些受限模型或资源的权限。
- 429 Too Many Requests：触发速率限制，按 Retry-After 头部等待并指数退避重试。
- 5xx：服务端错误，短时重试并报警。
性能、安全与成本考虑（实用建议）
几个日常会碰到的优化点：
- 批量合并：把一系列短文本合并到一次请求可以降低延迟与成本，但要控制单次长度上限。
- 并发控制：客户端保持合理并发数，避免同时发起大量请求导致被限流。
- 缓存译文：对不常变的短句做本地缓存，尤其是界面常用文案。
- 加密与密钥管理：API Key 不应暴露在前端；前端请求走自家后端转发并注入 Key。
- 成本控制：使用低成本模型处理草稿、只有在需要高质量时选择大模型；对大批量异步任务做配额与预算控制。
术语表与风格一致性
术语表（glossary）是提高翻译一致性的关键。把公司的专有名词或常用短语上传为表格并绑定 glossary_id，可以在接口调用时启用。风格参数（style）帮助维持称呼和语气，例如“更正式”或“更口语化”。这两项对产品化场景尤其重要。
流式翻译与实时场景
实时字幕或语音对话场景常用流式 API（WebSocket 或 Server-Sent Events）。要点：
- 建立长链接，发送音频片段或实时转写数据。
- 服务端按段返回部分译文与最终译文，客户端合并并展示。
- 注意网络抖动、断线重连与消息序号保证顺序。
调试小贴士（实践中常遇的坑）
- 语言码不统一：一些系统用 en-US、zh-CN，另一些用简短 en、zh；以 API 文档为准。
- 换行与特殊符号：若要保留排版，使用 preserve_format 并测试 edge cases。
- 文件编码：确保上传文本为 UTF-8，避免字符替换问题。
- 并发资源锁：若批量翻译涉及同一 glossary 的写操作，注意同步更新策略。
示例场景：跨境电商批量商品翻译
要点流程：
- 抽取商品标题与描述，合并成批次，每批不超过 API 限制字符数。
- 调用 /v1/translate/async 并传入 glossary_id 保证品牌/规格一致。
- 结果回调后做质量检查，若出现质量问题，反馈到质量审校流。
- 对高价值商品使用更高质量模型并人工校对。
最后值得记住的几句话（边想边说的那种）
把调用流程记成四步：获取 Key → 构建请求 → 收到翻译 → 处理错误和优化。开始先用同步 JSON 快速验证，再根据需求切换到 multipart、异步或流式。术语表、风格与缓存能显著提高产品体验。实现时别把 Key 放前端，遇到限流按 Retry-After 做指数退避。好了，按示例改个 API_KEY、语言码和文本，你就能马上跑起来了。
