Authentication

All API requests (except demo endpoints) require an API key. Three authentication methods are supported — all are equivalent:

Method 1: Authorization Bearer Header (Recommended)

curl -X POST https://api.socketsio.com/v1/translate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "Hello", "target": "zh"}'

Method 2: X-API-Key Header

curl -X POST https://api.socketsio.com/v1/translate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "Hello", "target": "zh"}'

Method 3: Query Parameter

curl -X POST "https://api.socketsio.com/v1/translate?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "Hello", "target": "zh"}'

Get your free API key at socketsio.com/signup — 500,000 characters/month free, no credit card required.

Plans

Plan	Price	Characters/Month	Rate Limit
Free	$0	500,000	10 req/min
Basic	$9/mo	5,000,000	60 req/min
Pro	$29/mo	50,000,000	300 req/min

Translate Text

Request Body

Parameter	Type	Required	Description
q	string | string[]	required	Text(s) to translate
target	string	required	Target language code (e.g. "zh", "es", "ja")
source	string	optional	Source language code. Auto-detected if omitted.
format	string	optional	"text" (default) or "html"

Example — Single Text

curl -X POST https://api.socketsio.com/v1/translate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "Hello, how are you?",
    "target": "es"
  }'

Response

{
  "data": {
    "translations": [
      {
        "translatedText": "Hola, ¿cómo estás?",
        "detectedSourceLanguage": "en",
        "input": "Hello, how are you?"
      }
    ]
  }
}

Example — Batch Translation

curl -X POST https://api.socketsio.com/v1/translate \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": ["Good morning", "Thank you", "Goodbye"],
    "target": "ja"
  }'

Python

from socketsio import SocketsIO

client = SocketsIO(api_key="YOUR_API_KEY")
result = client.translate("Hello world", target="zh")
print(result.text)  # "你好世界"

# Batch
results = client.translate(["Hello", "Goodbye"], target="es")
for r in results:
    print(r.text)

JavaScript

import { SocketsIO } from 'socketsio';

const client = new SocketsIO({ apiKey: 'YOUR_API_KEY' });
const result = await client.translate('Hello world', { target: 'zh' });
console.log(result.text); // "你好世界"

PHP

<?php
$ch = curl_init('https://api.socketsio.com/v1/translate');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer YOUR_API_KEY',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'q'      => 'Hello, world!',
        'target' => 'zh',
    ]),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $response['data']['translations'][0]['translatedText']; // 你好，世界！
?>

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    body, _ := json.Marshal(map[string]string{
        "q":      "Hello, world!",
        "target": "zh",
    })
    req, _ := http.NewRequest("POST", "https://api.socketsio.com/v1/translate", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    translations := result["data"].(map[string]interface{})["translations"].([]interface{})
    fmt.Println(translations[0].(map[string]interface{})["translatedText"]) // 你好，世界！
}

Bulk Translate

Request Body

Parameter	Type	Required	Description
q	string[]	required	Array of texts to translate (max 128 items)
target	string	required	Target language code (e.g. "zh", "es", "ja")
source	string	optional	Source language code. Auto-detected if omitted.
format	string	optional	"text" (default) or "html"

cURL

curl -X POST https://api.socketsio.com/v1/translate/bulk \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "q": ["Good morning", "Thank you", "Goodbye", "How are you?"],
    "target": "ja"
  }'

Response

{
  "data": {
    "translations": [
      { "translatedText": "おはようございます", "detectedSourceLanguage": "en", "input": "Good morning" },
      { "translatedText": "ありがとうございます", "detectedSourceLanguage": "en", "input": "Thank you" },
      { "translatedText": "さようなら", "detectedSourceLanguage": "en", "input": "Goodbye" },
      { "translatedText": "お元気ですか？", "detectedSourceLanguage": "en", "input": "How are you?" }
    ]
  }
}

Python

import requests

response = requests.post(
    "https://api.socketsio.com/v1/translate/bulk",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "q": ["Good morning", "Thank you", "Goodbye"],
        "target": "ja"
    }
)
for t in response.json()["data"]["translations"]:
    print(t["translatedText"])

JavaScript

