adg t_img - 图片翻译接口系列，json 数据返回

{
  "article_title": "ADG t_img 图片翻译接口全解析：从入门到工程化实战",
  "article_topic": "图片翻译API接口技术指南",
  "tags": ["图片翻译", "OCR", "API接口", "多语言", "工程化"],
  "summary": "t_img 是万邦开放平台推出的图片翻译专用接口，集 OCR 文字识别与机器翻译于一体，支持 20+ 语种互译，兼容 JPG/PNG 等主流格式，可保持原图排版布局，广泛应用于跨境电商、文档翻译、截图实时翻译等场景。本文从接口原理、参数详解、返回结构到代码实战，系统梳理 t_img 接口的完整接入方案。",
  "sections": [
    {
      "section_title": "一、接口概述",
      "content": "t_img 是图片翻译专用 API 接口，实现了「OCR 文字识别 + 机器翻译 + 版式回填」一体化处理。开发者只需传入图片 URL 或 Base64 编码，指定目标语言，即可一次性获取识别文本、翻译结果以及文字坐标信息，无需手动拼接 OCR 和翻译两个接口。",
      "key_features": [
        "OCR + 翻译一体化，单次调用完成全流程",
        "支持 20+ 语种互译（中、英、日、韩、法、德、俄、西等）",
        "兼容 JPG、PNG、BMP、WEBP 等主流图片格式",
        "返回文字区域坐标（rect/points），支持版式还原",
        "支持图片 URL 和 Base64 两种传入方式",
        "内置缓存机制，重复请求响应更快"
      ]
    },
    {
      "section_title": "二、接口信息与请求参数",
      "content": "接口采用 HTTP GET/POST 方式调用，公共参数通过 URL 拼接，业务参数支持 GET 查询串或 POST JSON Body。",
      "request_info": {
        "api_name": "translate.t_img",
        "endpoint": "https://api-gw.onebound.cn/translate/t_img",
        "method": "GET / POST",
        "content_type": "application/x-www-form-urlencoded / application/json"
      },
      "public_params": [
        {"name": "key", "type": "String", "required": true, "desc": "调用密钥 Key，GET 方式拼接在 URL 中"},
        {"name": "secret", "type": "String", "required": true, "desc": "调用密钥 Secret"},
        {"name": "api_name", "type": "String", "required": true, "desc": "API 接口名称，固定为 t_img"},
        {"name": "result_type", "type": "String", "required": false, "desc": "返回格式：json/jsonu/xml/serialize，默认 json"},
        {"name": "lang", "type": "String", "required": false, "desc": "接口说明语言：cn/en/ru，默认 cn"},
        {"name": "cache", "type": "String", "required": false, "desc": "是否使用缓存：yes/no，默认 yes"}
      ],
      "business_params": [
        {"name": "imgcode", "type": "String", "required": true, "desc": "图片地址（URL）或图片 Base64 编码（POST 方式）"},
        {"name": "to", "type": "String", "required": true, "desc": "目标语言代码，如 en（英语）、jp（日语）、kor（韩语）等"}
      ]
    },
    {
      "section_title": "三、返回数据结构详解",
      "content": "接口返回 JSON 格式数据，顶层为 items 对象，包含源语言、目标语言以及识别翻译内容列表。每个 content 元素对应图片中一行识别到的文字，包含原文、译文、位置坐标等完整信息。",
      "response_structure": {
        "items": {
          "from": "源语言代码（如 zh）",
          "to": "目标语言代码（如 en）",
          "content": [
            {
              "src": "识别到的原始文本",
              "dst": "翻译后的文本",
              "rect": "文字区域矩形坐标（x y width height）",
              "lineCount": "文本行数",
              "points": "文字区域四角坐标点数组 [{x,y}, ...]",
              "pasteImg": "回填效果图（Base64，部分场景返回）"
            }
          ]
        }
      },
      "response_example": {
        "items": {
          "from": "zh",
          "to": "en",
          "content": [
            {
              "src": "恭喜发财",
              "dst": "May you be happy and prosperous",
              "rect": "209 3 382 78",
              "lineCount": 1,
              "points": [
                {"x": 209, "y": 3},
                {"x": 589, "y": 3},
                {"x": 589, "y": 78},
                {"x": 209, "y": 78}
              ],
              "pasteImg": ""
            },
            {
              "src": "小财神",
              "dst": "Little God of Wealth",
              "rect": "612 641 157 53",
              "lineCount": 1,
              "points": [
                {"x": 612, "y": 641},
                {"x": 768, "y": 641},
                {"x": 768, "y": 692},
                {"x": 612, "y": 692}
              ],
              "pasteImg": ""
            }
          ]
        }
      }
    },
    {
      "section_title": "四、支持语言列表",
      "content": "t_img 接口覆盖主流语种，常用语言代码对照如下：",
      "language_codes": [
        {"language": "中文", "code": "zh"},
        {"language": "英语", "code": "en"},
        {"language": "日语", "code": "jp"},
        {"language": "韩语", "code": "kor"},
        {"language": "法语", "code": "fra"},
        {"language": "德语", "code": "de"},
        {"language": "西班牙语", "code": "spa"},
        {"language": "俄语", "code": "ru"},
        {"language": "葡萄牙语", "code": "pt"},
        {"language": "意大利语", "code": "it"},
        {"language": "荷兰语", "code": "nl"},
        {"language": "马来语", "code": "may"},
        {"language": "印尼语", "code": "id"},
        {"language": "土耳其语", "code": "tr"},
        {"language": "波兰语", "code": "pl"},
        {"language": "瑞典语", "code": "swe"},
        {"language": "丹麦语", "code": "dan"},
        {"language": "希腊语", "code": "el"},
        {"language": "匈牙利语", "code": "hu"},
        {"language": "罗马尼亚语", "code": "rom"}
      ]
    },
    {
      "section_title": "五、Python 接入实战",
      "content": "以下是基于 requests 库的 Python 调用示例，涵盖 URL 图片和 Base64 图片两种传入方式，以及返回结果的结构化解析。",
      "code_example_python": """import requests
import base64
from typing import Dict, List, Any
class TImgTranslator:
    """t_img 图片翻译客户端"""
    
    def __init__(self, api_key: str, api_secret: str):
        self.api_key = api_key
        self.api_secret = api_secret
        self.base_url = "https://api-gw.onebound.cn/translate/t_img"
    
    def translate_by_url(self, img_url: str, target_lang: str = "en") -> Dict[str, Any]:
        """通过图片 URL 翻译"""
        params = {
            "key": self.api_key,
            "secret": self.api_secret,
            "api_name": "t_img",
            "imgcode": img_url,
            "to": target_lang,
            "result_type": "json"
        }
        resp = requests.get(self.base_url, params=params, timeout=30)
        resp.raise_for_status()
        return resp.json()
    
    def translate_by_base64(self, image_path: str, target_lang: str = "en") -> Dict[str, Any]:
        """通过本地图片 Base64 翻译"""
        with open(image_path, "rb") as f:
            img_base64 = base64.b64encode(f.read()).decode()
        
        payload = {
            "key": self.api_key,
            "secret": self.api_secret,
            "api_name": "t_img",
            "imgcode": img_base64,
            "to": target_lang
        }
        resp = requests.post(self.base_url, json=payload, timeout=30)
        resp.raise_for_status()
        return resp.json()
    
    def extract_translations(self, result: Dict[str, Any]) -> List[Dict[str, str]]:
        """提取翻译文本对列表"""
        items = result.get("items", {})
        content_list = items.get("content", [])
        return [
            {
                "original": item.get("src", ""),
                "translated": item.get("dst", ""),
                "position": item.get("rect", "")
            }
            for item in content_list
        ]
# 使用示例
if __name__ == "__main__":
    translator = TImgTranslator("your_api_key", "your_api_secret")
    result = translator.translate_by_url(
        img_url="https://example.com/test.jpg",
        target_lang="en"
    )
    translations = translator.extract_translations(result)
    for t in translations:
        print(f"原文: {t['original']}")
        print(f"译文: {t['translated']}")
        print(f"位置: {t['position']}")
        print("---")"""
    },
    {
      "section_title": "六、Java 接入示例",
      "content": "Java 环境下通过原生 URLConnection 调用接口，解析 JSON 返回结果。",
      "code_example_java": """import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLConnection;
import java.nio.charset.StandardCharsets;
import org.json.JSONObject;
import org.json.JSONArray;
public class TImgExample {
    
    private static final String API_URL = 
        "https://api-gw.onebound.cn/translate/t_img/";
    
    public static JSONObject translateImage(String key, String secret, 
            String imgUrl, String targetLang) throws Exception {
        
        String url = API_URL + "?key=" + key + "&secret=" + secret 
            + "&api_name=t_img&imgcode=" + imgUrl + "&to=" + targetLang;
        
        URL realUrl = new URL(url);
        URLConnection conn = realUrl.openConnection();
        conn.setConnectTimeout(10000);
        conn.setReadTimeout(30000);
        
        try (BufferedReader rd = new BufferedReader(
                new InputStreamReader(conn.getInputStream(), StandardCharsets.UTF_8))) {
            StringBuilder sb = new StringBuilder();
            int cp;
            while ((cp = rd.read()) != -1) {
                sb.append((char) cp);
            }
            return new JSONObject(sb.toString());
        }
    }
    
    public static void main(String[] args) throws Exception {
        JSONObject result = translateImage(
            "your_api_key", "your_api_secret",
            "https://example.com/test.jpg", "en"
        );
        
        JSONObject items = result.getJSONObject("items");
        JSONArray content = items.getJSONArray("content");
        
        System.out.println("源语言: " + items.getString("from"));
        System.out.println("目标语言: " + items.getString("to"));
        System.out.println("识别行数: " + content.length());
        
        for (int i = 0; i < content.length(); i++) {
            JSONObject item = content.getJSONObject(i);
            System.out.println("原文: " + item.getString("src"));
            System.out.println("译文: " + item.getString("dst"));
        }
    }
}"""
    },
    {
      "section_title": "七、应用场景",
      "content": "t_img 接口的应用场景覆盖跨境电商、内容平台、工具类产品等多个领域。",
      "scenarios": [
        {
          "name": "跨境电商商品图翻译",
          "desc": "批量翻译商品详情图、海报图中的文字，快速适配多语言站点，提升海外用户转化率"
        },
        {
          "name": "截图实时翻译工具",
          "desc": "集成到浏览器插件、桌面应用中，实现选区截图即翻译，适合阅读外文文档、网页时使用"
        },
        {
          "name": "文档图片翻译",
          "desc": "扫描件、PDF 转图片后批量翻译，保留版式坐标信息，便于还原排版输出"
        },
        {
          "name": "APP 拍照翻译",
          "desc": "移动端调用摄像头拍照后上传翻译，应用于旅游翻译、菜单翻译、路牌翻译等场景"
        },
        {
          "name": "社交媒体内容本地化",
          "desc": "自动识别并翻译社交媒体图片中的文字，助力内容多语言分发和运营"
        }
      ]
    },
    {
      "section_title": "八、最佳实践与注意事项",
      "content": "在生产环境接入 t_img 接口时，建议从异常处理、缓存策略、图片预处理等方面做好工程化保障。",
      "best_practices": [
        "图片大小控制在 10MB 以内，过大图片建议先压缩再上传，可显著提升响应速度",
        "优先使用图片 URL 方式传入，减少请求体大小；本地图片再走 Base64 路径",
        "开启 cache=yes 利用缓存机制，相同图片重复翻译可大幅降低调用成本和延迟",
        "对返回的 content 列表做空判断，图片中无文字时 content 可能为空数组",
        "rect 字段格式为「x y width height」，points 为四角坐标，可根据需要选择使用",
        "生产环境建议配置超时重试机制，网络波动时自动重试 2-3 次保障成功率",
        "批量翻译场景建议控制并发数，避免触发频率限制，可结合队列削峰处理",
        "敏感内容翻译需结合内容安全接口做二次审核，确保合规"
      ]
    }
  ],
  "conclusion": "t_img 接口以「OCR + 翻译 + 坐标」一体化的设计，大幅降低了图片翻译功能的开发门槛。对于需要快速上线图片翻译能力的团队来说，直接调用成熟 API 比自建 OCR + 翻译链路更高效、更稳定。结合缓存策略、图片预处理和异常重试，可以构建出高性能、高可用的图片翻译服务，支撑跨境电商、工具类应用、内容平台等多种业务场景。"
}