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:
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
Add your API key to send requests
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.

Add your API key to send requests
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
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.

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.

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.

Add your API key to send requests
Editable
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
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.

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.

Add your API key to send requests

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

GET/features

Language & feature support

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

Add your API key to send requests
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
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.

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
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.

Add your API key to send requests

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