Skip to content

Translate many strings

Translates a list of plain-text strings in one request. Order and length are preserved.

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

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.
textsstring[]yesnone1 to 128 strings. Each string is at most 1,037,299 characters.Plain-text strings translated in order. The response array has the same length and order.
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
transstring[]Translated text, in the same order as the input when the input is a list.
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": "nmt",
    "degraded_segments": 0
  }
}

Samples

Replace YOUR_API_KEY or set HARK_API_KEY. The samples call https://edge.harktranslate.com/api/v1/translator.

Batch

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

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/texts",
    headers={"x-hark-key": os.environ["HARK_API_KEY"]},
    json={
        "from": "en",
        "to": "vi",
        "texts": [
            "Hello",
            "Goodbye",
        ],
    },
    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 /textsCheckout strings

Request
{
  "from": "en",
  "to": "ja",
  "texts": [
    "Add SKU to cart",
    "Your cart is empty."
  ],
  "do_not_translate": [
    "SKU"
  ]
}
Response
{
  "trans": [
    "SKUをカートに追加",
    "カートは空です。"
  ]
}

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