HF_API_INTEGRATION.md

Integrating external software with the Hugging Face NMT API

Use this when you connect another app (game, mobile app, desktop tool, backend service) to the hosted translator on Hugging Face—not your local machine.

Production endpoint

Item	Value
Base URL	https://marconolimits-nmt.hf.space
Protocol	HTTPS only
Space (dashboard)	huggingface.co/spaces/marconolimits/NMT

All paths below are relative to the base URL (e.g. full health URL: https://marconolimits-nmt.hf.space/healthz).

---

Authentication

If the Space has REQUIRE_API_KEY=1 and secret NMT_API_KEY set in Space settings, every translation request must include:

X-API-Key: <your NMT_API_KEY value>

• GET /healthz does not require a key (use for monitoring).
• GET / (HTML help) does not require a key.
• POST /translate and GET /translate require the key when enforcement is on.

Store the key in environment variables or a secure secret store in your app—never commit it to Git or embed it in public client binaries if you can avoid it.

---

Endpoints

1) Health check

GET /healthz

Response 200: {"status":"ok"}

Use this before showing “translator online” or in uptime checks.

---

2) Translate (recommended: POST + JSON)

POST /translate
Content-Type: application/json
X-API-Key: <optional if enforcement off>

{"text":"Your English sentence here."}

Response 200:

{
  "translation": "Italian text here.",
  "latency_ms": 123.4,
  "request_id": "..."
}

Typical errors

Code	Meaning
401	Missing/wrong X-API-Key
400	Bad body (e.g. missing text, invalid JSON)—body may include hint
413	Text longer than MAX_INPUT_CHARS
504	Translation timed out
415	Unsupported Content-Type for POST

---

3) Translate (GET, short text only)

GET /translate?text=Hello
X-API-Key: <optional if enforcement off>

URL-encode text if it contains spaces or special characters. Prefer POST for long sentences (URL length limits).

---

Minimal examples (copy and adapt)

cURL

curl -sS "https://marconolimits-nmt.hf.space/healthz"

curl -sS -X POST "https://marconolimits-nmt.hf.space/translate" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -d "{\"text\":\"Hello, how are you?\"}"

Python (this repo)

Use the bundled client so JSON and headers stay correct:

from scripts.nmt_client import translate

r = translate(
    "https://marconolimits-nmt.hf.space",
    "Hello, how are you?",
    api_key="YOUR_KEY_HERE",  # omit if API key is disabled on the Space
)
print(r.translation)

C# / .NET (HttpClient)

using var client = new HttpClient { BaseAddress = new Uri("https://marconolimits-nmt.hf.space/") };
client.DefaultRequestHeaders.Add("X-API-Key", "YOUR_KEY_HERE"); // if required

var json = """{"text":"Hello, how are you?"}""";
using var content = new StringContent(json, Encoding.UTF8, "application/json");
var resp = await client.PostAsync("translate", content);
resp.EnsureSuccessStatusCode();
var body = await resp.Content.ReadAsStringAsync();
// Parse JSON: translation, latency_ms, request_id

JavaScript / TypeScript (Node or server)

const res = await fetch("https://marconolimits-nmt.hf.space/translate", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.NMT_API_KEY, // if required
  },
  body: JSON.stringify({ text: "Hello, how are you?" }),
});
const data = await res.json();
// data.translation

---

Calling from a browser (web app)

Browsers enforce CORS. This API does not add permissive CORS headers by default, so direct fetch() from a random website to marconolimits-nmt.hf.space may be blocked.

Recommended: call the API from your backend (same origin as your web app), and have the frontend talk to your backend. Your backend adds X-API-Key and never exposes the key to the browser.

If you must call from the browser only, you may need a proxy or CORS configuration on a server you control—not covered here.

---

Operational notes

• Cold start: Free Spaces can sleep. The first request after idle may take tens of seconds; retries with backoff help.
• HTTPS: Always use https:// (certificate is managed by Hugging Face).
• Limits: Respect MAX_INPUT_CHARS (default 2000 unless changed in Space env).
• Same key everywhere: Use the same NMT_API_KEY value you configured in the Space Variables and secrets panel.

---

Checklist for a new integration

1. Confirm the Space is Running on the Space page.
2. Confirm NMT_API_KEY / REQUIRE_API_KEY in Space settings match what your app sends.
3. Implement POST /translate with Content-Type: application/json and body {"text":"..."}.
4. Send X-API-Key when enforcement is on.
5. Parse JSON response fields translation, latency_ms, request_id.
6. For production web UIs, prefer backend-to-Hugging Face, not browser-to-Hugging Face, unless you have solved CORS and key secrecy.

For Space-specific Git push and env setup, see HUGGINGFACE_SPACES.md.