const res = await fetch("https://api.socketsio.com/v1/translate/bulk", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    q: ["Good morning", "Thank you", "Goodbye"],
    target: "ja"
  })
});
const { data } = await res.json();
data.translations.forEach(t => console.log(t.translatedText));

PHP

<?php
$ch = curl_init('https://api.socketsio.com/v1/translate/bulk');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer YOUR_API_KEY',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'q'      => ['Good morning', 'Thank you', 'Goodbye'],
        'target' => 'ja',
    ]),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
foreach ($response['data']['translations'] as $t) {
    echo $t['translatedText'] . "\n";
}
?>

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    body, _ := json.Marshal(map[string]interface{}{
        "q":      []string{"Good morning", "Thank you", "Goodbye"},
        "target": "ja",
    })
    req, _ := http.NewRequest("POST", "https://api.socketsio.com/v1/translate/bulk", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    translations := result["data"].(map[string]interface{})["translations"].([]interface{})
    for _, t := range translations {
        fmt.Println(t.(map[string]interface{})["translatedText"])
    }
}

Detect Language

Request Body

Parameter	Type	Required	Description
q	string | string[]	required	Text(s) to detect

cURL

curl -X POST https://api.socketsio.com/v1/detect \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "Bonjour le monde"}'

Response

{
  "data": {
    "detections": [
      {
        "language": "fr",
        "confidence": 1.0,
        "isReliable": true,
        "input": "Bonjour le monde"
      }
    ]
  }
}

Python

import requests

response = requests.post(
    "https://api.socketsio.com/v1/detect",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"q": "Bonjour le monde"}
)
detection = response.json()["data"]["detections"][0]
print(detection["language"], detection["confidence"])  # fr 1.0

JavaScript

const res = await fetch("https://api.socketsio.com/v1/detect", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ q: "Bonjour le monde" })
});
const { data } = await res.json();
console.log(data.detections[0].language); // "fr"

PHP

<?php
$ch = curl_init('https://api.socketsio.com/v1/detect');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer YOUR_API_KEY',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['q' => 'Bonjour le monde']),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
$detection = $response['data']['detections'][0];
echo $detection['language'] . ' (' . $detection['confidence'] . ')'; // fr (1)
?>

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    body, _ := json.Marshal(map[string]string{"q": "Bonjour le monde"})
    req, _ := http.NewRequest("POST", "https://api.socketsio.com/v1/detect", bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()

    var result map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    detections := result["data"].(map[string]interface{})["detections"].([]interface{})
    d := detections[0].(map[string]interface{})
    fmt.Println(d["language"], d["confidence"]) // fr 1
}

Supported Languages

cURL

curl https://api.socketsio.com/v1/languages

Response

{
  "data": {
    "languages": [
      { "language": "af", "name": "Afrikaans" },
      { "language": "sq", "name": "Albanian" },
      { "language": "am", "name": "Amharic" },
      ...
    ]
  }
}

Language Code Reference

All 195 supported language codes (ISO 639-1 / BCP-47):

