API Documentation

Call the translation service via HTTP requests. Authenticated endpoints require an API Key.

Base URL https://

🔑Authentication

Include your API Key in the request header for all authenticated endpoints:

x-api-key: sk-tr-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Or pass via URL query parameter:

?key=sk-tr-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

POST /v1/translate Single or batch translation

Translate a single text or an array of texts.

Request Parameters

Parameter	Type		Description
text	string	Required	Text to translate (single mode)
texts	string[]	Optional	Array of texts (batch mode, mutually exclusive with text)
lang	string	Optional	Target language code, default: zh

Request Examples

bash

# Single
curl -X POST ${BASE_URL}/v1/translate \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk-tr-your-key" \
  -d '{"text":"Hello, world!","lang":"zh"}'
# Batch
curl -X POST ${BASE_URL}/v1/translate \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk-tr-your-key" \
  -d '{"texts":["Hello","World"],"lang":"zh"}'

python

import requests
API_URL = "${BASE_URL}"
API_KEY = "sk-tr-your-key"
# Single
r = requests.post(f"{API_URL}/v1/translate",
    headers={"x-api-key": API_KEY},
    json={"text": "Hello, world!", "lang": "zh"})
print(r.json()["translation"])  # 你好，世界！
# Batch
r = requests.post(f"{API_URL}/v1/translate",
    headers={"x-api-key": API_KEY},
    json={"texts": ["Hello", "World"], "lang": "zh"})
print(r.json()["translations"])  # ["你好","世界"]

javascript

const API_URL = "${BASE_URL}", API_KEY = "sk-tr-your-key";
// Single
const r = await fetch(`${API_URL}/v1/translate`, {
  method: "POST",
  headers: { "Content-Type": "application/json", "x-api-key": API_KEY },
  body: JSON.stringify({ text: "Hello, world!", lang: "zh" })
});
console.log((await r.json()).translation); // 你好，世界！
// Batch
const r2 = await fetch(`${API_URL}/v1/translate`, {
  method: "POST",
  headers: { "Content-Type": "application/json", "x-api-key": API_KEY },
  body: JSON.stringify({ texts: ["Hello", "World"], lang: "zh" })
});
console.log((await r2.json()).translations); // ["你好","世界"]

java

import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;

var client = HttpClient.newHttpClient();
var req = HttpRequest.newBuilder()
    .uri(URI.create("${BASE_URL}/v1/translate"))
    .headers("Content-Type","application/json","x-api-key","sk-tr-your-key")
    .POST(BodyPublishers.ofString("{\"text\":\"Hello, world!\",\"lang\":\"zh\"}"))
    .build();
var resp = client.send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(resp.body()); // {"translation":"你好，世界！"}

Success Response

Single mode:

{ "translation": "你好，世界！" }

Batch mode:

{ "translations": ["你好", "世界"] }

Error Codes

Status	Description
400	Missing or invalid request parameters
401	API Key missing, invalid or expired
429	Quota exhausted or rate limit exceeded
500	Translation failed

API Key

Text

Target Language

POST /v1/translate/multi Multi-channel translation

Translate long text using multiple concurrent channels for better speed and stability.

Request Parameters

Parameter	Type		Description
text	string	Required	Text to translate
lang	string	Optional	Target language code, default: zh
channels	number	Optional	Concurrent channels, default 10, range 1–10

Request Examples

bash

curl -X POST ${BASE_URL}/v1/translate/multi \
  -H "Content-Type: application/json" \
  -H "x-api-key: sk-tr-your-key" \
  -d '{"text":"Long paragraph...","lang":"zh","channels":10}'

python

r = requests.post(f"{API_URL}/v1/translate/multi",
    headers={"x-api-key": API_KEY},
    json={"text": "Long paragraph...", "lang": "zh", "channels": 10})
print(r.json()["translation"])

javascript

const r = await fetch(`${API_URL}/v1/translate/multi`, {
  method: "POST",
  headers: { "Content-Type": "application/json", "x-api-key": API_KEY },
  body: JSON.stringify({ text: "Long paragraph...", lang: "zh", channels: 10 })
});
console.log((await r.json()).translation);

java

