Create a translation job (legacy multipart)

POST/v1/public/document-translator/jobs

translator:translaterequired scope

Streams a `multipart/form-data` upload (max 100 MiB file, max 1000 pages), debits the prepaid credits tier price, and returns `202` with a poll URL. Idempotent on `Idempotency-Key` per key within 24 h. Requires scope `translator:translate` (10/min · 100/hour · 1,000/day per key). **Superseded** by the direct-to-storage flow (`POST /jobs/intent` → `PUT <uploadUrl>` → `POST /jobs/{jobId}/finalize`) — retained as the fallback while `UPLOAD_MODE=stream` remains a supported server mode; new integrations should use the intent flow.

Parameters

Name	In	Required	Description
idempotency-key	header	—	Replay key. Re-POSTing with the same value within 24 h returns the original response without re-charging. Keys are per-API-key — two different keys using the same value start independent jobs. Replaying the same key with a different payload returns 409 idempotency_conflict.e.g. 019a4d5e-6f7a-7b8c-9d0e-1f2a3b4c5d6e

Request & response

multipart/form-data

{
  "type": "object",
  "required": [
    "file",
    "target"
  ],
  "properties": {
    "file": {
      "type": "string",
      "format": "binary",
      "description": "The PDF to translate (max 100 MiB, 1000 pages). Only `application/pdf` parts are accepted."
    },
    "source": {
      "type": "string",
      "default": "auto",
      "description": "Source language — `auto` (detected at extract time) or an ISO 639-1 code.",
      "enum": [
        "auto",
        "aa",
        "ab",
        "ae",
        "af",
        "ak",
        "am",
        "an",
        "ar",
        "as",
        "av",
        "ay",
        "az",
        "ba",
        "be",
        "bg",
        "bi",
        "bm",
        "bn",
        "bo",
        "br",
        "bs",
        "ca",
        "ce",
        "ch",
        "co",
        "cr",
        "cs",
        "cu",
        "cv",
        "cy",
        "da",
        "de",
        "dv",
        "dz",
        "ee",
        "el",
        "en",
        "eo",
        "es",
        "et",
        "eu",
        "fa",
        "ff",
        "fi",
        "fj",
        "fo",
        "fr",
        "fy",
        "ga",
        "gd",
        "gl",
        "gn",
        "gu",
        "gv",
        "ha",
        "he",
        "hi",
        "ho",
        "hr",
        "ht",
        "hu",
        "hy",
        "hz",
        "ia",
        "id",
        "ie",
        "ig",
        "ii",
        "ik",
        "io",
        "is",
        "it",
        "iu",
        "ja",
        "jv",
        "ka",
        "kg",
        "ki",
        "kj",
        "kk",
        "kl",
        "km",
        "kn",
        "ko",
        "kr",
        "ks",
        "ku",
        "kv",
        "kw",
        "ky",
        "la",
        "lb",
        "lg",
        "li",
        "ln",
        "lo",
        "lt",
        "lu",
        "lv",
        "mg",
        "mh",
        "mi",
        "mk",
        "ml",
        "mn",
        "mr",
        "ms",
        "mt",
        "my",
        "na",
        "nb",
        "nd",
        "ne",
        "ng",
        "nl",
        "nn",
        "no",
        "nr",
        "nv",
        "ny",
        "oc",
        "oj",
        "om",
        "or",
        "os",
        "pa",
        "pi",
        "pl",
        "ps",
        "pt",
        "qu",
        "rm",
        "rn",
        "ro",
        "ru",
        "rw",
        "sa",
        "sc",
        "sd",
        "se",
        "sg",
        "si",
        "sk",
        "sl",
        "sm",
        "sn",
        "so",
        "sq",
        "sr",
        "ss",
        "st",
        "su",
        "sv",
        "sw",
        "ta",
        "te",
        "tg",
        "th",
        "ti",
        "tk",
        "tl",
        "tn",
        "to",
        "tr",
        "ts",
        "tt",
        "tw",
        "ty",
        "ug",
        "uk",
        "ur",
        "uz",
        "ve",
        "vi",
        "vo",
        "wa",
        "wo",
        "xh",
        "yi",
        "yo",
        "za",
        "zh",
        "zu"
      ]
    },
    "target": {
      "type": "string",
      "description": "Target language, ISO 639-1 code.",
      "enum": [
        "aa",
        "ab",
        "ae",
        "af",
        "ak",
        "am",
        "an",
        "ar",
        "as",
        "av",
        "ay",
        "az",
        "ba",
        "be",
        "bg",
        "bi",
        "bm",
        "bn",
        "bo",
        "br",
        "bs",
        "ca",
        "ce",
        "ch",
        "co",
        "cr",
        "cs",
        "cu",
        "cv",
        "cy",
        "da",
        "de",
        "dv",
        "dz",
        "ee",
        "el",
        "en",
        "eo",
        "es",
        "et",
        "eu",
        "fa",
        "ff",
        "fi",
        "fj",
        "fo",
        "fr",
        "fy",
        "ga",
        "gd",
        "gl",
        "gn",
        "gu",
        "gv",
        "ha",
        "he",
        "hi",
        "ho",
        "hr",
        "ht",
        "hu",
        "hy",
        "hz",
        "ia",
        "id",
        "ie",
        "ig",
        "ii",
        "ik",
        "io",
        "is",
        "it",
        "iu",
        "ja",
        "jv",
        "ka",
        "kg",
        "ki",
        "kj",
        "kk",
        "kl",
        "km",
        "kn",
        "ko",
        "kr",
        "ks",
        "ku",
        "kv",
        "kw",
        "ky",
        "la",
        "lb",
        "lg",
        "li",
        "ln",
        "lo",
        "lt",
        "lu",
        "lv",
        "mg",
        "mh",
        "mi",
        "mk",
        "ml",
        "mn",
        "mr",
        "ms",
        "mt",
        "my",
        "na",
        "nb",
        "nd",
        "ne",
        "ng",
        "nl",
        "nn",
        "no",
        "nr",
        "nv",
        "ny",
        "oc",
        "oj",
        "om",
        "or",
        "os",
        "pa",
        "pi",
        "pl",
        "ps",
        "pt",
        "qu",
        "rm",
        "rn",
        "ro",
        "ru",
        "rw",
        "sa",
        "sc",
        "sd",
        "se",
        "sg",
        "si",
        "sk",
        "sl",
        "sm",
        "sn",
        "so",
        "sq",
        "sr",
        "ss",
        "st",
        "su",
        "sv",
        "sw",
        "ta",
        "te",
        "tg",
        "th",
        "ti",
        "tk",
        "tl",
        "tn",
        "to",
        "tr",
        "ts",
        "tt",
        "tw",
        "ty",
        "ug",
        "uk",
        "ur",
        "uz",
        "ve",
        "vi",
        "vo",
        "wa",
        "wo",
        "xh",
        "yi",
        "yo",
        "za",
        "zh",
        "zu"
      ],
      "example": "km"
    },
    "notes_pdf": {
      "type": "string",
      "enum": [
        "true",
        "false"
      ],
      "default": "false",
      "description": "When `true`, append a notes page to the output."
    }
  }
}

