manilo.ai / developers / quickstart

Your first translation in five steps.

You need a manilo account with some balance and an IDML file. All examples use curl. A complete Python script follows at the end.

Before you start

Create an API key in the manilo app under API access. The key is shown once, so store it right away. The examples read it from an environment variable:

export MANILO_API_KEY="mnl_live_..."

All endpoints live under https://app.manilo.ai/api/v1.

1 · Upload the file

curl -X POST https://app.manilo.ai/api/v1/upload/ \
  -H "Authorization: Bearer $MANILO_API_KEY" \
  -F "file=@catalogue.idml"

The response describes the document. Keep filename: it is the file_id for every following call.

{
  "filename": "3f2b8c1e-5d47-4a9b-9c1e-7a2d4e6f8b10.idml",
  "file_size": 482113,
  "total_characters": 6000,
  "translatable_segments": 214,
  "stories_count": 37,
  "estimated_cost_per_language": 30.0
}

2 · Request a quote

A quote fixes the price for these languages. It is free and valid for 15 minutes.

curl -X POST https://app.manilo.ai/api/v1/quotes \
  -H "Authorization: Bearer $MANILO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file_id": "3f2b8c1e-5d47-4a9b-9c1e-7a2d4e6f8b10.idml", "source_language": "de", "target_languages": ["en-gb", "fr"]}'

Check total_cost and can_start. If can_start is false, blocked_reason says why, for example insufficient_funds.

{
  "quote_id": "0b9d6f0e-2f0a-4d0e-8f43-0d6f7f0d7c11",
  "total_words": 2000,
  "total_cost": 60.0,
  "currency": "EUR",
  "available_funds": 150.0,
  "can_start": true,
  "expires_at": "2027-01-15T10:15:00Z"
}

3 · Start the translation

curl -X POST https://app.manilo.ai/api/v1/quotes/0b9d6f0e-2f0a-4d0e-8f43-0d6f7f0d7c11/start \
  -H "Authorization: Bearer $MANILO_API_KEY"

You get a job with a job_id. Calling this endpoint again for the same quote returns the same job, so a retry is always safe.

4 · Wait for the job

curl https://app.manilo.ai/api/v1/jobs/JOB_ID \
  -H "Authorization: Bearer $MANILO_API_KEY"

Poll every few seconds until status is completed or failed. progress runs from 0 to 100. A translation usually takes a few minutes, depending on length and number of languages.

5 · Download the result

curl -o result.zip https://app.manilo.ai/api/v1/jobs/JOB_ID/download \
  -H "Authorization: Bearer $MANILO_API_KEY"

The ZIP archive holds one IDML file per language. Add ?language=fr to fetch a single file. Results are kept for 24 hours.

Handing files over in a chat

An assistant in a chat usually cannot send or receive files itself. Two endpoints cover that case, and neither needs the API key on the user side:

curl -X POST https://app.manilo.ai/api/v1/upload-links \
  -H "Authorization: Bearer $MANILO_API_KEY"

# no API key needed here
curl -F "file=@catalogue.idml" "$UPLOAD_URL"

The whole flow in Python

import os, time, requests

API = "https://app.manilo.ai/api/v1"
auth = {"Authorization": "Bearer " + os.environ["MANILO_API_KEY"]}

with open("catalogue.idml", "rb") as f:
    upload = requests.post(API + "/upload/", headers=auth, files={"file": f})
upload.raise_for_status()

quote = requests.post(API + "/quotes", headers=auth, json={
    "file_id": upload.json()["filename"],
    "source_language": "de",
    "target_languages": ["en-gb", "fr"],
}).json()
print("Price:", quote["total_cost"], quote["currency"])
if not quote["can_start"]:
    raise SystemExit("Cannot start: " + quote["blocked_reason"])

job = requests.post(API + "/quotes/" + quote["quote_id"] + "/start", headers=auth).json()
while job["status"] in ("pending", "processing"):
    time.sleep(5)
    job = requests.get(API + "/jobs/" + job["job_id"], headers=auth).json()
if job["status"] != "completed":
    raise SystemExit("Job " + job["status"] + ": " + str(job["error_message"]))

result = requests.get(API + "/jobs/" + job["job_id"] + "/download", headers=auth)
with open("result.zip", "wb") as f:
    f.write(result.content)

Try it without spending anything

Create a sandbox key (it starts with mnl_test_) and run the same calls. Nothing is translated or charged, and the result is a copy of your file. See Authentication.

Get notified instead of polling

Register a webhook and manilo calls your server when a job is finished or has failed.

Next

Authentication explains scopes, limits and error codes. The API reference lists every endpoint and field.