Compare direct answers, Streaming, background queries and Webhooks. All variants use text, voice code and mode.
Choose how your system receives the result.
{
"text": "Complex source content in the selected language.",
"locale": "en",
"mode": "simple-language"
}SDK and cURL examples available
Synchronous HTTP
Endpoint
POST /api/v2/translate
Best for
Short texts, the results of which are immediately required.
Success
200 OK
Streaming
The response uses Content-Type: text/event-stream.
Endpoint
POST /api/v2/translate/stream
Best for
For longer content whose result should appear progressively.
{
"text": "Source content in the selected language.",
"locale": "en",
"mode": "easy-language"
}event: meta
data: {"requestId":"req_stream_001","locale":"en","mode":"easy-language"}
event: delta
data: {"delta":"Complete result."}
event: done
data: {"usage":{"inputCharacters":42,"cacheHit":false}}The stream starts with meta, then one or more pieces of text follow as delta.
The first event contains the request ID, language code and mode.
Each delta contains a part of the result, and done contains the usage information.
After done, the connection closes.
Async job with polling
Idempotency-Key prevents duplicate jobs when you resend a request after a timeout or connection failure. Choose a new key for each new job, for example a UUID. This is a request identifier you create, not your API key.
Create endpoint
POST /api/v2/jobs
Status endpoint
GET /api/v2/jobs/{id}
Use 1 to 255 characters: A-Z, a-z, 0-9, dots (.), underscores (_), colons (:) or hyphens (-). Do not use spaces or shorten the key. For every retry, send the same key and the same request body.
The first creation returns HTTP 202. Repeating the same request returns HTTP 200 with the existing job ID. Reusing the key with a different request returns HTTP 409. The same rules apply to batches. The examples below include the header; replace each example key once for each new job or batch.
curl https://api.simple8.de/api/v2/jobs \
-H "Authorization: Bearer $SIMPLE8_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: article-4711-v1" \
-d '{
"text": "Source content in the selected language.",
"locale": "fr",
"mode": "simple-language",
"delivery": {
"type": "polling"
}
}'{
"jobId": "job_poll_001",
"status": "queued",
"expiresAt": "2026-09-03T12:00:00.000Z"
}{
"jobId": "job_poll_001",
"status": "completed",
"locale": "fr",
"mode": "simple-language",
"output": "Simplified content in French.",
"expiresAt": "2026-09-03T12:00:00.000Z"
}Jobs remain available for seven days.
A job moves through queued, processing, completed, or failed. Failed jobs include error.code. Create and status responses include expiresAt.
First, ask the status again after a second. Gradually increase the distance for longer processing.
Async job with webhook
Create and verify a webhook endpoint in the Simple8 application first. Then reference its endpoint ID in the job.
Create endpoint
POST /api/v2/jobs
curl https://api.simple8.de/api/v2/jobs \
-H "Authorization: Bearer $SIMPLE8_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: article-4711-webhook-v1" \
-d '{
"text": "Source content in the selected language.",
"locale": "de",
"mode": "easy-language",
"delivery": {
"type": "webhook",
"endpointId": "00000000-0000-4000-8000-000000000000"
}
}'{
"id": "evt_01",
"type": "job.completed",
"createdAt": "2026-08-06T12:00:00.000Z",
"data": {
"jobId": "job_hook_001",
"status": "completed"
}
}Simple8 sends Simple8-Signature as t=<timestamp>,v1=<signature>. <timestamp> is a Unix timestamp in seconds. The signature is the lowercase hexadecimal output of an HMAC SHA-256 over <timestamp>.<raw request body>.
Check the signature against the unchanged request. You will see the secret signing key once when creating the endpoint.
Return HTTP 200 or 201 as soon as your system accepts the event.
Repeats: If an error occurs, Simple8 tries to deliver within seven days up to 50 times.
Double events: Process each event ID only once, as a repeat can send the same event again.
Batch processing
Send between 1 and 50 items with a combined maximum of 25,000 characters.
Create endpoint
POST /api/v2/batches
Status endpoint
GET /api/v2/batches/{id}
Each item uses the same text, locale, and mode fields as a synchronous request.
Choose polling or a verified webhook endpoint for delivery and send a unique Idempotency-Key header.
curl https://api.simple8.de/api/v2/batches \
-H "Authorization: Bearer $SIMPLE8_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: release-4711-v1" \
-d '{
"items": [
{
"text": "First source text.",
"locale": "en",
"mode": "simple-language"
},
{
"text": "Second source text.",
"locale": "de",
"mode": "easy-language"
}
],
"delivery": {
"type": "polling"
}
}'{
"batchId": "batch_001",
"status": "queued",
"itemCount": 2
}{
"batchId": "batch_001",
"status": "completed",
"itemCount": 2,
"items": [
{
"jobId": "job_001",
"status": "completed",
"locale": "en",
"mode": "simple-language",
"output": "First result."
},
{
"jobId": "job_002",
"status": "failed",
"locale": "de",
"mode": "easy-language",
"error": {
"code": "processing_failed"
}
}
]
}Batch creation returns HTTP 202 the first time and HTTP 200 for an idempotent replay. The webhook events are job.completed, job.failed, batch.completed, and batch.failed. Completed webhook payloads contain identifiers and status only; fetch the job or batch status endpoint to read output.