API Reference
API

Get started with the API

Subscribe to start building

v1

Supertext API

Introduction

A RESTful API for translating text and files with AI.

Use Cases

The Supertext API revolves around the following core endpoints:

  • /translate/ai/text
  • /translate/fused/text
  • /translate/ai/file

/translate/ai/text allows instant text translation with state-of-the-art large language models. Use it to make your website or application available in more languages to increase its reach and usage.

/translate/fused/text offers verified text translation, i.e. an AI translation for which a human expert verified that it is 100% correct. Depending on the text length, it can be as fast as 8 min. Using this endpoint is recommended for parts of your website or application that contain key messages of your service or are visited by the majority of your users.

/translate/ai/file supports automatic translation of different file types. The endpoint is especially useful if your text is embedded in a certain format that is hard to reconstruct manually, e.g. PowerPoint presentations that are regularly shared on your website or application.

The supported languages for all translation endpoints can be retrieved using the /features endpoint. They are encoded with BCP-47 language codes. The API can also be used to determine the language in which a text is written. This AI-based functionality is available via the /detect-languages/text and /detect-languages/file endpoints. Note that these endpoints support more languages than /translate/* endpoints.

Authentication

All endpoints require authentication with an API key. To obtain an API key, head over to the cockpit.

For every request, the API key is sent in the Authorization HTTP header. The header value consists of the custom scheme Supertext-Auth-Key, followed by the API key. For example, the submitted header may look like this:

Authorization: Supertext-Auth-Key j5ZZ06H/gP2NrnS3XK9gTJ12uENeIkkVH9aBcdeFkszFgMYClGyuATnI25DTd+99rThTL0dVZvqqRW879IGbASb4K3fDA55h4WhZp/9Nbpna2hsRk8526bP2WmlTe6t3O4Z8h2o0PcXggGKKYI8oFeweRw+rq9XjIG+Ber/JaM7IGyLDKg+PCc8iSR8bcHT09zon761ZVnBiSZCy0cKxww==

Usage Costs

The following endpoints incur usage costs:

  • /translate/ai/text
  • /translate/fused/text
  • /translate/ai/file
  • /detect-languages/text
  • /detect-languages/file

For each of these endpoints, a corresponding quote endpoint exists. For example, to determine in advance the costs for a POST request to /translate/ai/text, send the exact same payload to /translate/ai/text/quote. If the request is valid, the response indicates the costs for the same request to /translate/ai/text. If the request would not be accepted by /translate/ai/text (e.g. due to missing feature support or exceeding size limits), then the respective error is returned by the quote endpoint. As such, the quote endpoints can be used as a dry-run utility for testing clients.

Limits

All endpoints are subject to size and rate limits. Size limits restrict the volume of an individual request in terms of text length (number of characters) and file size. Rate limits define the maximum allowed number of requests within a given timespan.

The most important limits are:

  • /translate/ai/text: maximum 10,000 characters per request, maximum 5 request(s) per second
  • /translate/fused/text: maximum 3,000 characters per request, maximum 1 request(s) per second
  • /translate/ai/file: maximum 1,000,000 characters per file and 30MiB maximum file size, maximum 1 request(s) per second

Note that this list is not exhaustive and limits may change without an update to the API version.

Server
https://api.supertext.com/v1
AuthenticationOptional
Name:Authorization
Value:

Text Translation

Endpoints for translating plain text.

Translate plain text with pure AI or fused with human assistance.

  • Use the /translate/*/text/quote endpoints to verify your requests are valid and to determine expected costs.
  • The /translate/ai/text endpoint returns the translation instantly.
  • The /translate/fused/text endpoint works asynchronously.

The translation is available within minutes or (outside business hours) days.

POST/translate/ai/textCosts

AI translation

Translate plain text with optional glossary and politeness settings.

Note: This endpoint incurs usage costs.

The request payload is described below.

See also the examples on the right for typical usage.

Limits:

  • maximum characters per request: 10,000
  • maximum requests per second: 5
application/json
200
Add your API key to send requests

A simple translation from a source language to a target language.

Editable

This request will incur usage costs

POST/translate/ai/text/quote

AI translation quote

Get the quote for translating a given text.

This endpoint accepts the same payload as /translate/ai/text.

application/json
200
Add your API key to send requests

A simple translation from a source language to a target language.

Editable
POST/translate/fused/textCosts

Fused translation

Submit a request for human-assisted translation.

Note: This endpoint incurs usage costs.

This is an asynchronous operation.

Multiple HTTP requests are necessary to obtain the translated text.

  • [optional] Determine costs and estimated delivery time with a POST request to /translate/fused/text/quote.
  • Initiate the translation flow with a POST request to /translate/fused/text. Store the translation_id from the response for use in the subsequent requests.
  • Poll the status of the translation with repeated GET requests to /translate/fused/text/{translation_id}/status. The suggested poll interval is 1 minute.
  • Once the status has changed to "done", retrieve the completed translation with a GET request to /translate/fused/text/{translation_id}/translation.

