# Translate API — free, keyless machine translation & text-to-speech powered by Google Translate: translate text into 130+ languages (single or MULTI-target in one call), turn text into spoken MP3 audio (text-to-speech / TTS) in any language, auto-detect the source language, and look up word-level dictionary meanings, synonyms and transliteration. Works with every script (Chinese, Japanese, Arabic, Cyrillic, Hindi). No API key, no Google Cloud project required.

> Translate text into a single target language. Auto-detects the source by default and returns the detected language + confidence. Supports every script.
> ReefAPI engine `translate` · 7 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/translate/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /translate/v1/translate — 1 credit
Translate text into a single target language. Auto-detects the source by default and returns the detected language + confidence. Supports every script.

**Parameters:**
- `text` (string, required) — The text to translate. Plain UTF-8 — any script works (Latin, Chinese, Japanese, Arabic, Cyrillic…). Up to 5000 characters per call; longer input is truncated and flagged in meta.truncated.
- `target` (enum, required) — Target language code to translate INTO (e.g. 'es', 'fr', 'ja', 'ar'). Must be one of the supported codes (see the 'languages' action). Friendly aliases like 'zh' or 'he' are accepted. [one of: af, sq, am, ar, hy, as, ay, az, bm, eu, be, bn, bho, bs, bg, ca, ceb, ny, zh-CN, zh-TW, co, hr, cs, da, dv, doi, nl, en, eo, et, ee, tl, fi, fr, fy, gl, ka, de, el, gn, gu, ht, ha, haw, iw, hi, hmn, hu, is, ig, ilo, id, ga, it, ja, jw, kn, kk, km, rw, gom, ko, kri, ku, ckb, ky, lo, la, lv, ln, lt, lg, lb, mk, mai, mg, ms, ml, mt, mi, mr, mni-Mtei, lus, mn, my, ne, no, or, om, ps, fa, pl, pt, pa, qu, ro, ru, sm, sa, gd, nso, sr, st, sn, sd, si, sk, sl, so, es, su, sw, sv, tg, ta, tt, te, th, ti, ts, tr, tk, ak, uk, ur, ug, uz, vi, cy, xh, yi, yo, zu]
- `source` (string, optional, default "auto") — Source language code (ISO-639-style, e.g. 'en', 'de', 'zh-CN'). Defaults to 'auto' — the language is detected automatically and returned as detected_source. See the 'languages' action for codes.

**Returns:** text (translated), source_text, source (used/detected), target, detected_source, detection_confidence, source_language_name, target_language_name

**Example request body:**
```json
{
  "text": "Hello, how are you?",
  "target": "es"
}
```

### POST /translate/v1/translate_multi — 1 credit
Translate the SAME text into MANY target languages in a single call — the multi-target differentiator. Pass up to 60 target codes; returns a translation for each, fanned out concurrently (≈15× faster than calling translate per language).

**Parameters:**
- `text` (string, required) — The text to translate. Plain UTF-8 — any script works (Latin, Chinese, Japanese, Arabic, Cyrillic…). Up to 5000 characters per call; longer input is truncated and flagged in meta.truncated.
- `targets` (array, required) — List of target language codes to translate the SAME text into, in ONE call (e.g. ['es','fr','de','ja','ar']). Accepts a JSON array or a comma-separated string. Up to 60 targets; unknown codes are rejected (never silently skipped).
- `source` (string, optional, default "auto") — Source language code (ISO-639-style, e.g. 'en', 'de', 'zh-CN'). Defaults to 'auto' — the language is detected automatically and returned as detected_source. See the 'languages' action for codes.

**Returns:** source_text, source, detected_source, translations{code:{text, language_name}}, errors{code:reason} (per-target), count

**Example request body:**
```json
{
  "text": "The weather is beautiful today.",
  "targets": [
    "es",
    "fr",
    "de",
    "ja",
    "ar"
  ]
}
```

