Skip to main content

Getting Started

This page walks you through the smallest end-to-end Ollang workflow: create an account, get an API key, upload a file, create a translation order, and read the result. You can then branch into the REST API, MCP, SDK, or Skills.

Prerequisites

  • An Ollang account (free to sign up).
  • An API key generated from the Olabs Dashboard.
  • curl (or your favorite HTTP client) for the examples below.
  • About 5 minutes.
Export your API key once so the examples below can read it:
Code samples on this page read the key from $OLLANG_API_KEY and use generic placeholders such as <project-id> and <order-id> — replace them with values from your account. Never commit API keys to source control.

1. Verify the API Is Reachable

Run the unauthenticated health check to confirm connectivity from your environment:
Expected response:
Full reference: Health Check.
If the health check fails, check status.ollang.com for an ongoing incident or scheduled maintenance before debugging your own environment.

2. Upload a Source File

Send a file (video, audio, document, subtitle, or image for image-to-image translation) to Ollang. The endpoint returns a projectId you’ll use to create orders.
Expected response (201):
A few notes:
  • sourceLanguage is a case-sensitive BCP-47 tag: a code from Supported Languages or a standard language / language-REGION tag (for example en, es-MX, or fr-CH). Anything else is rejected with 400.
  • folderId is optional; if omitted, uploads land in the default API Uploads folder. You can list folders with Retrieve All Folders.
  • Maximum sizes: 30 GB for video, 100 MB for documents (5 MB in the in-page API playground).
Full reference: Direct File Upload.

3. Create a Translation Order

With a projectId, create one or more orders. Each targetLanguageConfigs entry creates an order for that language — the response is an array of { orderId, orderType } objects for every order the request created, in no guaranteed order.
Expected response (201):
What the parameters mean:
  • orderType — cc, subtitle, document, aiDubbing, or studioDubbing. Full table at Order Types.
  • level — 0 for full-AI, 1 to add Ollang’s human review gate.
  • callbackUrl (optional) — Ollang POSTs the completed order payload here. Idempotent handlers recommended (10-second timeout).
  • autoQc (optional) — Run an AI QC evaluation automatically once the order completes.
Full reference: Create Order.

4. Check Status (or Wait for the Callback)

Poll the order until status === "completed":
Excerpted response:
All possible status values are listed in Order Statuses. Document type names (e.g. created_subtitle, created_ai_dub_audio) are listed in Order Document Types.
If you provided a callbackUrl, you don’t need to poll — Ollang POSTs the same payload to your URL when the order completes. Confirmation via Get Order by ID is still a good safety net.

5. (Optional) Upgrade to Human Review

Any AI-generated (Level 0) order can be escalated to Ollang-managed linguists after the fact:
Reference: Request Human Review. Need to back it out? See Cancel Human Review.

What’s Next

How everything connects

Choose between REST API, MCP, SDK, or Skills — and learn how they overlap.

Use Cases

End-to-end walkthroughs: AI dubbing, subtitle pipelines, document localization, visual translation, continuous i18n.

Best Practices

Production guidance: callbacks, retries, pagination, folder structure, memory, and review gates.

API Conventions

Base URL, authentication, pagination, errors, and webhook format in one place.

MCP Quickstart

Run the same workflow from Claude Desktop, Cursor, or Claude Code in 5 minutes.

SDK Quickstart

Scan a Next.js / React / Vue project for i18n strings and translate them.

Skills Quickstart

Give your AI agent natural-language access to Ollang — no MCP server needed.

Glossary

Folder, Project, Order, Level, Workflow, Review Gate, LSP, BYOK, QC — defined in one place.

Troubleshooting

Auth errors, callback issues, retries, rate limits, and how to file a good bug.