SocketsIO API Documentation

Authentication

All API requests require an API key passed via the X-API-Key header.

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

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

Plans

Translate Text

Request Body

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); // "你好世界"

Detect Language

Request Body

Example

curl -X POST https://api.socketsio.com/v1/detect \
  -H "X-API-Key: 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"
      }
    ]
  }
}

Supported Languages

Example

curl https://api.socketsio.com/v1/languages \
  -H "X-API-Key: YOUR_API_KEY"

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

⚡ Interactive API Playground

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

Rate Limits

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

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"
  }
}

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"
  }
}