Limits:

  • maximum characters per request: 3,000
  • maximum requests per second: 1
application/json
202
Add your API key to send requests
Editable

This request will incur usage costs

GET/translate/fused/text/{translation_id}/status

Fused translation status

Check the status of a human-assisted translation request.

200
Add your API key to send requests
GET/translate/fused/text/{translation_id}/translation

Fused translation download

Download the translated text once the human-assisted translation is completed.

Note: the translated text is available for download for 60 days after initiating the translation.

200
Add your API key to send requests
POST/translate/fused/text/quote

Fused translation quote

Get the quote for translating text with human assistance.

This endpoint accepts the same payload as /translate/fused/text.

application/json
200
Add your API key to send requests
Editable

File Translation

Endpoints for translating file-based documents with optional glossary and politeness settings.

Translating files is an asynchronous operation. Multiple HTTP requests are necessary to obtain the translated file.

  1. [optional] Determine costs with a POST request to /translate/ai/file/quote.
  2. Initiate the file-translation flow with a POST request to /translate/ai/file. Store the file_id from the response for use in the subsequent requests.
  3. Poll the status of the translation with repeated GET requests to /translate/ai/file/{file_id}/status. The suggested poll interval is 1 second.
  4. Once the status has changed to "done", retrieve the translated file with a GET request to /translate/ai/file/{file_id}/translation.
  5. [optional] Delete the translated file from the server with a DELETE request to /translate/ai/file/{file_id}.
POST/translate/ai/fileCosts

File translation

Upload a file for document translation.

Note: This endpoint incurs usage costs.

The request payload for this endpoint needs to be encoded as multipart/form-data.

Supported file types are: DOCX, PPTX, XLSX, PDF, HTML, TXT, SRT.

If the glossary parameter is provided, its value needs additional JSON encoding.

Limits:

  • maximum characters per file: 1,000,000
  • maximum file size: 30MiB
  • maximum requests per second: 1
multipart/form-data
202
Add your API key to send requests

Supported: DOCX, PPTX, XLSX, PDF, HTML, TXT, SRT

This request will incur usage costs

GET/translate/ai/file/{file_id}/status

File translation status

Check the status of a file translation request.

200
Add your API key to send requests
GET/translate/ai/file/{file_id}/translation

File translation download

Download the translated file once the translation is completed.

Note: the translated file is available for download for 24h after initiating the translation.

Add your API key to send requests
DELETE/translate/ai/file/{file_id}

File translation delete

Delete the translated document from a file translation request.

This operation is irreversible.

After deleting a translated file, requests to /translate/ai/file/{file_id}/status and .../translation will result in a 404 error response.

Note: translated files are automatically deleted from the server 24h after initiating the translation.

Add your API key to send requests
POST/translate/ai/file/quote

File translation quote

Retrieve the quote for translating a document.

This endpoint accepts the same payload as /translate/ai/file.

multipart/form-data
200
Add your API key to send requests

Supported: DOCX, PPTX, XLSX, PDF, HTML, TXT, SRT

Feature Scope

Endpoints for checking the feature scope of the API key.

GET/features

Language & feature support

Get a list of supported features for all language combinations, optionally filtered by source and/or target language.

200
Add your API key to send requests

Language Detection

Endpoints for detecting languages in text and files.

These endpoints are intended for use cases where identifying the language is the objective. In the context of translating text or files in an unknown source language, it is more convenient (and cost-effective) to submit a translation request with an unspecified source language rather than using these endpoints.

Language detection is based on a probabilistic AI model and may not always be correct, in particular for short texts. Therefore, the language detection endpoints return a list of languages, sorted by confidence score, with the most probable language at the top. The list may include languages that are not supported by our translation endpoints; this is indicated by the supports_translation flag.

POST/detect-languages/textCosts

Language detection

Detect the languages of the provided text.

Note: This endpoint incurs usage costs.

Limits:

  • maximum requests per second: 10
application/json
200
Add your API key to send requests
Editable

This request will incur usage costs

POST/detect-languages/text/quote

Language detection quote

Get the quote for detecting the languages of a given text.

application/json
200
Add your API key to send requests
Editable
POST/detect-languages/fileCosts

File language detection

Detect the languages of a file-based document.

Note: This endpoint incurs usage costs.

Limits:

  • maximum requests per second: 1
multipart/form-data
200
Add your API key to send requests

Supported: DOCX, PPTX, XLSX, PDF, HTML, TXT, SRT

This request will incur usage costs

POST/detect-languages/file/quote

File language detection quote

Get the quote for detecting the languages of a file-based document.

multipart/form-data
200
Add your API key to send requests

Supported: DOCX, PPTX, XLSX, PDF, HTML, TXT, SRT