Supertext API
Introduction
A RESTful API for translating text with AI, and for finding out what a translation will cost before you ask for it.
Use Cases
/translate/ai/text translates plain text instantly with large language
models. Use it to make a website or an application available in more
languages.
/translate/ai/file translates a whole document and gives it back in the
same format. It answers with a file_id rather than a translation, because
extracting, translating and reassembling a document takes longer than a
request should stay open; poll the id and download the result when it is
ready.
/translate/fused/text translates text and has a human expert review the
result before you get it. Use it for the copy you cannot afford to get wrong —
key messages, legal or safety-critical wording, the pages most of your users
see. It answers with an id to poll rather than a translation, because a person
has to do the work; delivery is minutes during covered hours.
/translate/fused/file is the same service for a whole document: it is
translated and a reviewer works on the result, and what you download at the end
is the reviewed document, not a machine translation of it.
Adding a briefing to either request orders Optimisation instead of
Verification: the reviewer works to your instructions — tone, audience, what
the text is for — rather than only checking that the translation is correct. It
is the same endpoint and the same call sequence; the briefing changes the price,
the delivery time and how much text you may send.
/detect-languages/text identifies the language a text is written in. If your
goal is to translate text whose language you do not know, you do not need this
endpoint — omit source_lang from the translation request instead and the
answer comes back as detected_source_lang, at no extra cost.
The supported language pairs, and which features each pair supports, come from
/features. Languages are BCP 47 tags.
Authentication
Every endpoint requires an API key. Workspace admins create and revoke keys in the Supertext workspace under API keys; a key belongs to one workspace and inherits that workspace's plan, entitlements and billing.
The key goes in the Authorization header as a bearer token:
Authorization: Bearer st_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
A key is shown once, when it is created, and stored only as a hash — so it cannot be recovered afterwards, only replaced. Revoking a key takes effect immediately.
Usage Costs
These endpoints incur usage costs:
/translate/ai/text/detect-languages/text/translate/ai/file/detect-languages/file/translate/fused/text/translate/fused/file
Each has a /quote sibling that takes the same payload and answers what
the real call would cost. Validation runs there too, so a quote doubles as a
dry run: an unsupported language pair or an oversized request fails on the
quote exactly as it would on the translation.
A quote answers prices, keyed by lower-case currency code — one entry, your
workspace's own billing currency. It is deliberately not rounded to the cent,
because nothing is charged per request: usage accrues in characters and is
priced on the accumulated total, so a single request's share of the bill is a
fraction of a cent and that fraction is what you are told.
Human review is charged differently from machine translation, because it is
different work. A /translate/fused/text order is priced per word of your
source text, with a minimum charge per order, and the amount is taken from your
credit balance the moment the order is accepted — the same price the same
service costs when ordered from the Supertext workspace. The machine
translation that produces the reviewer's draft is included in that price;
it is not metered separately, in the same way that detecting the language of a
translation you did not label costs nothing extra.
API and MCP usage draws on your plan's quota first. Each plan includes a quota of characters per month (per year on a yearly plan), shared by this API and the MCP server, and it resets with your billing period. Only the characters past it are charged. It is separate from the characters included for use of the Supertext workspace itself, which API usage never draws on.
Characters past the quota are paid from the workspace's credit balance. A
request whose slice past the quota the balance cannot cover is refused with
402 rather than queued, and the response's reason
says which case it is: insufficient_credit means top up (or switch automatic
top-up on, which is what an unattended integration wants). Usage accrues in
characters and is priced periodically, so a 402 reflects what is already owed
plus what you just asked for.
Limits
Size limits cap one request; rate limits cap how many requests you may send
per second, per key. Exceeding a rate limit returns 429 with a
Retry-After header — read that header rather than hardcoding a backoff.
| Endpoint | Size | Rate |
|---|---|---|
/translate/ai/text | 10,000 characters, 100 terms | 5/s |
/translate/ai/text/quote | same | 10/s |
/detect-languages/text | first 500 characters read | 10/s |
/detect-languages/text/quote | same | 10/s |
/translate/ai/file | 30 MiB | 1/s |
/translate/ai/file/quote | same | 10/s |
/detect-languages/file | 30 MiB | 1/s |
/detect-languages/file/quote | same | 10/s |
/translate/fused/text | 3,000 characters, or 12,000 with a briefing | 1/s |
/translate/fused/text/quote | same | 10/s |
/translate/fused/file | 30 MiB | 1/s |
/translate/fused/file/quote | same | 10/s |
/features | — | 10/s |
/webhooks (every method) | 10 webhooks per workspace | 1/s |
/webhooks/{webhook_id}/test | — | 1 per 5 s |
This list is not exhaustive, and limits may change without a new API version.
Errors
Every error is application/problem+json (RFC 9457):
{
"type": "urn:supertext:error:validation_error",
"title": "Unprocessable Entity",
"status": 422,
"detail": "body.target_lang: unsupported target language",
"code": "validation_error",
"error_id": "9f1c7a2e"
}
detail is always a string and is safe to show to a person. code is the
stable slug to branch on in code. Errors carry an error_id; quote it when
reporting a problem.
Response headers
Every response carries an X-Request-ID, also returned as request_id in the
bodies that have one; quote it with any support request. A 429 carries
Retry-After (seconds) and a 401 carries WWW-Authenticate. A download
carries Content-Disposition with the file name. The rest — Cache-Control,
Strict-Transport-Security, Content-Security-Policy,
X-Content-Type-Options, X-Frame-Options, Referrer-Policy,
Permissions-Policy — are standard security headers a client can ignore.
Webhooks
Instead of polling, register a webhook: an HTTPS URL that we call when something happens — a translation finishes, or the workspace needs attention. Polling keeps working; a webhook tells you when to look.
A webhook belongs to the API key that created it. A key lists, changes, tests and deletes only its own webhooks, and translation events go only to the webhooks of the key that started the translation. Workspace events go to every webhook in the workspace that subscribed to them. A webhook stops when its key is revoked or expires. A workspace can have up to 10 webhooks.
A webhook subscribes to an explicit list of event types; there is no wildcard.
| Event type | Sent when | Sample data |
|---|---|---|
translation.ai_file.completed | An API-started AI file translation finishes successfully. | {"file_id": "b0f3a1d84c6e4a7f9c2e5d1b8a7f6e30"} |
translation.ai_file.failed | An API-started AI file translation fails. | {"file_id": "b0f3a1d84c6e4a7f9c2e5d1b8a7f6e30", "error": "The document could not be translated."} |
translation.fused_text.completed | An API-ordered Fused text translation is delivered. | {"translation_id": "0e9b7c52-6a1d-4f3e-8b2a-9c4d5e6f7a81"} |
translation.fused_file.completed | An API-ordered Fused file translation is delivered. | {"translation_id": "7d3f9a12-4b6c-4e8d-a1f2-3c5b7d9e0f14"} |
translation.fused_file.failed | An API-ordered Fused file translation fails. | {"translation_id": "7d3f9a12-4b6c-4e8d-a1f2-3c5b7d9e0f14", "error": "The document could not be translated."} |
wallet.low_balance | The wallet balance newly drops below its low-balance threshold. | {"currency": "CHF", "balance": "18.40"} |
wallet.topped_up | A wallet top-up is finalised, manual or automatic. | {"top_up_id": "c41a8e3d-2b7f-4d9a-8e1c-6f5b3a2d9e07", "currency": "CHF", "amount": "200.00", "balance": "218.40"} |
invoice.issued | An invoice PDF is issued. | {"invoice_id": "a9e2d7c4-1f3b-4a6e-9d8c-2b5f7e1a3c60", "issued_at": "2026-11-01T00:04:31Z"} |
subscription.payment_failed | The subscription goes past due after a failed payment. | {"plan_code": "growth"} |
subscription.payment_recovered | The subscription is restored after a payment succeeds. | {"plan_code": "growth"} |
api_key.expiring | An API key is 30 days, and again 7 days, from its expiry. | {"api_key_id": "3e7b1d9f-5c2a-4f8e-b6d1-8a4c2e9f7b35", "name": "CMS plugin", "expires_at": "2026-12-01T09:00:00Z", "days_left": 30} |
api_key.revoked | An API key is revoked. | {"api_key_id": "3e7b1d9f-5c2a-4f8e-b6d1-8a4c2e9f7b35", "name": "CMS plugin", "revoked_at": "2026-10-28T15:42:07Z"} |
Good to know about individual events. Some events have conditions the table does not show:
api_key.revokedis never sent to the webhooks of the key that was revoked: they are deleted first. Only the workspace's other webhooks hear of it.wallet.low_balanceis sent at most once every 24 hours per wallet, not when a wallet is first seen, nor after its threshold is changed. It is sent only when the balance crosses below the threshold.invoice.issuedis sent only when the invoice is issued within 24 hours of its payment; an invoice that turns up later is not announced.invoice.issuedissued_atis the invoice date, which is the payment time; for a top-up theinvoice_idequals thetop_up_id.wallet.topped_upamountis the credits added, not the price paid. In every event, amounts are strings with 2 decimal places and the currency is upper-case, for example"18.40"and"CHF".api_key.expiringis sent at 30 days and again at 7 days before expiry, at most one warning per hourly run: a key first seen inside the 7-day window gets only that one.translation.fused_file.completedcan be held for up to 5 minutes, until the translated document is ready to download.
Payloads never contain content. An event carries ids, statuses and
amounts — never text, documents or download links. Fetch the result with your
API key, from the endpoint you would otherwise poll. The error of a failed
event is always the same generic message; call that endpoint's /status for
the detail.
Every event is a POST with a JSON body:
POST https://cms.example.com/hooks/supertext
content-type: application/json
user-agent: Supertext-Webhooks/1
webhook-id: 2f6c1b0e-9d4a-4e37-8c15-7a3b9e2d4f60
webhook-timestamp: 1761656713
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
{"type":"translation.ai_file.completed","timestamp":"2026-10-28T13:05:12Z","data":{"file_id":"b0f3a1d84c6e4a7f9c2e5d1b8a7f6e30"}}
timestamp in the body is when the event happened, in UTC; webhook-timestamp
is when this attempt was sent, in Unix seconds.
Verify every request. Requests are signed the
Standard Webhooks way: webhook-signature
is v1, followed by the base64 HMAC-SHA256 of
{webhook-id}.{webhook-timestamp}.{body}, keyed with your secret (the
base64 part after whsec_, decoded). Check it against the raw body, before
any JSON parsing, and reject a request whose timestamp is more than a few
minutes old.
The Standard Webhooks libraries do all of this. In Python, with the
standardwebhooks package:
from standardwebhooks.webhooks import Webhook
webhook = Webhook(secret) # the whsec_... value from the create response
event = webhook.verify(raw_body, headers) # raises unless the request is ours
Libraries exist for JavaScript, PHP, Go, Java, Ruby, C#, Rust and more; see standardwebhooks.com.
Source IPs are not fixed. Requests can come from any address and the addresses change without notice, so verify the signature instead of allowlisting IPs.
Answer with a 2xx, quickly. Any 2xx is a success. Anything else — another status, a redirect (never followed), or no answer within 10 seconds — is a failed attempt. Answer first and do the work afterwards.
Retries. After each failed attempt the event is sent again, waiting 5 s, 5 min, 30 min, 2 h, 5 h, 10 h, 10 h in turn. After the 8th failed attempt it is given up.
At least once, in any order. An event can arrive more than once:
webhook-id is the same on every retry, so deduplicate on it. Events are not
guaranteed to arrive in the order they happened.
Disabled webhooks. A webhook that answers 410 Gone is disabled at once.
One that has failed 20 attempts in a row and not succeeded
for 5 days is disabled too; the 5
days run from the last success, or from when you created or re-enabled the
webhook, whichever is latest. A disabled webhook shows
status: disabled with a disabled_reason (gone or failing), and the
events still waiting for it are cancelled. Once your endpoint is fixed,
re-enable it with PATCH /webhooks/{webhook_id} and {"enabled": true}.
Testing. POST /webhooks/{webhook_id}/test sends a webhook.test
event straight away, with data set to {"webhook_id": "5b0c1e7a-3d2f-4c8e-9a61-2f7d8e4b1c90"}, and answers with what
your endpoint replied. It is not retried and does not count as a failure. You cannot
subscribe to webhook.test.
https://api-platform.supertext.com/v1Text Translation
Translate plain text with AI or human assistance, or request a quote before ordering.
/translate/ai/textCostsAI translation
Translate plain text, with optional glossary terms, formality control and tag handling.
This endpoint incurs usage costs.
Send one or several strings in text; each is translated independently and the
results come back in the same order. Omit source_lang to have it detected —
the detected language is reported as detected_source_lang, and detection
costs nothing extra because the translation pays for the text anyway.
Ask /features whether the pair you want supports politeness or a
glossary. Sending either for a pair that does not support it is refused
rather than silently ignored.
Limits: 10,000 characters per request (the total across
text), 100 glossary terms, 5
request(s) per second.
One string, from a stated source language into one target variant.
This request will incur usage costs
/translate/ai/text/quoteAI translation quote
What a translation would cost.
Takes the same payload as /translate/ai/text, so you can price the exact call
you are about to make by re-sending it. Nothing is translated, nothing is
metered, and no usage is recorded. Validation still runs, which makes this a
dry run as well as a price.
prices gives what these characters cost, keyed by your workspace's billing
currency in lower case ({"chf": 0.00056}). The price is what the request
would cost beyond your plan's API & MCP quota at the time of the quote, so it
is 0.0 while the request fits inside the quota. It is not rounded to the
cent, because usage is priced on an accumulated character total rather than
per request.
Quotes are not gated on your balance: the moment you most need to ask the price is the moment you have run out.
Limits: 10 request(s) per second.
One string, from a stated source language into one target variant.
/translate/fused/textCostsFused translation
Translate text and have a human expert review the result.
This endpoint incurs usage costs.
This is an asynchronous operation: several HTTP requests are needed to get the finished text.
- (optional) Ask
/translate/fused/text/quotewhat it will cost and when it will be delivered. Same payload, nothing charged. POST /translate/fused/text. Keep thetranslation_idfrom the response.- Poll
GET /translate/fused/text/{translation_id}/status— once a minute is a sensible interval.estimated_duration_left_in_secondstells you how long is left, and goes negative if the promised time has passed. - When
statusiscompleted, fetch the text fromGET /translate/fused/text/{translation_id}/translation.
The price covers the whole thing — the machine translation and the review.
/translate/fused/text/quote reports it before you commit.
A briefing orders Optimisation instead of Verification. Without one, a
reviewer checks that the translation is correct. With one, the reviewer also
works the text to your instructions. You will get back briefing_applied so
you can tell which service you bought without parsing the name, and
service_label for showing a person. Branch on the boolean, not the label —
the names may change.
source_lang is required here, unlike on /translate/ai/text: the order is
priced and routed to a linguist before anything is translated, and both need
the language pair up front.
Not every language pair can be reviewed by a human — it depends on there being
a linguist for that direction. /features marks the ones that can with
supports_fused_translation. Sending an unsupported pair is refused before
anything is charged.
Limits: 3,000 characters per request, or 12,000 with a briefing; 1 request(s) per second.
A reviewer checks that the translation is correct. This is the default.
This request will incur usage costs
/translate/fused/text/{translation_id}/statusFused translation status
Where a human-assisted translation has got to.
in_progress covers everything before delivery, whether or not a reviewer has
started. completed means the text is ready to fetch. failed means the order
was cancelled and no text is coming — check it rather than polling forever.
estimated_duration_left_in_seconds counts down to the delivery time promised
when the order was placed. A negative number means that time has passed; the
order is still being worked on, and the number says by how much it is late.
/translate/fused/text/{translation_id}/translationFused translation download
Download a human-assisted translation once a reviewer has delivered it.
202 with "status": "in_progress" while the order is still open —
the id is valid, the text just is not ready. Poll the status endpoint rather
than retrying this one on a tight loop.
The text stays available for as long as the order is kept in your workspace, so you can fetch it more than once.
/translate/fused/text/quoteFused translation quote
What a human-assisted translation would cost, and when it would be delivered.
Takes the same payload as /translate/fused/text, including the briefing,
which is what decides both numbers. Nothing is translated, nothing is metered,
no order is placed and no reviewer is engaged.
prices is what the call costs, in your workspace's billing currency: the
review, priced per source word with a per-order minimum. The machine
translation is included in it. word_count is the unit the price is computed
from, so you can see where the number comes from.
estimated_duration_in_seconds is measured from now and accounts for our
review hours, so a request sent at the end of a working day is quoted longer
than the same request sent at the start of one. It is an estimate, not a
guarantee.
Validation runs here too, so this doubles as a dry run: an unsupported pair, an oversized text or a service we cannot currently deliver fails on the quote exactly as it would on the order.
Quotes are not gated on your balance.
Limits: 10 request(s) per second.
A reviewer checks that the translation is correct. This is the default.
File Translation
Translate documents with AI or human review, follow progress, and download the result.
/translate/ai/fileCostsAI file translation
Translate a document and get it back in the same format.
This endpoint incurs usage costs.
Send the file as multipart/form-data. This is an asynchronous operation:
- (optional) Ask
/translate/ai/file/quotewhat it will cost. Same form body, nothing charged. POST /translate/ai/file. Keep thefile_idfrom the response.- Poll
GET /translate/ai/file/{file_id}/status— every few seconds is plenty. - When
statusisdone, download the translated document fromGET /translate/ai/file/{file_id}/translation.
Supported formats: DOCX, PPTX, XLSX, PDF, HTML, TXT, SRT. A PDF comes back as a DOCX, because a
translated PDF has to be rebuilt as an editable document.
use_ocr applies to PDFs only. Set it when the document is a scan, or when
its text layer is unreliable — leaving it off on such a file yields an empty
or garbled translation rather than an error.
glossary is a JSON object of source → target terms, sent as a string
inside the form field. At most 100 terms.
You are charged for the characters the document turns out to hold, which is not knowable until it has been extracted. The upload checks that your balance can be charged at all and refuses immediately if it cannot; the real charge lands when the translation finishes.
Limits: 30 MiB per file, 1 request(s) per second.
Supported: DOCX, PPTX, XLSX, PDF, HTML, TXT, SRT
This request will incur usage costs
/translate/ai/file/{file_id}/statusAI file translation status
Where a file translation has got to.
translating covers everything before the document is ready — extraction,
translation and reassembly are our stages, not yours. Then done, or error
with a message, or deleted if you withdrew the document.
Polling this is also what finalises the charge for the translation, so keep polling until you see a terminal status.
/translate/ai/file/{file_id}/translationAI file translation download
Download the translated document once it is ready.
The response is the file itself, with a Content-Disposition header — not
JSON. A PDF you uploaded comes back as a DOCX.
202 with "status": "in_progress" while the document is not ready
yet: the id is valid, the translation just is not finished. Poll the status
endpoint rather than retrying this one in a tight loop.
Translations stay available for 24 hours.
/translate/ai/file/{file_id}AI file translation delete
Delete an uploaded document before its retention window elapses.
The document is removed from storage, together with its translation and everything extracted from it. Use this when you have uploaded something confidential and do not want to wait 24 hours for it to expire.
Deleting the same id twice answers the same both times. A translation already finished has already been charged for; deleting the document does not undo that.
/translate/ai/file/quoteAI file translation quote
What translating a document would cost.
Send exactly the request you would send to /translate/ai/file. Every
field that endpoint takes is accepted here, so pricing a call means re-sending
it rather than rewriting it. Nothing is translated, nothing is metered and no
job is created.
Most of those fields cannot change the price — characters cost the same in every language, and neither a glossary nor a politeness setting adds any — but they are validated here anyway, so a request that would be refused by the translation is refused by its quote.
The price is what the request would cost beyond your plan's API & MCP quota at the time of the quote.
use_ocr does change the price. It decides how a PDF's text is read, and
therefore how many characters the document turns out to hold: quote a scan
without it and you are pricing a document that appears to be empty, while the
real charge lands on everything OCR finds. Send the same value you will order
with.
The document does have to be read to count its characters, so this takes about
as long as an extraction — it is a dry run for the price, not for the time. With
use_ocr, it takes about as long as OCR: a large scan can take a while, and the
answer is worth the wait only because the alternative is a price for a document
that appears to be empty.
Limits: 30 MiB per file, 10 request(s) per second.
Supported: DOCX, PPTX, XLSX, PDF, HTML, TXT, SRT
/translate/fused/fileCostsFused file translation
Translate a document and have a human expert review the result.
This endpoint incurs usage costs.
Send the file as multipart/form-data. One call places the whole order — the
document is translated and a reviewer takes it from there:
- (optional) Ask
/translate/fused/file/quotewhat it will cost and how long it will take. Same form body, nothing ordered. POST /translate/fused/file. Keep thetranslation_idfrom the response.- Poll
GET /translate/fused/file/{translation_id}/status— once a minute is plenty. It staysin_progresswhile the document is being translated and while it is being reviewed. - When
statusiscompleted, download the reviewed document fromGET /translate/fused/file/{translation_id}/translation.
Supported formats: DOCX, PPTX, XLSX, PDF, HTML, TXT, SRT. A PDF comes back as a DOCX, because a
translated document has to be rebuilt as an editable one.
source_lang is required here, as it is for text: the review is priced and
routed to a linguist before anything is translated, and both need the pair up
front.
The price is the service's, per source word of your document, and the
machine translation is included in it. It is not knowable until the document
has been extracted, so this call checks that your balance can be charged at all
and the real debit lands when the order is placed. If your balance no longer
covers it by then, status answers failed with that as the reason.
Limits: 30 MiB per file, 1 request(s) per second. There is no character cap: a document too large to promise a delivery date for is refused with a 422 pointing at a manual quote.
Supported: DOCX, PPTX, XLSX, PDF, HTML, TXT, SRT
This request will incur usage costs
/translate/fused/file/{translation_id}/statusFused file translation status
Where your order has got to.
in_progress covers both phases — the machine translation and the human
review. completed means the reviewed document is ready to download.
failed means the order will not be delivered, and error says why: the
document could not be translated, it held no text to review, or your balance
did not cover the price when the order was placed.
estimated_duration_left_in_seconds counts down to the promised delivery once
a reviewer has the document, and is 0 before that. A negative number means the
promise has passed.
/translate/fused/file/{translation_id}/translationFused file translation download
Download the reviewed document.
Answers the document itself, with the reviewer's changes patched back into it,
under a Content-Disposition filename — not JSON. It is a DOCX: a PDF is
converted on the way in, and what comes back is the document as it was
translated.
202 with "status": "in_progress" until a reviewer has delivered.
The machine translation exists long before that, and handing it back here would
sell you a draft as a reviewed document. Poll the status endpoint rather than
retrying this one on a tight loop.
/translate/fused/file/quoteFused file translation quote
What a human review of this document would cost, and when it would arrive.
Send exactly the request you would send to /translate/fused/file. Every
field that endpoint takes is accepted here, so pricing a call means re-sending
it rather than rewriting it. Nothing is translated, nothing is metered, no
order is placed and no reviewer is engaged.
Two of those fields change the answer. The briefing selects Optimisation
instead of Verification, which changes both the price and the delivery time.
And use_ocr decides how a PDF's text is read, and therefore how many
words the document turns out to hold — quote a scan without it and you are
pricing a document that appears to be empty. politeness steers the draft the
reviewer starts from, not how much there is to review, so it cannot change
either number.
prices is what the call costs, in your workspace's billing currency: the
review, priced per source word with a per-order minimum, with the machine
translation included. word_count and character_count are what was found in
the document, so you can see where the number comes from — neither is a
quantity you are charged for separately.
The document is read to answer this, so the same size and format rules apply as for the order itself.
Limits: 30 MiB per file, 10 requests per second.
Supported: DOCX, PPTX, XLSX, PDF, HTML, TXT, SRT
Feature Scope
Discover supported language pairs and their available features.
/featuresLanguage & feature support
Every supported language pair, and the features supported for each.
Translation itself is a full matrix — every source language translates into every target language. What has gaps is the features, and the gaps are per language: formality is meaningless in some targets, and glossary terms cannot be enforced in every target. So this endpoint answers one entry per pair with the feature names that pair supports; a name that is absent is not supported.
Filter with source_lang and/or target_lang to ask about one row rather than
the whole matrix. A filter naming a language we do not support narrows the
answer to nothing rather than failing — a language picker asking about an
unknown language wants an empty list, not an error. A target_lang naming a
base language with several variants (de) keeps all of them.
Limits: 10 request(s) per second.
Language Detection
Identify the language of text or files, or quote detection.
/detect-languages/textCostsLanguage detection
Detect the language of the provided text.
This endpoint incurs usage costs, charged like a translation of the
500-character snippet actually read. An inconclusive
answer — an empty detected_languages — is free.
Limits: 10 request(s) per second.
This request will incur usage costs
/detect-languages/text/quoteLanguage detection quote
What a detection would cost.
Takes the same payload as /detect-languages/text. Same fields as the
translation quote, priced on the capped snippet. The price is what the request
would cost beyond your plan's API & MCP quota at the time of the quote.
Limits: 10 request(s) per second.
/detect-languages/fileCostsFile language detection
Identify the language a document is written in.
This endpoint incurs usage costs.
Send the file as multipart/form-data. The answer comes back on the same
request — no polling. The document is read while you wait, so a large file, or
a scan that needs OCR, can take a while and may time out; if that happens,
extracting the text yourself and using /detect-languages/text is the
reliable path.
A document with no readable text answers with an empty detected_languages
list and costs nothing.
Charged on the first 500 characters of the document, like the text endpoint — identifying a language needs a sample, not the whole file.
Limits: 30 MiB per file, 1 request(s) per second.
Supported: DOCX, PPTX, XLSX, PDF, HTML, TXT, SRT
This request will incur usage costs
/detect-languages/file/quoteFile language detection quote
What detecting a document's language would cost.
Takes the same file as /detect-languages/file. Nothing is identified and no
usage is recorded, but the document is still read to see how much text it
holds, so this is as slow as the detection itself. The price is what the request
would cost beyond your plan's API & MCP quota at the time of the quote.
Limits: 10 request(s) per second.
Supported: DOCX, PPTX, XLSX, PDF, HTML, TXT, SRT
Webhooks
Register endpoints that we call when your translations finish or your workspace needs attention.
/webhooksList webhooks
The webhooks this API key created. Another key's webhooks, even in the same workspace, are not listed.
Limits: 1 request(s) per second.
/webhooksCreate a webhook
Register a URL to receive the events you list. See the Webhooks section for the event types, the request we send and how to verify it.
The response carries the signing secret, and only this response does.
Store it now: it cannot be read again. To get a new one, delete the webhook
and create it again.
The URL must be https, carry no credentials and resolve to a public address;
it is checked now and again before every delivery. A workspace can have up to
10 webhooks; the next one is refused with 409
webhook_limit_reached.
Limits: 1 request(s) per second.
The usual set for an integration that uploads documents and wants the result.
/webhooks/{webhook_id}Get a webhook
One of this API key's webhooks, with its delivery health: when an event last reached it, the last failure and how many attempts in a row have failed.
Limits: 1 request(s) per second.
/webhooks/{webhook_id}Update a webhook
Change the URL, the event types or the description. Only the fields you send
change; "description": null clears the description.
"enabled": true switches a disabled webhook back on and resets its failure
count. Events that were cancelled while it was disabled are not sent again.
Limits: 1 request(s) per second.
Once your endpoint answers again. Resets the failure count.
/webhooks/{webhook_id}Delete a webhook
Delete a webhook. Events not yet delivered to it are cancelled, and nothing new is sent to it; at most a request already in progress may still arrive.
Limits: 1 request(s) per second.
/webhooks/{webhook_id}/testSend a test event
Send a webhook.test event to the webhook now and report what came back.
Use it to check an endpoint while you set it up.
It is signed and sent exactly like a real event, but it is not retried and
does not count towards the webhook's failure record. A failed test is still a
200: read delivered, status_code and error. A disabled webhook
answers 409 webhook_disabled; re-enable it first.
Limits: 1 per 5 s.