var body = "{\"text\":\"Long paragraph...\",\"lang\":\"zh\",\"channels\":10}";
var req = HttpRequest.newBuilder()
    .uri(URI.create("${BASE_URL}/v1/translate/multi"))
    .headers("Content-Type","application/json","x-api-key","sk-tr-your-key")
    .POST(BodyPublishers.ofString(body))
    .build();
var resp = client.send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(resp.body());

Success Response

{ "translation": "长段文字的翻译结果..." }

Error Codes

Status	Description
400	Missing or invalid request parameters
401	API Key missing, invalid or expired
429	Quota exhausted or rate limit exceeded
500	Translation failed

API Key

Text

Target Language

GET /v1/usage Query usage statistics

Query usage statistics, quota, and expiry information for the current API Key.

Request Examples

bash

curl ${BASE_URL}/v1/usage \
  -H "x-api-key: sk-tr-your-key"

python

r = requests.get(f"{API_URL}/v1/usage", headers={"x-api-key": API_KEY})
print(r.json())

javascript

const r = await fetch(`${API_URL}/v1/usage`, {
  headers: { "x-api-key": API_KEY }
});
console.log(await r.json());

java

var req = HttpRequest.newBuilder()
    .uri(URI.create("${BASE_URL}/v1/usage"))
    .header("x-api-key", "sk-tr-your-key")
    .GET().build();
var resp = client.send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(resp.body());

Success Response

{
  "charsUsed": 12345,
  "charsLimit": 1000000,
  "requestCount": 42,
  "lastUsedAt": "2026-05-20T12:00:00.000Z",
  "expiresAt": "2027-01-01T00:00:00.000Z",
  "expired": false,
  "daysLeft": 225
}

Response Fields

Field	Type	Description
charsUsed	number	Characters used
charsLimit	number\|null	Total quota (null = unlimited)
requestCount	number	Total request count
lastUsedAt	string\|null	Last used time
expiresAt	string\|null	Expiry time (null = never)
expired	boolean	Whether expired
daysLeft	number\|null	Days remaining (null = never expires)

Error Codes

Status	Description
401	API Key missing or invalid

API Key

POST /public/translate Free translation (no API Key)

No API Key required. Subject to daily character quota and rate limits.

Request Parameters

Parameter	Type		Description
text	string	Required	Text to translate
lang	string	Optional	Target language code, default: zh

Request Examples

bash

curl -X POST ${BASE_URL}/public/translate \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello, world!","lang":"zh"}'

python

r = requests.post(f"{API_URL}/public/translate",
    json={"text": "Hello, world!", "lang": "zh"})
print(r.json()["translation"])

javascript

const r = await fetch(`${API_URL}/public/translate`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ text: "Hello, world!", lang: "zh" })
});
console.log((await r.json()).translation);

java

var req = HttpRequest.newBuilder()
    .uri(URI.create("${BASE_URL}/public/translate"))
    .header("Content-Type", "application/json")
    .POST(BodyPublishers.ofString("{\"text\":\"Hello, world!\",\"lang\":\"zh\"}"))
    .build();
var resp = client.send(req, HttpResponse.BodyHandlers.ofString());
System.out.println(resp.body());

Success Response

{ "translation": "你好，世界！" }

Error Codes

Status	Description
400	Missing or invalid request parameters
429	Daily quota exhausted or rate limit exceeded
500	Translation failed
503	Free translation is currently disabled

No API Key required

Text

Target Language

GET /public/status Free quota status

Request Examples

bash

curl ${BASE_URL}/public/status

python

r = requests.get(f"{API_URL}/public/status"); print(r.json())

javascript

console.log(await (await fetch(`${API_URL}/public/status`)).json());

java

var resp = client.send(
    HttpRequest.newBuilder().uri(URI.create("${BASE_URL}/public/status")).GET().build(),
    HttpResponse.BodyHandlers.ofString());
System.out.println(resp.body());

Success Response

{ "available": true, "remainingChars": 85000, "dailyLimit": 100000 }

Response Fields

Field	Type	Description
available	boolean	Whether free translation is available now
remainingChars	number	Remaining characters today
dailyLimit	number	Daily character quota

GET /health Service health check

Request Examples

bash

curl ${BASE_URL}/health

javascript

console.log(await (await fetch(`${API_URL}/health`)).json());

Success Response

{ "status": "ok" }

🌐Supported Language Codes

Use these codes for the lang parameter. More languages are supported.

Translation API · Billed by source character count · Fast & Reliable