Skip to main content
Glama
Sign In

Vaquill

by io.github.Vaquill-AI
OverviewDiscussionsAdmin

Create Document

create_document

Starts translating a file you uploaded with POST /translation/files.

Charged in pages, when the translation finishes. Submitting costs nothing. The job spends one translation page per physical page of the document, once, on completion, and a job that fails spends nothing.

Authentication: a vq_key_ key holding translate:write. A wildcard (*) key does not hold it: grant it by name in the dashboard.

Asynchronous

You get 202 Accepted, a documentId and a Location header. Poll GET /translation/documents/{id} until status is completed (or failed), then download with GET /translation/documents/{id}/content. Documents take from seconds to several minutes depending on length.

What is checked before the job is queued

Everything refusable is refused before anything is queued: an unsupported language (read GET /translation/languages), an unknown outputFormat, courtStyle or engine, an unknown or foreign fileId (404) and an insufficient balance (402).

The balance check uses the page count recorded at upload. For pdf and docx that is exact. For images and plain text the count is not known until the job runs, so the check only confirms you hold at least one page; if the real count is higher than your balance the job ends failed with INSUFFICIENT_TRANSLATION_PAGES and you are not charged.

Whether a scanned document also needs pages from the separate OCR pool is NOT determined at submission and is not checked here. Read GET /translation/balance, which reports both pools.

Formatting the output

courtStyle renders the translation to an Indian court's mandated paper, font, margins and line spacing (Supreme Court and nine High Courts). Omit it for the compact reader-friendly layout, which is about 45% fewer pages. The font mandate applies when targetLanguage is English; an Indic target is always set in Noto Sans, because the mandated Latin faces carry no Devanagari, while paper size, margins and spacing still apply.

Tables, figures and document structure are preserved on every job. That is the default path, not an option, so there is no flag to set.

handwritten: true routes extraction through a vision model that reads handwriting far better than the default OCR, at a higher cost per page to us. Page billing is unchanged either way. Leave it false for born-digital or clean typed documents, where the default is both cheaper and as accurate.

engine selects the translation model: omit it for gpt54 (recommended), gpt54mini for cheaper and faster work on simple text, sarvam for Indic languages. Billing does not change with the engine.

Removing stamps and signatures

Stamp, seal and signature images can be dropped from the rendered output. This is an ACCOUNT setting rather than a per-job field, so it applies to every job this account submits, through the API and the web app alike. Set it once in your Anuvad profile and this route honours it. Images are classified and only removed above a confidence threshold, so an unclear mark is kept rather than guessed away.

No URLs

This route does not accept a URL, only a fileId. A sourceFileUrl field is a 422.

Duplicates

Submitting the same fileId with the same languages and format again while the first job is still running returns that job (still 202) instead of starting a second one. Once it has finished, the same request starts a new job.

Example

curl -X POST https://api.vaquill.ai/api/v1/translation/documents \
  -H "Authorization: Bearer $VAQUILL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileId": "3f2c9a52-8d2e-4a43-9e0b-5b6a1c7d9f10", "targetLanguage": "hi", "sourceLanguage": "en", "outputFormat": "pdf"}'
{
  "documentId": "9b1d5c0e-7a64-4f0a-8d3b-2c5e6f7a8b90",
  "status": "pending",
  "progress": 0,
  "sourceLanguage": "en",
  "targetLanguage": "hi",
  "outputFormat": "pdf",
  "pagesCharged": null,
  "createdAt": "2026-11-01T12:34:56Z",
  "completedAt": null,
  "error": null
}

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "fileId": "<fileId>",
      "targetLanguage": "<targetLanguage>"
    },
    "name": "create_document"
  }
}

Input Schema

NameRequiredDescriptionDefault
engineNoTranslation engine. Omit for the default (`gpt54`), which is the balance we recommend. `gpt54mini` is cheaper and faster on simple text; `sarvam` is tuned for Indic languages. Page billing does not change with the engine.
fileIdYesThe `fileId` returned by `POST /translation/files`.
courtStyleNoIndian-court formatting profile for the rendered output. When set, the document uses that court's mandated paper, font, margins and line spacing instead of the compact reader-friendly layout. Omit it (the default) for the compact layout. An unknown value is a 422. Note: the font mandate is applied when `targetLanguage` is English. Indic targets are always rendered in Noto Sans, because the mandated Latin faces have no Devanagari coverage; paper size, margins and spacing still apply.
handwrittenNoSet true for a scanned or handwritten document. Routes extraction through a vision model that reads handwriting far better than the default OCR, at a higher cost per page. Page BILLING is unchanged: pages are counted the same way either way. Leave false for a born-digital or clean typed document, where the default path is both cheaper and as accurate.
outputFormatNoFormat of the translated document: `pdf` (default), `docx` or `text`.pdf
sourceLanguageNoLanguage of the document, or `auto` (the default) to detect it.auto
targetLanguageYesLanguage to translate INTO. A code from `GET /translation/languages` with `target: true`.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations only declare readOnly=false, destructive=false, openWorld=false; the description adds substantially more: page-based billing only on completion, failed jobs costing nothing, the 202 async contract, duplicate-request coalescing, and the account-level stamp removal that is not a per-job field. That is exactly the kind of behavior annotations cannot express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is long, but front-loaded (cost, auth, async flow, validation) and sectioned so an agent can skim to the part it needs. The curl invocation and the full JSON response example are redundant given an output schema exists, which keeps it out of the top band.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a billed async mutation with 7 parameters, this covers cost model, auth scope, polling loop, pre-queue refusals, deduplication, and the account-level output setting. With an output schema present, it is not obligated to describe return fields and correctly does not rely on doing so.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, and the description does repeat much of the per-parameter text verbatim (engine, courtStyle, handwritten). It earns above baseline by adding meaning the schema lacks: the fileId must come from the upload route, no URL form is accepted, and the balance check behaves differently for pdf/docx versus images and text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource: starting a translation job on a file previously uploaded via POST /translation/files. It names the prerequisite route, which cleanly separates it from upload_file (the sibling that creates the fileId) and from translate_text (the synchronous text-only alternative).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit workflow guidance: upload first, submit, poll GET /translation/documents/{id} until completed, then download content. It also states what is rejected up front and notes that no URL is accepted (sourceFileUrl is a 422). The only gap is that it never names translate_text as the alternative for short plain text, leaving that routing to the sibling's own definition.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Vaquill toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources