Documentation

API Reference

Everything you need to start translating. Most integrations take under 10 minutes.

Authentication

Every request needs an API key. Pass it in the X-API-Key header or as Authorization: Bearer <key>.

Two types of keys: test (sk_test_...) and live (sk_live_...). Test keys hit the real model but skip billing — use them during development. Switch to live when you ship.

POST /api/v1/translate

Send text, get one or many translations. Pass a single language string to translate once, or an array of up to 20 languages to fan out the same text in a single round trip. Source language is auto-detected when you don't specify one.

Request body

{
  "text": "Your order has been shipped",
  "targetLanguage": "ja",             // string OR array of strings (max 20)
  "sourceLanguage": "en"              // optional — auto-detects if omitted
}

Response

{
  "translatedText": "ご注文の商品が発送されました",
  "detectedLanguage": "en",
  "cached": false,
  "mode": "live",
  "usage": {
    "inputTokens": 24,
    "outputTokens": 18,
    "cost": 0.000378
  }
}

Multi-target — translate once, fan out to many locales

Pass targetLanguage as an array and the response shape changes to a translations array. Each entry has its own cached flag; usage is reported as an aggregate. Ideal for content pipelines: translate a post into every locale your app supports, then store the results.

// Request
{
  "text": "Your order has been shipped",
  "targetLanguage": ["ja", "es", "fr", "de"]
}

// Response
{
  "translations": [
    { "targetLanguage": "ja", "translatedText": "ご注文の商品が発送されました", "cached": true },
    { "targetLanguage": "es", "translatedText": "Su pedido ha sido enviado", "cached": false },
    { "targetLanguage": "fr", "translatedText": "Votre commande a été expédiée", "cached": false },
    { "targetLanguage": "de", "translatedText": "Ihre Bestellung wurde versendet", "cached": false }
  ],
  "detectedLanguage": "en",
  "mode": "live",
  "usage": {
    "inputTokens": 72,
    "outputTokens": 54,
    "cost": 0.001134
  }
}

curl

curl -X POST https://your-domain.com/api/v1/translate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_test_your_key_here" \
  -d '{"text": "Your order has been shipped", "targetLanguage": "ja"}'

Python

import requests

resp = requests.post(
    "https://your-domain.com/api/v1/translate",
    headers={"X-API-Key": "sk_test_your_key_here"},
    json={"text": "Your order has been shipped", "targetLanguage": "ja"}
)

print(resp.json()["translatedText"])

JavaScript / TypeScript

const resp = await fetch("https://your-domain.com/api/v1/translate", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "sk_test_your_key_here",
  },
  body: JSON.stringify({
    text: "Your order has been shipped",
    targetLanguage: "ja",
  }),
});

const { translatedText } = await resp.json();

POST /api/v1/translate/bulk

Translate multiple strings in one request. Under 20 items: synchronous response. Over 20: returns a job ID for async polling with optional webhook callback.

Request body

{
  "items": [
    { "text": "Add to cart", "targetLanguage": "ja" },
    { "text": "Checkout", "targetLanguage": "ja" },
    { "text": "Your order is confirmed", "targetLanguage": "fr" }
  ],
  "webhook": "https://your-app.com/hooks/translations"  // optional
}

Synchronous response (20 items or fewer)

{
  "status": "completed",
  "totalItems": 3,
  "completedItems": 3,
  "cachedItems": 1,
  "totalCost": 0.000756,
  "results": [...]
}

Async response (over 20 items)

{
  "jobId": "a1b2c3d4-...",
  "status": "processing",
  "totalItems": 500,
  "pollUrl": "/api/v1/translate/bulk/a1b2c3d4-..."
}

Bulk translations receive a 10% discount. Items already in cache are skipped — no model call, no charge.

GET /api/v1/translate/bulk/:jobId

Check the status of an async bulk job.

{
  "jobId": "a1b2c3d4-...",
  "status": "completed",
  "progress": { "total": 500, "completed": 500, "cached": 120 },
  "totalCost": 0.142,
  "results": [...]
}

GET /api/v1/usage

Team usage and costs for the signed-in session. Includes totals, last 30 days, per-key translation spend and storage (keys are identified by id and prefix, not the secret). Filter with ?mode=live or ?mode=test.

curl https://your-domain.com/api/v1/usage?mode=live \
  -H "Cookie: auto18n_session=YOUR_SESSION"

GET /api/v1/languages

List all supported languages. No authentication required.

curl https://your-domain.com/api/v1/languages

API Key Management

Manage keys from the dashboard or via the API.

Create a key

curl -X POST https://your-domain.com/api/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"name": "Production", "mode": "live"}'

List keys

curl https://your-domain.com/api/v1/keys

Delete a key

curl -X DELETE https://your-domain.com/api/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"id": "key-id-here"}'

Models — platform (Vercel AI Gateway)

Default translation traffic uses the Vercel AI Gateway OpenAI-compatible API. Set AI_GATEWAY_API_KEY (and optionally AI_GATEWAY_BASE_URL, VERCEL_OIDC_TOKEN on Vercel) on the server. Choose a model with AI_GATEWAY_MODEL (for example openai/gpt-4o-mini). List models with GET https://ai-gateway.vercel.sh/v1/models.

curl -X POST https://your-domain.com/api/v1/translate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_your_platform_key" \
  -d '{"text": "Your order has been shipped", "targetLanguage": "ja"}'

Bring your own endpoint (OpenAI-compatible)

To call your own provider with your key, send both X-Model-API-Key (bearer for that API) and X-Model-Base-URL (OpenAI-compatible root, e.g. https://api.openai.com/v1, https://api.x.ai/v1). Optionally set X-Model-Id for the model id (defaults to gpt-4o-mini or BYOK_DEFAULT_MODEL). We bill a small platform fee on token volume; you pay the provider directly at their rates.

curl -X POST https://your-domain.com/api/v1/translate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_your_platform_key" \
  -H "X-Model-API-Key: sk-your-openai-or-provider-key" \
  -H "X-Model-Base-URL: https://api.openai.com/v1" \
  -H "X-Model-Id: gpt-4o-mini" \
  -d '{"text": "Shipped", "targetLanguage": "de"}'