### POST /translate/v1/translate_batch — 1 credit
Translate MANY strings into ONE target language in a single call — built for catalogue work (product titles, spec values, category names). Send up to 500 strings as an array and get an array back in the SAME order, index for index. Costs ONE upstream call regardless of how many strings you send, so a 500-title page is one request instead of 500. Items the upstream could not translate are listed in `failed[]` with a reason and come back as text:null — never as an empty string and never silently dropped.

**Parameters:**
- `texts` (array, required) — The strings to translate, as a JSON array — e.g. a page of product titles or spec values. Order is preserved: result[i] always corresponds to texts[i]. Up to 500 items and 100000 characters total per call, 5000 characters per item. NOTE: pass a real JSON array. A bare string is split on commas (gateway-wide behaviour for array parameters), which would cut a title like 'Trainers, size 42' into two items.
- `target` (enum, required) — Target language code to translate INTO (e.g. 'es', 'fr', 'ja', 'ar'). Must be one of the supported codes (see the 'languages' action). Friendly aliases like 'zh' or 'he' are accepted. [one of: af, sq, am, ar, hy, as, ay, az, bm, eu, be, bn, bho, bs, bg, ca, ceb, ny, zh-CN, zh-TW, co, hr, cs, da, dv, doi, nl, en, eo, et, ee, tl, fi, fr, fy, gl, ka, de, el, gn, gu, ht, ha, haw, iw, hi, hmn, hu, is, ig, ilo, id, ga, it, ja, jw, kn, kk, km, rw, gom, ko, kri, ku, ckb, ky, lo, la, lv, ln, lt, lg, lb, mk, mai, mg, ms, ml, mt, mi, mr, mni-Mtei, lus, mn, my, ne, no, or, om, ps, fa, pl, pt, pa, qu, ro, ru, sm, sa, gd, nso, sr, st, sn, sd, si, sk, sl, so, es, su, sw, sv, tg, ta, tt, te, th, ti, ts, tr, tk, ak, uk, ur, ug, uz, vi, cy, xh, yi, yo, zu]
- `source` (string, optional, default "auto") — Source language code (ISO-639-style, e.g. 'en', 'de', 'zh-CN'). Defaults to 'auto' — the language is detected automatically and returned as detected_source. See the 'languages' action for codes.

**Returns:** translations[]{index, source_text, text (null if it failed), detected_source}, failed[]{index, reason}, count, requested, failed_count, target, target_language_name, source, detected_source

**Example request body:**
```json
{
  "texts": [
    "Wireless Bluetooth Headphones",
    "Stainless Steel Water Bottle 1L",
    "Men's Running Shoes, Size 42",
    "Organic Green Tea, 100 bags",
    "4K Ultra HD Smart TV 55 inch"
  ],
  "target": "es"
}
```

### POST /translate/v1/detect — 1 credit
Detect the language of a piece of text. Returns the detected language code, its name and a confidence score (0-1). Works on any script.

**Parameters:**
- `text` (string, required) — The text to translate. Plain UTF-8 — any script works (Latin, Chinese, Japanese, Arabic, Cyrillic…). Up to 5000 characters per call; longer input is truncated and flagged in meta.truncated.

**Returns:** detected_source (code), language_name, confidence (0-1), is_reliable

**Example request body:**
```json
{
  "text": "Привет мир"
}
```

### POST /translate/v1/dictionary — 1 credit
Word-level dictionary lookup: translate a word/short phrase and get its meanings grouped by part of speech, synonyms, back-translations and transliteration (romanization). Best for single words or short phrases.