Error responses

202Job accepted — debit taken, engine dispatch queued. Poll `pollUrl` until `state` is `done` or `error`.

application/json

{
  "jobId": "019a2c3d-4e5f-7a9b-8c0d-1e2f3a4b5c6d",
  "pagesTotal": 72,
  "tier": "t4",
  "priceCredits": 999,
  "walletAfter": 1301,
  "pollUrl": "/v1/public/document-translator/jobs/019a2c3d-4e5f-7a9b-8c0d-1e2f3a4b5c6d"
}

400Malformed request — missing field or bad value.

application/json

{
  "error": "invalid_request",
  "message": "`source`/`target` must be ISO 639-1 codes; `file` is required.",
  "requestId": "trk_01HKA1B2C3D4E5F6G7H8J9K0M1",
  "correlationId": "019a1b2c-3d4e-7f8a-9b0c-1d2e3f4a5b6c"
}

401Missing or unrecognised API key.

application/json

{
  "error": "missing_authorization",
  "message": "Send `Authorization: Bearer <api-key>`.",
  "requestId": "trk_01HKA1B2C3D4E5F6G7H8J9K0M1",
  "correlationId": "019a1b2c-3d4e-7f8a-9b0c-1d2e3f4a5b6c"
}

402The wallet balance is below the tier price — top up and retry (this error is retryable).

