# 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. |
| `summarize` / `presentation_maker` | `POST /v3/summarization` | Turns a DOCX/PDF into a **PowerPoint deck** (a Presentation Maker, not a text summary). |
| `presenter` | `POST /v3/upload` → `/v3/create/transcripts` → `/v3/create/video` | Presentation **video** from a PPTX/PDF (3-step: upload → transcripts → render). |
| `meeting_notes` (Note-Taker) | `POST /audio2dialog` → `POST /dialog2meeting` | Meeting audio → speaker dialog → structured notes (markdown + DOCX). **Different base URL — see below.** |
| `translate_xml` | `POST /v4/xml-document` | Translate an XML/HTML document while preserving all tags. |
| `get_upload_url` | `POST /v3/upload` · `POST /v4/upload/presign` | 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` 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, docx_url}`.
- A bad key returns `401 INVALID_API_KEY`.

> These two are **not** in the OpenAPI spec (different service) — call them directly at the base URL above.

## 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](../mcp-model-context-protocol) 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.