> For the complete documentation index, see [llms.txt](https://developer.doctranslate.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.doctranslate.io/agent-plugin-and-ai-integration.md).

# Agent Plugin & AI Integration

Connect DocTranslate.io to AI agents and automation platforms. The DocTranslate Agent Plugin exposes the same public REST API as OpenAPI + platform manifests + language SDKs, so an autonomous agent can translate documents, text, images, audio and video, run PDF tools, and fill forms — using a single API key.

## Base URL & Auth

* **Base URL:** `https://doctranslate-api.doctranslate.io`
* **Auth:** header `X-API-Key: <key>` **or** `Authorization: Bearer <key>`
* **Get a key:** DocTranslate app → Settings → API Keys. Keys start with `dtl_`.

## Machine-readable spec (for agents)

Point your agent's tool loader at the OpenAPI spec:

* [**Download the OpenAPI spec** (openapi.yaml)](https://pub-bf5af811d50c430a8fb9e8245625c242.r2.dev/agent-docs/openapi.yaml) — load this into your agent's tool loader.
* [**Agent quick-reference** (markdown)](https://pub-bf5af811d50c430a8fb9e8245625c242.r2.dev/agent-docs/doctranslate-agents.md)

The spec is generator-stamped from the live server, so parameter names, enums and status codes match production exactly.

## Tools

| Tool                 | Endpoint                                           | Notes                                                                                                         |
| -------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `translate_text`     | `POST /v3/translate/text`                          | Returns a `task_id`; poll `get_result`.                                                                       |
| `translate_document` | `POST /v3/translate/document`                      | DOCX/PDF/PPTX/XLSX/XML/HTML. Keeps layout.                                                                    |
| `translate_image`    | `POST /v3/translate/images`                        | Translate text in an image.                                                                                   |
| `translate_media`    | `POST /v4/translate/audio` · `/v4/translate/video` | Subtitle by default; set `export_audio`/`export_video` for a dubbed result (video → dubbed video end-to-end). |
| `pdf_tool`           | `POST /v3/pdf-tools/{tool}`                        | 29 PDF operations (convert, merge, split, rotate, compress…).                                                 |
| `data_entry`         | `POST /v3/data-entry`                              | Extract fields from a document and fill a form/template.                                                      |
| `get_upload_url`     | `POST /v3/upload`                                  | Presigned R2 PUT for large files; then pass the returned `file_key`.                                          |
| `get_result`         | `GET /v3/result/{task_id}`                         | Poll async tasks; returns text + a presigned download URL.                                                    |

### Key parameters

* **Languages:** `dest_lang` (target). Source hint: **`original_lang`** for text/document/image; **`source_lang`** for audio/video. Omit the source to auto-detect.
* **`file_type`:** MIME-style enum, e.g. `application/docx`, `application/pdf`, `application/pptx`, `application/xlsx`.
* **`domain` / `tone`:** exact enum strings (e.g. `"Legal Documents"`, `"Formal"`) — a `422` response lists the valid values.
* **Async contract:** dispatch endpoints return **`200`** with `{ data: { task_id } }`; poll `get_result` until it returns the output + download URL.

### Note-Taker & Presenter (a different base URL)

meeting\_notes (Note-Taker) and presenter (Presentation Video) are served by the main app, not the translation-file host. Use base URL <https://www.doctranslate.io/api/v1/third-party/> with the same X-API-Key.

* Note-Taker: POST /note-taker/audio2dialog (multipart files) -> poll GET /note-taker/audio2dialog/{task\_id} for data.result.dialog\_url; then POST /note-taker/dialog2meeting -> poll GET /note-taker/dialog2meeting/{task\_id} for data.result.markdown and docx\_url.
* Presenter (Presentation Video): POST /v3/upload (task\_type=document, PPTX/PDF) -> POST /v3/create/transcripts -> POST /v3/create/video. These two are not in the OpenAPI spec; a bad key returns 401 INVALID\_API\_KEY.

## Quick start (cURL)

```bash
# 1) submit
curl -s https://doctranslate-api.doctranslate.io/v3/translate/document \
  -H "X-API-Key: dtl_xxx" \
  -F "file=@report.docx" -F "file_type=application/docx" -F "dest_lang=vi"
# -> { "data": { "task_id": "..." } }

# 2) poll
curl -s https://doctranslate-api.doctranslate.io/v3/result/<task_id> \
  -H "X-API-Key: dtl_xxx"
# -> { "data": { "status": "success", "url_download": "https://..." } }
```

## SDKs

* **JavaScript / TypeScript:** `@doctranslate/sdk` — `new DocTranslate({ apiKey }).translateDocument({ file, dest_lang })`
* **Python:** `doctranslate` — `DocTranslate(api_key=...).translate_document(file=..., dest_lang="vi")`

Both wrap the same endpoints and auth. See the plugin repository for full method signatures.

## Supported agent platforms

The plugin ships ready-to-install manifests for:

* **Model Context Protocol (MCP)** — see the [MCP](broken://pages/80d2811c569c38951574c4938d99ea3b4d44ef9f) page.
* **Composio**, **Pi**, and **Custom GPT / OpenAI plugin** — install the manifest, paste your API key, done.

Any platform that accepts an OpenAPI 3 spec can consume the API directly from the OpenAPI URL above.

## Notes

* `Every tool deducts credit per completed task; a bad key returns 401.`
* Enhanced-conversion and billing are unaffected — the plugin only calls the public translation API.