Integration guides

Build a considerate translation client.

Start with the API quick start and its copyable cURL example. The same request and response work from any HTTP client.

1. Keep your key on your server

Create a named key for each integration. Put its secret in an environment variable or secret manager. Browser JavaScript and mobile bundles cannot keep a shared key private. Your backend should call the API for your users.

2. Discover before translating

Use GET /v1/models and GET /v1/languages. Select only an enabled direction and inspect its quality status. Cache discovery briefly; do not assume every combination of languages is supported.

3. Send small, complete text

The API accepts up to 768 UTF-8 bytes of input. Byte length differs from character count, especially for Arabic, Japanese, and emoji. Split long documents at sentence boundaries in your application, preserving context where possible.

4. Handle busy responses

The server handles one translation at a time. Queue requests in your own application and avoid bursts. For 429 or 503 responses, honor Retry-After and use bounded retries with backoff and jitter. A dispatched attempt counts toward quota even if inference fails, so a retry may consume another request.

5. Rotate without interruption

Create a replacement using key rotation, choose an overlap, update your deployment, and verify the replacement before the old key expires. Revoke unused keys promptly. Monitor usage in your account.

Before going live

Check the output language and meaning with representative text. Handle structured errors without displaying internal logs. Do not log your key or your users’ text. Download the OpenAPI specification for the complete contract.