Skip to content

Translate text

Translates one plain-text string. HTML is translated by POST /html.

POSThttps://edge.harktranslate.com/api/v1/translator/text

Request

Send JSON (Content-Type: application/json). Form-encoded bodies are also accepted. Authenticate with the x-hark-key header.

Request fields
FieldTypeRequiredDefaultAllowedDescription
fromstringyesnoneA supported language code. from also accepts auto.Source language code. The value auto asks the service to detect the source.
tostringyesnoneA supported language code. from also accepts auto.Language code to translate into.
textstringyesnone1 to 1,037,299 characters.The string to translate, or the text whose language should be identified.
qualitystringnoauto-latencyliteral, 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.
contextstringnoomittedAn optional string. No values are published.Optional content register. Omit it to use the default register.
glossaryarray of { source: string, target: string }noomittedUp 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_translatestring[]noomittedUp 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.

Response fields
FieldTypeDescription
transstringTranslated text, in the same order as the input when the input is a list.
source_language_codestringDetected source language code.
source_languagestringDetected source language name.
trust_levelnumberHow confident detection was.
dictobject or nullDictionary data when any was returned.
meta.qualitystringThe quality the request sent, or auto-latency when it sent none.
meta.gradestringGrade of the answer that was served: literal, nmt or llm.
meta.degraded_segmentsnumberHow many protected parts of the answer could not be restored.
{
  "trans": "...",
  "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.

Plain text

curl
curl -X POST "https://edge.harktranslate.com/api/v1/translator/text" \
  -H "x-hark-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "from": "en",
  "to": "vi",
  "text": "Hello"
}
JSON
JavaScript
const response = await fetch("https://edge.harktranslate.com/api/v1/translator/text", {
  method: "POST",
  headers: {
    "x-hark-key": process.env.HARK_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "from": "en",
    "to": "vi",
    "text": "Hello"
  }),
});

if (!response.ok) {
  throw new Error(`Hark responded ${response.status}`);
}

console.log(await response.json());
Python
import os
import requests

response = requests.post(
    "https://edge.harktranslate.com/api/v1/translator/text",
    headers={"x-hark-key": os.environ["HARK_API_KEY"]},
    json={
        "from": "en",
        "to": "vi",
        "text": "Hello",
    },
    timeout=30,
)
response.raise_for_status()
print(response.json())

Strict LLM grade

curl
curl -X POST "https://edge.harktranslate.com/api/v1/translator/text" \
  -H "x-hark-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "from": "en",
  "to": "vi",
  "text": "Hello",
  "quality": "llm"
}
JSON
JavaScript
const response = await fetch("https://edge.harktranslate.com/api/v1/translator/text", {
  method: "POST",
  headers: {
    "x-hark-key": process.env.HARK_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "from": "en",
    "to": "vi",
    "text": "Hello",
    "quality": "llm"
  }),
});

if (!response.ok) {
  throw new Error(`Hark responded ${response.status}`);
}

console.log(await response.json());
Python
import os
import requests

response = requests.post(
    "https://edge.harktranslate.com/api/v1/translator/text",
    headers={"x-hark-key": os.environ["HARK_API_KEY"]},
    json={
        "from": "en",
        "to": "vi",
        "text": "Hello",
        "quality": "llm",
    },
    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 /textGlossary keeps brand names

Request
{
  "from": "en",
  "to": "de",
  "text": "Ship the Northwind order today.",
  "glossary": [
    {
      "source": "Northwind",
      "target": "Northwind"
    }
  ]
}
Response
{
  "trans": "Versenden Sie die Northwind-Bestellung noch heute."
}

Status codes and machine codes are listed on the error catalog, including 200, 202, 400, 401, 403, 404, 413, 429, and 503.