Translate a string or a batch into one target language

POST /v1/translate

Returns one translation per input string, in input order, each carrying where it sits on the review ladder and whether it came from your memory rather than an engine — plus a usage block of REAL counts (strings, cached, translated, and the source characters that actually reached an engine). Send text for one string or batch for many, never both. When you name no source, the detected one is reported back.

THE TRANSLATION MEMORY IS CONSULTED FIRST AND IT IS NORMATIVE, NOT A CACHE. Every string keys on (source text, target, glossary version, tier); a hit is returned VERBATIM and never re-translated, which is what makes a locale rebuild idempotent under a non-deterministic model and the bill proportional to what actually changed. Misses go to the engine and are written back at state machine. Editing a glossary term changes the key, so a stale rendering can never be served.

IT CANNOT TRAMPLE REVIEWED WORK. A write from this route may create an entry or refresh one still at machine, and nothing else — a string a human moved to approved or published through the memory review lane survives every rebuild, and comes back here unchanged. The memory is the caller's OWN org's, a separate store per org: the source text you send is customer content and lands nowhere else. Read it back or review it at /v1/translate/memory.

tier picks the engine and defaults to quality — the model plane, which carries context, terminology and tone, and which bills its own tokens, so nothing is charged twice here. bulk is the high-volume engine and is metered HERE, on the source characters that reached it: a fully-cached rebuild reports zero characters and costs zero. BULK NEVER FALLS BACK TO QUALITY — on a deployment that does not serve it the answer is 503 for that tier, so a caller is never quietly served, or charged, at a tier it did not ask for. A bulk request beyond its balance is refused with the nested {"error":{"code","message"}} body at 402/503.

target IS CHECKED FOR SHAPE, NOT FOR SUPPORT: anything BCP-47-shaped is accepted (es, pt-BR), anything else is 400. There is no unsupported-language error — a well-formed tag no engine can actually render is passed straight through, and whatever comes back is what gets stored and returned. format (text, html, markdown) tells the engine what markup to preserve; glossary fixes terms verbatim.

Requires a validated principal — 401 without one, and the org is always that principal's. At most 512 strings per call and 32768 characters per string; an engine that fails or answers a reply that does not cover every input is 502, and nothing is stored.

Request

The document declares no body for POST /v1/translate. The handler is typed in cloud but its shape is not yet emitted, so the fields are not listed here — ask the MCP door's describe for post_translate, which answers from the running route.

Response

The document declares no response body for this operation. It answers 200 on success and the platform error shape on failure — see Errors.

Examples

hanzo translate create

import { Configuration, TranslateApi } from 'hanzoai';

const api = new TranslateApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.postTranslate();

from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import TranslateApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = TranslateApi(client).post_translate()

cfg := cloud.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := cloud.NewAPIClient(cfg)

resp, _, err := client.TranslateAPI.PostTranslate(context.Background()).Execute()
if err != nil {
	return err
}

use hanzo_cloud::apis::{configuration::Configuration, translate_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = translate_api::post_translate(&cfg, Default::default()).await?;

import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.TranslateApi;

ApiClient client = new ApiClient();
client.setRequestInterceptor(b -> b.header("Authorization", "Bearer " + System.getenv("HANZO_API_KEY")));

var result = new TranslateApi(client).postTranslate();

curl -X POST https://api.hanzo.ai/v1/translate \
  -H "Authorization: Bearer $HANZO_API_KEY"

curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "get_translate_memory"
         }
       }
     }'

Translate API · All Hanzo APIs · Interactive reference