Oxygen Translation API

Rövid összefoglaló

A szolgáltatás célja, hogy a lehető legegyszerűbben lehessen fordítást kérni. Nincs szükség a háttérrendszer ismeretére, elég elküldeni egy JSON body-t a POST /api/translate végpontra, és a szolgáltatás visszaadja ugyanazt a tartalmat a beállított célnyelveken.

A működés lépésről lépésre:

• A kliens elküldi a JSON body-t és a Bearer tokent.
• A szolgáltatás ellenőrzi a tokent és a bemeneti adatot.
• A szolgáltatás egységes belső szerkezetre alakítja a kérést.
• Az AI háttér elkészíti az összes fordítást.
• A válasz egységes JSON formában érkezik vissza a source és translations blokkokkal.

Végpontok

Hitelesítés

A POST /api/translate végpont Bearer tokennel védett.

Authorization: Bearer <TRANSLATE_API_TOKEN>

A hívó félnek semmilyen AI kulcsot vagy háttérmodellt nem kell ismernie. A technikai metaadatok csak admin tokennel látszanak.

Gyors indítás

Ha valaki a legrövidebb úton akarja integrálni:

1. Küldjön egy POST kérést ide: https://oxygen-translate.datalight.hu/api/translate
2. Adja át a Bearer tokent az Authorization headerben.
3. Küldjön JSON body-t, amiben van legalább content vagy text.
4. A fordításokat a válasz translations.en, translations.ro, translations.sk, translations.es, translations.de, translations.uk ágaiban kapja meg.

Támogatott bemeneti formátumok

A szolgáltatás többféle bemenetet fogad el, hogy ne kelljen minden rendszert pontosan ugyanarra a JSON szerkezetre átállítani.

1. Minimális szövegkérés

A legegyszerűbb forma, ha csak sima szöveg áll rendelkezésre.

{
  "text": "Ide jön a szöveg.",
  "language": "hu"
}

2. Egyszerű, lapos content objektum

A content önmagában is elég; a title és a facebook_title opcionális.

{
  "content": "Itt jön a teljes fordítandó szöveg.",
  "language": "hu"
}

3. Beágyazott item objektum

Ez jó akkor, ha a küldő rendszer már eleve objektumként kezeli a cikket vagy rekordot.

{
  "item": {
    "title": "Magyar cím",
    "facebook_title": "Magyar Facebook cím",
    "content": "A teljes magyar szöveg itt jön...",
    "language": "hu",
    "source_name": "Példa forrás",
    "source_url": "https://pelda.hu/cikk",
    "published_at": "2026-03-25T10:00:00Z"
  }
}

Mezőszintű szabályok

A szolgáltatás a fordítandó szöveget ebben a sorrendben keresi:

1. item.content
2. content
3. text

A forrásnyelvet ebben a sorrendben keresi:

1. source_language
2. item.language
3. language
4. ha egyik sincs: auto

Alap limitértékek:

• title: maximum 320 karakter
• facebook_title: maximum 320 karakter
• content: maximum 12000 karakter
• teljes HTTP body: maximum 65536 byte
• napi AI keret: az ingyenes Cloudflare AI napi Neuron keretéhez igazítva
• egy kérés AI kerete: az ingyenes Cloudflare AI napi Neuron keretéhez igazítva

Mi történik a kérés után?

A szolgáltatás minden kérést ugyanarra a belső szerkezetre alakít. Ezután csak a title, facebook_title és content mezőket küldi tovább fordításra. A metaadatok nem módosulnak.

Fontos szabályok:

• A rendszer nem rövidít, nem foglal össze és nem ír át szerkesztői stílusban.
• A rendszer a jelentést, a bekezdéseket, a neveket, a számokat és az URL-eket megőrzi.
• Ha a forrásnyelv megegyezik valamelyik célnyelvvel, arra a nyelvre az eredeti szöveg változatlanul visszajöhet.
• A válaszban mindig minden beállított célnyelv szerepel.
• Az AI hívás napi és kérésenkénti Neuron keretből megy; ha a keret elfogy vagy a kérés átlépné, a szolgáltatás 429-et ad.

Sikeres válasz szerkezete

A sikeres válasz három fő részből áll:

• source: a validált és normalizált eredeti bemenet
• translations: a beállított célnyelvek fordításai
• meta: kísérő adatok, például modell és kérésazonosító

{
  "ok": true,
  "source": {
    "title": "Példa cím",
    "facebook_title": "Példa cím",
    "content": "Eredeti szöveg",
    "language": "hu"
  },
  "translations": {
    "en": {
      "title": "Example title",
      "facebook_title": "Example title",
      "content": "Translated English text",
      "language": "en"
    },
    "ro": { "...": "..." },
    "sk": { "...": "..." },
    "es": { "...": "..." },
    "de": { "...": "..." },
    "uk": { "...": "..." }
  }
}

Admin tokennel a válasz meta blokkot is tartalmaz a provider, modell és usage adatokkal.

Hibakezelés

Minden hiba egységes JSON formában jön vissza:

{
  "ok": false,
  "error": {
    "code": "validation_error",
    "message": "item.content or text is required"
  },
  "meta": {
    "request_id": "..."
  }
}

Integrációs példák

cURL minimális példával

curl -X POST "https://oxygen-translate.datalight.hu/api/translate" \
  -H "Authorization: Bearer <TRANSLATE_API_TOKEN>" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "text": "Ez egy magyar minta szöveg.",
  "language": "hu"
}
JSON

cURL cím + content példával

curl -X POST "https://oxygen-translate.datalight.hu/api/translate" \
  -H "Authorization: Bearer <TRANSLATE_API_TOKEN>" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "title": "Példa cím",
  "facebook_title": "Példa cím",
  "content": "Ez a teljes fordítandó szöveg.",
  "language": "hu"
}
JSON

JavaScript / Node.js

const response = await fetch("https://oxygen-translate.datalight.hu/api/translate", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_TRANSLATE_API_TOKEN",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "Példa cím",
    facebook_title: "Példa cím",
    content: "Ez a teljes fordítandó szöveg.",
    language: "hu"
  }),
});

const data = await response.json();
if (!response.ok || !data.ok) {
  throw new Error(data?.error?.message || "A fordítás nem sikerült");
}

console.log(data.translations.en.content);

Python

import requests

payload = {
    "text": "Ez egy magyar szöveg.",
    "language": "hu",
}

response = requests.post(
    "https://oxygen-translate.datalight.hu/api/translate",
    headers={
        "Authorization": "Bearer YOUR_TRANSLATE_API_TOKEN",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=60,
)

data = response.json()
if response.status_code != 200 or not data.get("ok"):
    raise RuntimeError(data.get("error", {}).get("message", "A fordítás nem sikerült"))

print(data["translations"]["de"]["content"])

PHP

<?php
$payload = [
    "text" => "Ez egy magyar szöveg.",
    "language" => "hu",
];

$ch = curl_init("https://oxygen-translate.datalight.hu/api/translate");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer YOUR_TRANSLATE_API_TOKEN",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode($payload, JSON_UNESCAPED_UNICODE),
]);

$raw = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($raw, true);

Megjegyzések

• Csak a title, facebook_title és content mező fordul.
• A metaadatok, például source_name, source_url, published_at változatlanul továbbmennek.
• A szolgáltatás fordítási előzményt nem tárol; csak napi Cloudflare AI Neuron és OpenAI tokenhasználati számlálót vezet.
• Hibánál a kliensnek érdemes a meta.request_id értéket naplózni.
• Ha gépi leírásra is szükség van, az OpenAPI változat elérhető a /openapi.json útvonalon.