Code	Language	Code	Language	Code	Language
af	Afrikaans	ak	Akan	sq	Albanian
am	Amharic	ar	Arabic	hy	Armenian
as	Assamese	ay	Aymara	az	Azerbaijani
bm	Bambara	eu	Basque	be	Belarusian
bn	Bengali	bho	Bhojpuri	bs	Bosnian
bg	Bulgarian	ca	Catalan	ceb	Cebuano
zh-CN	Chinese (Simplified)	zh-TW	Chinese (Traditional)	co	Corsican
hr	Croatian	cs	Czech	da	Danish
dv	Dhivehi	doi	Dogri	nl	Dutch
en	English	eo	Esperanto	et	Estonian
ee	Ewe	fil	Filipino	fi	Finnish
fr	French	fy	Frisian	gl	Galician
ka	Georgian	de	German	el	Greek
gn	Guarani	gu	Gujarati	ht	Haitian Creole
ha	Hausa	haw	Hawaiian	he	Hebrew
hi	Hindi	hmn	Hmong	hu	Hungarian
is	Icelandic	ig	Igbo	ilo	Ilocano
id	Indonesian	ga	Irish	it	Italian
ja	Japanese	jv	Javanese	kn	Kannada
kk	Kazakh	km	Khmer	rw	Kinyarwanda
gom	Konkani	ko	Korean	kri	Krio
ku	Kurdish (Kurmanji)	ckb	Kurdish (Sorani)	ky	Kyrgyz
lo	Lao	la	Latin	lv	Latvian
ln	Lingala	lt	Lithuanian	lg	Luganda
lb	Luxembourgish	mk	Macedonian	mai	Maithili
mg	Malagasy	ms	Malay	ml	Malayalam
mt	Maltese	mi	Maori	mr	Marathi
mni-Mtei	Meitei (Manipuri)	lus	Mizo	mn	Mongolian
my	Myanmar (Burmese)	ne	Nepali	no	Norwegian
ny	Nyanja (Chichewa)	or	Odia (Oriya)	om	Oromo
ps	Pashto	fa	Persian	pl	Polish
pt	Portuguese	pa	Punjabi	qu	Quechua
ro	Romanian	ru	Russian	sm	Samoan
sa	Sanskrit	gd	Scots Gaelic	nso	Sepedi
sr	Serbian	st	Sesotho	sn	Shona
sd	Sindhi	si	Sinhala	sk	Slovak
sl	Slovenian	so	Somali	es	Spanish
su	Sundanese	sw	Swahili	sv	Swedish
tl	Tagalog (Filipino)	tg	Tajik	ta	Tamil
tt	Tatar	te	Telugu	th	Thai
ti	Tigrinya	ts	Tsonga	tr	Turkish
tk	Turkmen	ak	Twi (Akan)	uk	Ukrainian
ur	Urdu	ug	Uyghur	uz	Uzbek
vi	Vietnamese	cy	Welsh	xh	Xhosa
yi	Yiddish	yo	Yoruba	zu	Zulu

Note: zh is an alias for zh-CN (Simplified Chinese). Use zh-TW for Traditional Chinese.

Demo Endpoints (No Auth Required)

These endpoints allow unauthenticated access for testing and demos. Rate-limited to 10 requests/day per IP.

Request Body

Parameter	Type	Required	Description
q	string	required	Text to translate (max 500 chars)
target	string	required	Target language code
source	string	optional	Source language. Auto-detected if omitted.

cURL

curl -X POST https://api.socketsio.com/v1/demo/translate \
  -H "Content-Type: application/json" \
  -d '{"q": "Hello world", "target": "es"}'

Response

{
  "data": {
    "translations": [
      {
        "translatedText": "Hola mundo",
        "detectedSourceLanguage": "en"
      }
    ]
  },
  "demo": true,
  "remaining": 9
}

Request Body

Parameter	Type	Required	Description
q	string	required	Text to detect (max 500 chars)

cURL

curl -X POST https://api.socketsio.com/v1/demo/detect \
  -H "Content-Type: application/json" \
  -d '{"q": "Bonjour le monde"}'

Response

{
  "data": {
    "detections": [
      {
        "language": "fr",
        "confidence": 1.0,
        "isReliable": true
      }
    ]
  },
  "demo": true,
  "remaining": 9
}

Health Check

cURL

curl https://api.socketsio.com/health

Response

{
  "status": "ok",
  "version": "1.0.0",
  "uptime": 99.97,
  "latency_ms": 12
}

Speech-to-Text (STT)

Request

Send audio as multipart/form-data:

Field	Type	Required	Description
audio	File	✅ Yes	Audio file (mp3, wav, flac, ogg, webm)
language	String	No	BCP-47 language code (e.g. en-US, zh-CN). Omit for auto-detect.

Supported Languages

Auto-detect picks from: en-US, zh-CN, ja-JP, ko-KR, es-ES, fr-FR, de-DE, pt-BR, ar-SA, ru-RU

cURL

curl -X POST https://api.socketsio.com/v1/stt \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]" \
  -F "language=zh-CN"

Response

{
  "data": {
    "text": "你好，世界",
    "language": "zh-CN",
    "confidence": 0.97
  }
}

Python

import requests

with open("voice.mp3", "rb") as f:
    res = requests.post(
        "https://api.socketsio.com/v1/stt",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        files={"audio": f},
        data={"language": "zh-CN"}
    )
