⚡ Quick Start

This guide walks through one document translation from start to finish: upload → wait for processing → start translation → wait for the result → download. The same flow works for every supported file type — PDF, Word, PowerPoint, Excel, InDesign (IDML) and more. See Supported file types for the full list.

🤖 Work with Agents

Building with a coding agent such as Claude Code, Codex or Cursor? Start here.

Copy this prompt

Paste it into your agent to get started:

Read Bluente's API docs at https://www.bluente.com/docs/quickstart and the agent skill at https://github.com/Bluente/bluente-api-skill, then help me translate documents with the Bluente API.

Install the agent skill

Bluente API skill teaches your agent the whole flow, the error codes and the options, with example clients in bash, Python and TypeScript. Install it once, and your agent uses it whenever you work with the Bluente API. Installation steps are in the repository’s README.

Translate from chat with MCP

Don’t need to write code? With MCP, you can translate documents straight from Claude, ChatGPT, Codex and other AI clients: attach a file, name the language, and get the translated file back.

📋 Before You Start

• API key. Create one on the API Keys page and send it on every request as Authorization: Bearer $BLUENTE_API_KEY. See API Key.
• Base URL. All endpoints below sit under https://api.bluente.com/api/20250924/blu_translate.
• Check code, not the HTTP status. Every response is returned with HTTP status 200. A request succeeded only when the JSON body has "code": 0. See Error Codes.
• Credits. Translation is charged when it starts. Call Get Account to see your balance.

🗺️ The Flow at a Glance

At any point, a status of ERROR, CANCELLED or CREDITS_INSUFFICIENT means the task has stopped. Read the message field, then stop polling. Any status not shown in this guide is a brief intermediate step: keep waiting.

1️⃣ Upload the Document

Send the file as multipart/form-data in a field named file. The filename must include its extension (for example contract.docx), because the extension tells Bluente which file type it is.

curl -X POST "https://api.bluente.com/api/20250924/blu_translate/upload?engine=3" \
     -H "Authorization: Bearer $BLUENTE_API_KEY" \
     -F "file=@/path/to/contract.docx"

{
  "message": "success",
  "code": 0,
  "data": {
    "id": 12345,
    "language": "",
    "sub_task_ids": null
  }
}

• Keep data.id. It identifies this document in every later call.
• engine chooses the translation engine: 3 = LLM, 4 = LLM Pro. Use the same engine value in step 3.

Details: Upload File.

2️⃣ Wait for Processing

Upload is asynchronous. The id comes back as soon as the file is received; Bluente then opens the file and counts its pages. Poll Get Translation Status until status is SERVICE_PROCESSED.

curl -X GET "https://api.bluente.com/api/20250924/blu_translate/check?id=12345" \
     -H "Authorization: Bearer $BLUENTE_API_KEY"

{
  "message": "success",
  "code": 0,
  "data": {
    "id": 12345,
    "serviceCode": 0,
    "pageCount": 8,
    "status": "SERVICE_PROCESSED",
    "message": "File is ready for translation",
    "updatedAt": "2026-10-23 10:15:23"
  }
}

Starting the translation before processing finishes fails with code: 40, because the page count is not known yet.

Details: Get Translation Status.

3️⃣ Start the Translation

Call Translate File with the task id, action: "start", and the source and target language codes. Use the same engine as the upload.

curl -X POST "https://api.bluente.com/api/20250924/blu_translate/translate?engine=3" \
     -H "Authorization: Bearer $BLUENTE_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
           "id": 12345,
           "action": "start",
           "from": "en",
           "to": "fr",
           "meta_data": { "job_id": "your-own-reference" }
         }'

{
  "message": "success",
  "code": 0
}

• Language codes come from Supported languages.
• meta_data is optional. Any JSON object you put here is returned unchanged in the Webhook, which helps you match a result to your own job.
• Common errors: 70 = not enough credits, 80 = this task was already started, 40 = an invalid language or option. See Error Codes.
• To check your options without starting the translation or spending credits, send the same request to Validate Options first.
• Other options (glossary, bilingual output, scanned documents) are described in Translate File. Some options don’t apply to every file type — for example, InDesign files have their own limits. See InDesign (IDML).

4️⃣ Wait for the Translation

Poll the same Get Translation Status call until status is READY or ERROR.

curl -X GET "https://api.bluente.com/api/20250924/blu_translate/check?id=12345" \
     -H "Authorization: Bearer $BLUENTE_API_KEY"

• Most documents finish within 2–5 minutes. Large documents (100+ pages) can take 15–20 minutes.
• Checking every 10–30 seconds is enough.
• Instead of polling, you can set a Webhook URL. Bluente then calls it once when the task becomes READY or ERROR.

5️⃣ Download the Result

When status is READY, download the translated file.

curl -X GET "https://api.bluente.com/api/20250924/blu_translate/download?id=12345" \
     -H "Authorization: Bearer $BLUENTE_API_KEY" \
     -o translated_contract.docx

• Without to_type, the file comes back in the same format you uploaded. InDesign files always come back as .idml.
• The suggested filename is in the Content-Disposition response header.
• On error, the response is JSON instead of a file. Check the Content-Type header, or look for a code field, before you save the response.

Details: Download File.

📌 What’s Next

• Webhook — get notified instead of polling.
• Glossary — keep terminology consistent across documents.
• OCR — translate scanned documents.
• History — list your past tasks.