POSThttps://edge.harktranslate.com/api/v1/translator/json
Request
Send JSON (Content-Type: application/json). Form-encoded bodies are also accepted. Authenticate with the x-hark-key header.
| Field | Type | Required | Default | Allowed | Description |
|---|---|---|---|---|---|
| from | string | yes | none | A supported language code. from also accepts auto. | Source language code. The value auto asks the service to detect the source. |
| to | string | yes | none | A supported language code. from also accepts auto. | Language code to translate into. |
| quality | string | no | auto-latency | literal, nmt, llm, auto-llm, auto-latency. Case-insensitive. | The grade of answer you accept. llm, nmt and literal serve only that grade and respond 503 when it cannot be served. auto-latency (the default) returns the fastest answer of any grade. auto-llm prefers an LLM answer and returns the fastest other answer when the LLM one is late. meta.grade reports what actually served. |
| context | string | no | omitted | An optional string. No values are published. | Optional content register. Omit it to use the default register. |
| protected_paths | string[] | no | empty | An array of path strings. Omitted is treated as empty. | Dot paths whose values are not translated. |
| common_protected_paths | string[] | no | empty | An array of key names. Omitted is treated as empty. | Key names left untranslated at every nesting level. |
| json | object or JSON string | yes | none | A JSON object or array, or a string that parses as one. | String values are translated. Keys, numbers, booleans, and null stay as sent. |
| glossary | array of { source: string, target: string } | no | omitted | Up to 50 entries, shared with do_not_translate. Each source and target is 1 to 256 characters, unique by source, with no control characters. | Replaces each source term with its target after translation. Omitted or empty leaves the text unchanged. |
| do_not_translate | string[] | no | omitted | Up to 50 terms combined with glossary. Each term is 1 to 256 characters, unique, and not equal to a glossary source. | Terms copied through unchanged. Omitted or empty leaves the text unchanged. |
Response
Success is HTTP 200.
| Field | Type | Description |
|---|---|---|
| trans | object or array | Translated text, in the same order as the input when the input is a list. |
| meta.quality | string | The quality the request sent, or auto-latency when it sent none. |
| meta.grade | string | Grade of the answer that was served: literal, nmt or llm. |
| meta.degraded_segments | number | How many protected parts of the answer could not be restored. |
{
"trans": { "title": "...", "id": "keep-me" },
"meta": {
"quality": "auto-latency",
"grade": "llm",
"degraded_segments": 0
}
}Samples
Replace YOUR_API_KEY or set HARK_API_KEY. The samples call https://edge.harktranslate.com/api/v1/translator.
JSON object
curl -X POST "https://edge.harktranslate.com/api/v1/translator/json" \
-H "x-hark-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
--data-binary @- <<'JSON'
{
"from": "en",
"to": "vi",
"json": {
"title": "Hello",
"id": "keep-me"
},
"protected_paths": [
"id"
]
}
JSONconst response = await fetch("https://edge.harktranslate.com/api/v1/translator/json", {
method: "POST",
headers: {
"x-hark-key": process.env.HARK_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
"from": "en",
"to": "vi",
"json": {
"title": "Hello",
"id": "keep-me"
},
"protected_paths": [
"id"
]
}),
});
if (!response.ok) {
throw new Error(`Hark responded ${response.status}`);
}
console.log(await response.json());import os
import requests
response = requests.post(
"https://edge.harktranslate.com/api/v1/translator/json",
headers={"x-hark-key": os.environ["HARK_API_KEY"]},
json={
"from": "en",
"to": "vi",
"json": {
"title": "Hello",
"id": "keep-me",
},
"protected_paths": [
"id",
],
},
timeout=30,
)
response.raise_for_status()
print(response.json())Request and response transcripts
One example for this endpoint, written into the page so you can read it without running a request.
POST /jsonProtected JSON paths
Request
{
"from": "en",
"to": "ja",
"json": {
"cart": {
"title": "Your cart",
"empty": "Your cart is empty.",
"checkout": "Proceed to checkout"
},
"brand": "Northwind",
"errors": [
"Card declined",
"Address is required"
]
},
"protected_paths": [
"brand"
]
}Response
{
"trans": {
"cart": {
"title": "あなたのカート",
"empty": "カートは空です。",
"checkout": "チェックアウトに進む"
},
"brand": "Northwind",
"errors": [
"カードが拒否されました",
"住所は必須です"
]
}
}Status codes and machine codes are listed on the error catalog, including 200, 202, 400, 401, 403, 404, 413, 429, and 503.