print(res.json()["data"]["text"])

JavaScript

const form = new FormData();
form.append("audio", audioFile);  // File object
form.append("language", "zh-CN");

const res = await fetch("https://api.socketsio.com/v1/stt", {
  method: "POST",
  headers: { "Authorization": "Bearer YOUR_API_KEY" },
  body: form
});
const { data } = await res.json();
console.log(data.text);  // "你好，世界"

Voice Translation Workflow

# Step 1: Transcribe audio to text
stt_res = requests.post("https://api.socketsio.com/v1/stt",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    files={"audio": open("voice.mp3", "rb")})
text = stt_res.json()["data"]["text"]

# Step 2: Translate to target language
tr_res = requests.post("https://api.socketsio.com/v1/translate",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"q": text, "target": "en"})
print(tr_res.json()["data"]["translatedText"])

Migrating from Google Translate v2

SocketsIO is drop-in compatible with Google Translate v2. To migrate, change one line:

# Before (Google)
POST https://translation.googleapis.com/language/translate/v2?key=GOOGLE_KEY

# After (SocketsIO)
POST https://api.socketsio.com/v1/translate
Header: X-API-Key: YOUR_SOCKETSIO_KEY

Request and response formats are identical. Your existing code works with minimal changes.

SDKs & Libraries

Language	Package	Install
Python	socketsio	pip install socketsio
JavaScript	socketsio	npm install socketsio

⚡ Interactive API Playground

Test the API live in your browser — no installation needed. Results appear in under a second.

Google AI Toolkit — MCP Server

SocketsIO provides a full-stack Model Context Protocol (MCP) server that gives AI agents (Claude, Cursor, Windsurf, and any MCP-compatible client) direct access to 7 Google Cloud AI tools — translation, language detection, OCR, text-to-speech, sentiment analysis, and more. No HTTP boilerplate needed.

Installation

pip install fastmcp httpx

Configuration — Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "socketsio-google-ai-toolkit": {
      "command": "fastmcp",
      "args": ["run", "/path/to/mcp-servers/google-ai-toolkit/server.py"],
      "env": {
        "SOCKETSIO_API_KEY": "your-api-key-here"
      }
    }
  }
}

Configuration — Cursor / Windsurf

{
  "socketsio-google-ai-toolkit": {
    "command": "fastmcp",
    "args": ["run", "/path/to/mcp-servers/google-ai-toolkit/server.py"],
    "env": {
      "SOCKETSIO_API_KEY": "your-api-key-here"
    }
  }
}

Available MCP Tools (7 Tools)

Tool	Description	Powered By
translate	Translate text across 195 languages	Google Cloud Translation
detect	Detect the language of text	Google Cloud Translation
languages	List all 195 supported languages	Google Cloud Translation
bulk_translate	Translate up to 128 texts in one call	Google Cloud Translation
ocr	Extract text from images (base64 or URL)	Google Cloud Vision
text_to_speech	Convert text to audio (MP3/WAV)	Google Cloud TTS
analyze_sentiment	Analyze text sentiment (score + magnitude)	Google Cloud Natural Language

Example Usage (Claude)

Once configured, Claude can call all 7 Google AI tools naturally:

User: Translate "Hello, how are you?" to Japanese and Chinese, then read it aloud.

Claude: I'll use the SocketsIO Google AI Toolkit for that.
[calls translate("Hello, how are you?", "ja")]  → こんにちは、お元気ですか？
[calls translate("Hello, how are you?", "zh")]  → 你好，你好吗？
[calls text_to_speech("こんにちは、お元気ですか？", lang="ja")]  → [MP3 audio]

User: What language is this text? "Bonjour le monde"

Claude: [calls detect("Bonjour le monde")]  → {"language": "fr", "confidence": 0.99}

User: Extract the text from this image.

Claude: [calls ocr(image_base64="...")]  → "Invoice #1234\nTotal: $99.00"

Get Your API Key

Sign up free → — 500K trial credits included, no credit card required. Or buy a Credit Pack for more volume. Credits never expire.

x402 Micropayments — AI Agent Native Access

SocketsIO supports the x402 protocol — an HTTP-native payment standard for AI agents. No API key required. Your agent pays per request using USDC on Base network.

