Image Translation API

# Image Translation API

Intelligently recognize and translate text in images, generating images in your chosen language with support for 26 target languages. Automatically preserve the original fonts, font sizes, text colors, and layout to match the original style as closely as possible.

> Result image URLs are generally valid for 1 hour. Please download and store them promptly.

## Base URL

https://techhk.aoscdn.com

## Authentication

Every request must include the X-API-KEY request header.

```http
X-API-KEY: YOUR_API_KEY
```

[Get or manage your API key](https://picwish.com/my-account?subRoute=api-key)

## Request modes

sync=0: Async (default); create a task, then poll for the result. sync=1: Sync; wait for processing to complete and return the result directly.

## Source image

Source image URL. Provide at least one of image_url or image_file; image_file takes precedence when both are supplied.

Source image file as binary data. Provide at least one of image_file or image_url; image_file takes precedence when both are supplied.

## Endpoints

| Purpose | Method | Path |
| --- | --- | --- |
| Create an image translation task | POST | /api/tasks/visual/image-translator |
| Query image translation result | GET | /api/tasks/visual/image-translator/{task_id} |

## Create an image translation task

POST /api/tasks/visual/image-translator

Content-Type: `multipart/form-data`

### Body Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| image_url | string | one required | Source image URL. Provide at least one of image_url or image_file; image_file takes precedence when both are supplied. |
| image_file | file | one required | Source image file as binary data. Provide at least one of image_file or image_url; image_file takes precedence when both are supplied. |
| target_language | string | required | Target language. Use one of the following language codes:<br>`AR`: Arabic<br>`BG`: Bulgarian<br>`CSY`: Czech<br>`DEU`: German<br>`ENG`: English<br>`ESP`: Spanish<br>`FRA`: French<br>`HUN`: Hungarian<br>`ID`: Indonesian<br>`ITA`: Italian<br>`JPN`: Japanese<br>`JW`: Javanese<br>`KOR`: Korean<br>`MS`: Malay<br>`MY`: Burmese<br>`NLD`: Dutch<br>`PLK`: Polish<br>`ROM`: Romanian<br>`RUS`: Russian<br>`TH`: Thai<br>`TRK`: Turkish<br>`VIN`: Vietnamese<br>`TL`: Tagalog (Philippines)<br>`PTB`: Brazilian Portuguese<br>`CHT`: Traditional Chinese<br>`CHS`: Simplified Chinese |
| aspect_ratio | string | optional | Output aspect ratio. Omit for automatic sizing. Supported values: 1:1, 2:3, 3:2, 4:3, 3:4, 16:9, 9:16, 9:21. |
| quality | string | optional | Output quality. Available values:<br>`1k`<br>`1.5k`<br>`2k` (default) |
| sync | uint | optional | Request mode. Available values:<br>`0`: Async (default). Read task_id from the create response, then poll for the result.<br>`1`: Sync. Wait for translation to complete and return the result directly. |

### Async return parameters

| Name | Type | Description |
| --- | --- | --- |
| status | integer | Response status. 200 means the request succeeded, not that image translation succeeded. |
| message | string | Response message. Include the error message and task_id when contacting support about a failed task. |
| data.task_id | string | Task ID used to query the image translation result. |

### Sync return parameters

| Name | Type | Description |
| --- | --- | --- |
| status | integer | Response status. 200 means the request succeeded, not that image translation succeeded. |
| message | string | Response message. Include the error message and task_id when contacting support about a failed task. |
| data.task_id | string | Task ID used to query the image translation result. |
| data.image_url | string | Translated image URL or base64 data. Result URLs are generally valid for 1 hour. |
| data.state | integer | Task status. Stop polling on success or failure.<br>`0`: Queued.<br>`1`: Succeeded.<br>`2`: Preparing.<br>`3`: Waiting.<br>`4`: Processing.<br>`< 0`: Failed.<br>`-8`: Processing timed out (maximum 180 seconds).<br>`-7`: Invalid image file.<br>`-5`: Image exceeds 10MB.<br>`-3`: The server failed to download the image.<br>`-2`: Translation completed, but uploading the result failed.<br>`-1`: Image translation failed. |
| data.progress | integer | Task progress from 0 to 100. Check data.state to determine whether translation succeeded. |
| data.created_at | integer | Timestamp of task creation. |
| data.processed_at | integer | Timestamp when processing started. |
| data.completed_at | integer | Timestamp of task completion. |
| data.state_detail | string | Detailed task status. |
| data.return_type | integer | Result return method. |
| data.type | integer | Result method field returned by the API. |
| data.time_elapsed | number | Elapsed processing time. |

### Async request: image URL

```bash
curl 'https://techhk.aoscdn.com/api/tasks/visual/image-translator' \
-H 'X-API-KEY: YOUR_API_KEY' \
-F 'sync=0' \
-F 'target_language=ENG' \
-F 'quality=2k' \
-F 'image_url=YOUR_IMAGE_URL'
```

### Async request: local file

```bash
curl 'https://techhk.aoscdn.com/api/tasks/visual/image-translator' \
-H 'X-API-KEY: YOUR_API_KEY' \
-F 'sync=0' \
-F 'target_language=ENG' \
-F 'quality=2k' \
-F 'image_file=@/path/to/image.jpg'
```

Successful create response:

```json
{
  "status": 200,
  "message": "ok",
  "data": {
    "task_id": "94806a3f-1173-4afb-9bcc-3ff19c0981f4"
  }
}
```

### Sync request: image URL

```bash
curl 'https://techhk.aoscdn.com/api/tasks/visual/image-translator' \
-H 'X-API-KEY: YOUR_API_KEY' \
-F 'sync=1' \
-F 'target_language=ENG' \
-F 'quality=2k' \
-F 'image_url=YOUR_IMAGE_URL'
```

### Sync request: local file

```bash
curl 'https://techhk.aoscdn.com/api/tasks/visual/image-translator' \
-H 'X-API-KEY: YOUR_API_KEY' \
-F 'sync=1' \
-F 'target_language=ENG' \
-F 'quality=2k' \
-F 'image_file=@/path/to/image.jpg'
```

Successful sync response (result field: image_url):

```json
{
  "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": 1,
    "time_elapsed": 0
  }
}
```

## Query image translation result

For asynchronous requests, poll the result once every **1 second**. The maximum polling duration for this API is **180 seconds**; if the total polling time exceeds this without a result, treat it as a timeout failure.

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

### Path Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| task_id | string | required | Task ID used to query the image translation result. |

### Return Parameters

| Name | Type | Description |
| --- | --- | --- |
| status | integer | Response status. 200 means the request succeeded, not that image translation succeeded. |
| message | string | Response message. Include the error message and task_id when contacting support about a failed task. |
| data.task_id | string | Task ID used to query the image translation result. |
| data.image_url | string | Translated image URL or base64 data. Result URLs are generally valid for 1 hour. |
| data.state | integer | Task status. Stop polling on success or failure.<br>`0`: Queued.<br>`1`: Succeeded.<br>`2`: Preparing.<br>`3`: Waiting.<br>`4`: Processing.<br>`< 0`: Failed.<br>`-8`: Processing timed out (maximum 180 seconds).<br>`-7`: Invalid image file.<br>`-5`: Image exceeds 10MB.<br>`-3`: The server failed to download the image.<br>`-2`: Translation completed, but uploading the result failed.<br>`-1`: Image translation failed. |
| data.progress | integer | Task progress from 0 to 100. Check data.state to determine whether translation succeeded. |
| data.created_at | integer | Timestamp of task creation. |
| data.processed_at | integer | Timestamp when processing started. |
| data.completed_at | integer | Timestamp of task completion. |
| data.state_detail | string | Detailed task status. |
| data.return_type | integer | Result return method. |
| data.time_elapsed | string | Elapsed processing time. |
| data.cost | number | Cost value returned by the API. |
| data.use_point | integer | Credits consumed by this task. Each successful call consumes 5 credits. |

### cURL

```bash
curl 'https://techhk.aoscdn.com/api/tasks/visual/image-translator/{task_id}' \
-H 'X-API-KEY: YOUR_API_KEY'
```

Processing response:

```json
{
  "status": 200,
  "message": "success",
  "data": {
    "progress": 21,
    "state": 4
  }
}
```

Completed async response (result field: image_url):

```json
{
  "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
  }
}
```

Failed task response:

```json
{
  "status": 200,
  "message": "success",
  "data": {
    "task_id": "94806a3f-1173-4afb-9bcc-3ff19c0981f4",
    "progress": 0,
    "state": -1
  }
}
```

Failed request response:

```json
{
  "status": 401,
  "message": "Invalid API key"
}
```

## Recommended asynchronous flow

1. POST a task with image_url or image_file, target_language and sync=0.
2. Read data.task_id from the response.
3. GET the result every 1 second for no more than 180 seconds.
4. When data.state=1, read data.image_url and stop polling. When data.state<0, record the error and stop polling.
5. Download and store the image before the result URL expires.

## Guidelines and Limits



- Result image URLs are generally valid for 1 hour. Please download and store them promptly.



- HTTP status 200 only means the request succeeded. data.state = 1 means translation succeeded; data.state < 0 means it failed. Stop polling on either success or failure.



- Follow URL encoding standards when passing URLs. Preserve all signed URL parameters when downloading results; do not incorrectly escape &.



- Image URLs support HTTP and OSS, up to 512 characters, with a 20-second download timeout. File size is measured on the server.



- Processing usually takes 1–2 minutes, depending on image size. Poll asynchronous tasks every 1 second for no more than 180 seconds.



- The default QPS limit is 2. Contact sales for a higher limit. Each successful call consumes 5 credits.





- Uploaded images must meet the following format, resolution, and file size limits.



| Format | File size | Resolution |

| --- | --- | --- |

| JPEG, JPG, PNG, WebP | Up to 10MB | ≤ 6000 × 6000 px |



## Status codes



Determine success by combining the HTTP response status code (`status`) with the task status code (`data.state`).



### HTTP response status codes



| Code | Meaning |

| --- | --- |

| 200 | The request is successful. |

| 400 | Wrong parameter passed by the client. Check whether a parameter is missing or has an incorrect value. |

| 401 | Unauthorized API key. Check that X-API-KEY is correct and the service is enabled. |

| 404 | The requested URL or resource does not exist. Check that the URL or task_id is correct. |

| 413 | The uploaded file exceeds the allowed size. Refer to the supported image size. |

| 429 | Request frequency exceeds the QPS limit (default QPS is 2). Slow down or contact us to raise your QPS. |

| 500 | Server-side exception. Please contact support. |



### Task status codes (data.state)



1 = succeeded; greater than 1 = still processing; less than 0 = failed.



| Code | Meaning |

| --- | --- |

| -17 | Processing failed because the prompt is invalid. |

| -16 | Processing failed because a third-party review detected prohibited content. |

| -15 | Processing failed due to insufficient resources. |

| -14 | Processing failed because the input image content does not meet the requirements. |

| -13 | Processing failed because the task was canceled due to an exception. |

| -11 | Processing failed because the result is empty. |

| -10 | Processing failed because internal review detected prohibited content. |

| -9 | Processing failed because the internal program failed during loop processing. |

| -8 | Processing timed out. The maximum processing time is 180 seconds. |

| -7 | Invalid image file (e.g. corrupted image or incorrect format). |

| -5 | The image_url image exceeds the size limit (10MB). |

| -3 | The server failed to download your file. Check that the source image URL is available. |

| -2 | Processing completed, but uploading the result to OSS failed. |

| -1 | Processing failed. |

| 0 | Queued. The task is waiting in the queue. |

| 1 | Completed. Processing succeeded. |

| 2 | Preparing. |

| 3 | Waiting. |

| 4 | Processing in progress. |

| 5 | Internally publishing the result. |

| 6 | Processing. Internal loop processing is in progress. |