application/json

{
  "error": "insufficient_credits",
  "message": "Wallet balance is below the tier price.",
  "requestId": "trk_01HKA1B2C3D4E5F6G7H8J9K0M1",
  "correlationId": "019a1b2c-3d4e-7f8a-9b0c-1d2e3f4a5b6c",
  "need": 999,
  "have": 120,
  "topUpUrl": "https://inkhmer.com/credits/topup"
}

403The key is valid but lacks the scope this operation requires.

application/json

{
  "error": "scope_missing",
  "message": "This key lacks the required scope.",
  "requestId": "trk_01HKA1B2C3D4E5F6G7H8J9K0M1",
  "correlationId": "019a1b2c-3d4e-7f8a-9b0c-1d2e3f4a5b6c",
  "requiredScope": "translator:read"
}

409The same `Idempotency-Key` was replayed with a different payload (different file hash/size).

application/json

{
  "error": "idempotency_conflict",
  "message": "Idempotency-Key was already used with a different payload.",
  "requestId": "trk_01HKA1B2C3D4E5F6G7H8J9K0M1",
  "correlationId": "019a1b2c-3d4e-7f8a-9b0c-1d2e3f4a5b6c"
}

413The file exceeds 100 MiB, or the document has more than 1000 pages (contact tier).

application/json

{
  "error": "payload_too_large",
  "message": "File exceeds the 100 MiB limit.",
  "requestId": "trk_01HKA1B2C3D4E5F6G7H8J9K0M1",
  "correlationId": "019a1b2c-3d4e-7f8a-9b0c-1d2e3f4a5b6c",
  "maxBytes": 104857600,
  "maxPages": 1000,
  "nextStep": "split_or_contact"
}

415The request Content-Type is not `multipart/form-data`, or the `file` part is not `application/pdf`.

application/json

{
  "error": "unsupported_media_type",
  "message": "Send `Content-Type: multipart/form-data` with a `file` part.",
  "requestId": "trk_01HKA1B2C3D4E5F6G7H8J9K0M1",
  "correlationId": "019a1b2c-3d4e-7f8a-9b0c-1d2e3f4a5b6c",
  "accepted": [
    "multipart/form-data"
  ]
}

429Per-key or per-account rate limit exhausted. Retry after the `Retry-After` interval (see the rate-limit table).

application/json

{
  "error": "rate_limited",
  "message": "Rate limit exhausted — retry after the interval.",
  "requestId": "trk_01HKA1B2C3D4E5F6G7H8J9K0M1",
  "correlationId": "019a1b2c-3d4e-7f8a-9b0c-1d2e3f4a5b6c",
  "retryAfter": 42
}

500Engine failure — the wallet debit is refunded when one was taken.

application/json

{
  "error": "internal_error",
  "message": "Something went wrong — retry shortly.",
  "requestId": "trk_01HKA1B2C3D4E5F6G7H8J9K0M1",
  "correlationId": "019a1b2c-3d4e-7f8a-9b0c-1d2e3f4a5b6c"
}

503A required upstream (OpenRouter, Bayla, key verification) is unavailable — the wallet debit is refunded when one was taken.

application/json

{
  "error": "upstream_unavailable",
  "message": "A required upstream is unavailable — retry shortly.",
  "requestId": "trk_01HKA1B2C3D4E5F6G7H8J9K0M1",
  "correlationId": "019a1b2c-3d4e-7f8a-9b0c-1d2e3f4a5b6c"
}