Base URL

https://x402.api.socketsio.com

How It Works

1. Agent sends a normal HTTP request to the x402 endpoint
2. Server responds with HTTP 402 Payment Required + payment details
3. Agent pays the specified USDC amount on Base network
4. Agent retries with X-PAYMENT header containing payment proof
5. Server verifies payment and returns the result

x402 Endpoints & Pricing

Endpoint	Method	Price	Description
/v1/translate	POST	$0.001 USDC	Translate text (195 languages)
/v1/detect	POST	$0.0005 USDC	Detect language of text
/v1/languages	GET	Free	List supported languages
/health	GET	Free	Health check

Example: x402 Flow

# Step 1: Initial request → 402 Payment Required
curl -X POST https://x402.api.socketsio.com/v1/translate \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello world", "target_lang": "zh"}'

# Response: HTTP 402
# {
#   "error": "Payment required",
#   "price": "0.001",
#   "currency": "USDC",
#   "network": "base",
#   "payTo": "0x...",
#   "x402Version": 1
# }

# Step 2: Agent pays on Base, retries with payment proof
curl -X POST https://x402.api.socketsio.com/v1/translate \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: <base64-encoded-payment-proof>" \
  -d '{"text": "Hello world", "target_lang": "zh"}'

# Response: HTTP 200
# {"translated_text": "你好世界", "detected_lang": "en", "characters": 11}

Compatible Frameworks

• Coinbase AgentKit — native x402 support
• Any HTTP client — implement the 402→pay→retry flow manually
• Claude Computer Use — via HTTP tool calls
• LangChain / AutoGPT — via custom tool wrappers

See Pricing → x402 section for full details and pricing comparison.

Rate Limits

All API endpoints are rate-limited per API key. Limits reset every 60 seconds (rolling window).

Plan	Rate Limit	Characters/Month
Free	100 req/min	500,000
Basic	300 req/min	5,000,000
Pro	1,000 req/min	50,000,000
Enterprise	Unlimited	Custom

429 Response Format

When you exceed the rate limit, the API returns HTTP 429 Too Many Requests with a Retry-After header indicating how many seconds to wait:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json

{
  "error": {
    "code": 429,
    "message": "Rate limit exceeded. You have sent too many requests in the past 60 seconds.",
    "type": "rate_limit"
  }
}

Best practices:

• Check the Retry-After header and wait that many seconds before retrying
• Implement exponential backoff for batch translation jobs
• Use the q array parameter to batch up to 128 strings in a single request
• Cache translated content — the same string in the same language never needs re-translating

Error Codes

All errors follow a consistent JSON structure:

{
  "error": {
    "code": 400,
    "message": "Human-readable description of what went wrong",
    "type": "error_type_string"
  }
}

HTTP Code	Type	Meaning	Example Cause
400	invalid_request	Bad request	Missing q or target field; unsupported language code
401	authentication_error	Missing or invalid API key	No X-API-Key header; key revoked or mistyped
403	quota_exceeded	Monthly character limit exceeded	Free plan 500K chars/month used up; upgrade to continue
429	rate_limit	Too many requests	Exceeded req/min limit for your plan; check Retry-After header
500	server_error	Internal server error	Unexpected backend error; safe to retry after a short delay

Error Examples

401 — Missing API key:

curl https://api.socketsio.com/v1/translate \
  -H "Content-Type: application/json" \
  -d '{"q": "Hello", "target": "es"}'

# Response:
{
  "error": {
    "code": 401,
    "message": "API key required. Pass your key via the X-API-Key header.",
    "type": "authentication_error"
  }
}

400 — Invalid language code:

curl https://api.socketsio.com/v1/translate \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "Hello", "target": "zzz"}'

# Response:
{
  "error": {
    "code": 400,
    "message": "Unsupported target language: 'zzz'. See /v1/languages for supported codes.",
    "type": "invalid_request"
  }
}

403 — Monthly quota exceeded:

{
  "error": {
    "code": 403,
    "message": "Monthly character quota exceeded. Upgrade your plan at socketsio.com/pricing.",
    "type": "quota_exceeded"
  }
}