**Parameters:**
- `text` (string, required) — A word or short phrase to look up.
- `target` (enum, required) — Target language code to translate INTO (e.g. 'es', 'fr', 'ja', 'ar'). Must be one of the supported codes (see the 'languages' action). Friendly aliases like 'zh' or 'he' are accepted. [one of: af, sq, am, ar, hy, as, ay, az, bm, eu, be, bn, bho, bs, bg, ca, ceb, ny, zh-CN, zh-TW, co, hr, cs, da, dv, doi, nl, en, eo, et, ee, tl, fi, fr, fy, gl, ka, de, el, gn, gu, ht, ha, haw, iw, hi, hmn, hu, is, ig, ilo, id, ga, it, ja, jw, kn, kk, km, rw, gom, ko, kri, ku, ckb, ky, lo, la, lv, ln, lt, lg, lb, mk, mai, mg, ms, ml, mt, mi, mr, mni-Mtei, lus, mn, my, ne, no, or, om, ps, fa, pl, pt, pa, qu, ro, ru, sm, sa, gd, nso, sr, st, sn, sd, si, sk, sl, so, es, su, sw, sv, tg, ta, tt, te, th, ti, ts, tr, tk, ak, uk, ur, ug, uz, vi, cy, xh, yi, yo, zu]
- `source` (string, optional, default "auto") — Source language code (ISO-639-style, e.g. 'en', 'de', 'zh-CN'). Defaults to 'auto' — the language is detected automatically and returned as detected_source. See the 'languages' action for codes.

**Returns:** text (primary translation), transliteration, source, target, detected_source, dictionary[]{part_of_speech, translations[]{term, synonyms[], score}}

**Example request body:**
```json
{
  "text": "run",
  "target": "es"
}
```

### POST /translate/v1/languages — 0 credits
List all supported languages (code → English name). Useful to populate a language picker or validate a code before translating.

**Parameters:** none

**Returns:** languages[]{code, name}, count

### POST /translate/v1/speak — 1 credit
Text-to-speech: turn text into spoken audio (MP3). Pronounces the text in the chosen language's voice/accent — works with every script (Chinese, Japanese, Arabic, Cyrillic, Turkish…). Long text is split and joined into a single MP3. Returns the audio base64-encoded inline (audio/mpeg), so no second download is needed. Pair it with 'translate' to get spoken translations.

**Parameters:**
- `text` (string, required) — The text to speak aloud. Plain UTF-8 — any script works (Latin, Chinese, Japanese, Arabic, Cyrillic…). Up to 3000 characters; longer text is split into chunks and the audio is joined into one MP3. Longer input than that is truncated and flagged in meta.truncated.
- `lang` (enum, required) — Language to pronounce the text in (e.g. 'en', 'es', 'ja', 'tr', 'ar'). Determines the voice/accent. Must be a supported code (see the 'languages' action). Friendly aliases like 'zh' or 'he' are accepted. [one of: af, sq, am, ar, hy, as, ay, az, bm, eu, be, bn, bho, bs, bg, ca, ceb, ny, zh-CN, zh-TW, co, hr, cs, da, dv, doi, nl, en, eo, et, ee, tl, fi, fr, fy, gl, ka, de, el, gn, gu, ht, ha, haw, iw, hi, hmn, hu, is, ig, ilo, id, ga, it, ja, jw, kn, kk, km, rw, gom, ko, kri, ku, ckb, ky, lo, la, lv, ln, lt, lg, lb, mk, mai, mg, ms, ml, mt, mi, mr, mni-Mtei, lus, mn, my, ne, no, or, om, ps, fa, pl, pt, pa, qu, ro, ru, sm, sa, gd, nso, sr, st, sn, sd, si, sk, sl, so, es, su, sw, sv, tg, ta, tt, te, th, ti, ts, tr, tk, ak, uk, ur, ug, uz, vi, cy, xh, yi, yo, zu]
- `slow` (boolean, optional, default false) — Speak slowly (useful for language learning / clear pronunciation). Defaults to false (normal speed).

**Returns:** audio_base64 (MP3, base64), mime (audio/mpeg), format ('mp3'), lang, language_name, char_count, segments, duration_estimate_seconds, audio_bytes, slow

**Example request body:**
```json
{
  "text": "Hello, how are you today?",
  "lang": "en"
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=translate
- Human docs page: https://reefapi.com/docs/translate
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt