图片翻译API

免费体验

智能识别并翻译图片中的文字，生成指定语言的图片，支持 26 种目标语言。自动保留原图的字体、字号、文字颜色和排版，最大程度还原原图样式。

接口返回的结果图片链接一般有效期为 1 小时，请及时下载存储。

鉴权

每个 API 请求都必须在请求头中携带你的 API Key。请按当前文档中的请求方式和参数说明，将其作为 X-API-KEY 请求头传入。

X-API-KEY: YOUR_API_KEY

创建图片翻译任务

POST /api/tasks/visual/image-translator

请求参数

image_url string 可选

原图下载地址。与 image_file 至少提供一个；同时传入时优先使用 image_file。

二选一必填

image_file file 可选

原图文件（二进制）。与 image_url 至少提供一个；同时传入时优先使用 image_file。

图片上传要求请参看使用规范与限制#7。

target_language string 必填

目标语言，使用以下语言代码：

AR：阿拉伯语
BG：保加利亚语
CSY：捷克语
DEU：德语
ENG：英语
ESP：西班牙语
FRA：法语
HUN：匈牙利语
ID：印度尼西亚语
ITA：意大利语
JPN：日语
JW：爪哇语
KOR：韩语
MS：马来语
MY：缅甸语
NLD：荷兰语
PLK：波兰语
ROM：罗马尼亚语
RUS：俄语
TH：泰语
TRK：土耳其语
VIN：越南语
TL：他加禄语（菲律宾）
PTB：巴西葡萄牙语
CHT：繁体中文
CHS：简体中文

aspect_ratio string 可选

输出图片宽高比。不传时自动设置；支持 1:1、2:3、3:2、4:3、3:4、16:9、9:16、9:21。

quality string 可选

输出质量，可选：

1k
1.5k
2k（默认）

sync uint 可选

调用方式，可选：

0：异步（默认）。创建任务后返回 task_id，再轮询查询结果。
1：同步。等待翻译完成后直接返回结果。

返回参数

status integer

响应状态码。200 表示请求成功，不代表图片翻译成功。详见状态码说明。

message string

返回的信息说明。处理失败时请携带错误信息和 task_id 联系支持人员。

data.task_id string

任务 ID，用于查询图片翻译结果。

status integer

响应状态码。200 表示请求成功，不代表图片翻译成功。详见状态码说明。

message string

返回的信息说明。处理失败时请携带错误信息和 task_id 联系支持人员。

data.task_id string

任务 ID，用于查询图片翻译结果。

data.image_url string

翻译结果图片下载地址或 base64 数据。结果链接一般有效期为 1 小时。

data.state integer

任务处理状态，成功或失败时停止轮询。详见状态码说明。

0：排队中。
1：成功。
2：准备中。
3：等待中。
4：处理中。
< 0：失败。
-8：处理超时，最长 180 秒。
-7：无效图片文件。
-5：图片超过 10MB。
-3：服务器下载图片失败。
-2：翻译完成，但上传结果失败。
-1：图片翻译失败。

data.progress integer

任务处理进度，范围为 0～100。请结合 data.state 判断翻译是否成功。

data.created_at integer

任务创建时间戳。

data.processed_at integer

任务开始处理时间戳。

data.completed_at integer

任务完成时间戳。

data.state_detail string

任务状态详情。

data.return_type integer

结果返回方式。

data.type integer

接口返回的结果方式字段。

data.time_elapsed number

任务处理耗时。

查询图片翻译结果

异步请求建议每 1 秒 轮询一次结果，本接口最大轮询时长为 180 秒；累计轮询超过该时长仍未返回结果，即可视为超时失败。

GET /api/tasks/visual/image-translator/{task_id}

路径参数

task_id string 必填

任务 ID，用于查询图片翻译结果。

返回参数

status integer

响应状态码。200 表示请求成功，不代表图片翻译成功。详见状态码说明。

message string

返回的信息说明。处理失败时请携带错误信息和 task_id 联系支持人员。

data.task_id string

任务 ID，用于查询图片翻译结果。

data.image_url string

翻译结果图片下载地址或 base64 数据。结果链接一般有效期为 1 小时。

data.state integer

任务处理状态，成功或失败时停止轮询。详见状态码说明。

0：排队中。
1：成功。
2：准备中。
3：等待中。
4：处理中。
< 0：失败。
-8：处理超时，最长 180 秒。
-7：无效图片文件。
-5：图片超过 10MB。
-3：服务器下载图片失败。
-2：翻译完成，但上传结果失败。
-1：图片翻译失败。

data.progress integer

任务处理进度，范围为 0～100。请结合 data.state 判断翻译是否成功。

data.created_at integer

任务创建时间戳。

data.processed_at integer

任务开始处理时间戳。

data.completed_at integer

任务完成时间戳。

data.state_detail string

任务状态详情。

data.return_type integer

结果返回方式。

data.time_elapsed string

任务处理耗时。

data.cost number

接口返回的费用值。

data.use_point integer

本次任务消耗的算粒。每次成功调用消耗 5 算粒。

使用规范与限制

接口返回的结果图片链接一般有效期为 1 小时，请及时下载存储。
HTTP status 为 200 仅表示请求成功；data.state = 1 才表示翻译成功，data.state < 0 表示失败。成功或失败后均应停止轮询。
URL 作为参数传递时请遵守 URL 编码规范。下载结果时请保留完整签名参数，不要将 & 错误转义。
图片下载地址支持 HTTP 和 OSS 协议，最长 512 个字符，下载超时 20 秒。图片大小以服务端接收到的文件为准。
处理通常需要 1～2 分钟，耗时受图片大小影响。异步轮询间隔建议 1 秒，累计不超过 180 秒。
默认 QPS 为 2；如需提高限制，请联系商务。每次成功调用消耗 5 算粒。
上传图片需符合以下格式、分辨率和大小限制。

格式大小分辨率

JPEG, JPG, PNG, WebP 不超过 10MB ≤ 6000 × 6000 px

格式	大小	分辨率
JPEG, JPG, PNG, WebP	不超过 10MB	≤ 6000 × 6000 px

响应

{
  "status": 200,
  "data": {
    "task_id": "94806a3f-1173-4afb-9bcc-3ff19c0981f4",
    "created_at": 1789541552,
    "processed_at": 1789541552,
    "completed_at": 1789541563,
    "progress": 100,
    "state": 1,
    "state_detail": "Complete",
    "image_url": "YOUR_RESULT_IMAGE_URL",
    "return_type": 2,
    "cost": 0,
    "use_point": 5
  }
}