docs: new file formats GA — drop beta labels, document the 50k billing floor by yoshiamakino · Pull Request #481 · DeepL/api-docs

yoshiamakino · 2026-11-02T15:33:06Z

What

Ten formats introduced in beta on Sept 29 (xlsm, zip/SCORM, vtt, yaml/yml, properties, strings, md/markdown, resx, odt, rtf) plus jpeg/png image translation are generally available as of 2026-11-02 (TW-2713). This PR:

Strips (currently in beta) from the format lists in openapi.yaml, openapi.json, and the format-gotcha headers in document-translations.mdx (54 labels).
Billing minimums — replaces the stale "beta formats are not billed" claim with the actual GA rule:
- Document-like formats (.docx, .doc, .pptx, .xlsx, .xlsm, .pdf, .odt, .rtf, SCORM .zip, .jpeg/.png, .idml, .mif) → 50,000-character minimum per document.
- Text-like formats (.txt, .html, .xml, .json, .yaml/.yml, .properties, .strings, .md, .dita, .xlf/.xliff, .srt, .vtt, .resx) → exact character count, no minimum.
- Updated in document-translations.mdx (Billing minimums), translate-documents-quickstart.mdx, and usage-limits.mdx.
Adds a November 2 changelog entry; updates the format list in about.mdx.

Verification

Floor behavior verified live in prod on release day (Databricks: JPEG 341 docs/46 floored, IDML 58/44, PNG 22/5, YAML 70 exact).
All 20 format probes (12 new + controls) translated and downloaded successfully against production.
The Sept 29 changelog entry is intentionally left as-is (historical record).

Jira: TW-2713

…g floor Ten beta formats (xlsm, zip/SCORM, vtt, yaml, properties, strings, md, resx, odt, rtf) plus jpeg/png image translation are generally available as of 2026-11-02 (TW-2713). - Strip '(currently in beta)' from the format lists in openapi.yaml, openapi.json, and the document-translations gotcha headers. - Billing minimums: document-like formats (docx, doc, pptx, xlsx, xlsm, pdf, odt, rtf, SCORM zip, jpeg/png, idml, mif) bill a 50,000-character minimum; text-like formats bill exact characters. Replaces the old 'beta formats are not billed' claim in document-translations, translate-documents-quickstart, and usage-limits. - Changelog entry for November 2; about.mdx format list updated.

mintlify · 2026-11-02T15:33:12Z

Preview approval required

This pull request comes from a fork, so Mintlify won't build a preview until someone with write access approves commit 855fc8d.

Approve preview

kabraham13 · 2026-11-02T15:59:53Z

 </Update>

 <Update label="October 2026">
+## November 2 - New File Formats Generally Available


This entry is inside <Update label="October 2026">, but a <Update label="November 2026"> block already exists above (it holds "November 2 - Custom Instructions for Document Translation"). Please move this entry into the November block so the changelog label and RSS grouping are correct.

Good catch — moved the Nov 2 GA entry into the November 2026 <Update> block (it now sits after the Custom Instructions entry). Fixed in 855fc8d.

kabraham13 · 2026-11-02T15:59:53Z


 <Update label="October 2026">
+## November 2 - New File Formats Generally Available
+- Ten formats introduced in beta on September 29 — `xlsm` (macro-enabled Excel), `zip` (SCORM e-learning packages), `vtt` (WebVTT subtitles), `yaml` / `yml`, `properties` (Java properties), `strings` (iOS/macOS strings), `md` / `markdown`, `resx` (.NET resources), `odt` (OpenDocument Text), and `rtf` (Rich Text Format) — plus `jpeg` / `png` image translation, are now generally available in [`POST /v2/document`](/api-reference/document/upload-and-translate-a-document). They are no longer marked beta and are now billed like other formats.


"are now billed like other formats" is the sentence beta users will read as the price change, and the next bullet then gives two different rules (50k floor vs exact count). Suggest saying it directly, e.g. "During beta these formats were not billed. They now count toward your character usage, with the billing rules below."

Agreed — reworded to: "During beta these formats were not billed. They now count toward your character usage, with the billing rules below." Fixed in 855fc8d.

kabraham13 · 2026-11-02T15:59:53Z


 *DeepL supports XLIFF versions 1.2, 2.0, and 2.1 (2.1 shares the 2.0 core namespace).<br />
-**Currently in Beta. During the Beta phase, characters translated in these file formats are not billed and not counted against your character threshold.
+Document-like formats (`.docx`, `.doc`, `.pptx`, `.xlsx`, `.xlsm`, `.pdf`, `.odt`, `.rtf`, SCORM `.zip`, `.jpeg`/`.png`, `.idml`, `.mif`) are billed a minimum of 50,000 characters per document; text-like formats are billed for their exact character count. See [Document translations](/docs/best-practices/document-translations#billing-minimums).


Two things here:

The old **Currently in Beta footnote carried the ** marker. It is gone now, but ten table rows above still end in \*\* (YAML, Properties, Strings, Markdown, WebVTT, SCORM, RESX, ODT, RTF, Images), so they point at nothing. Please remove those markers.

This sentence now sits directly under the XLIFF * footnote and reads as part of it. Make it its own paragraph, or a <Note>.

Both fixed in 855fc8d: removed the orphaned \*\* markers from all ten table rows (XLIFF keeps its single \* footnote), and the billing sentence is now its own paragraph after the XLIFF footnote.

kabraham13 · 2026-11-02T15:59:53Z


 ### Billing minimums
-Every submitted document of type `.pptx`, `.docx`, `.doc`, `.xlsx`, or `.pdf` is billed a minimum of 50,000 characters on DeepL API plans, no matter how many characters the document contains. Formats currently in beta are not billed and are not subject to this minimum.
+Documents of type `.docx`, `.doc`, `.pptx`, `.xlsx`, `.xlsm`, `.pdf`, `.odt`, `.rtf`, SCORM (`.zip`), `.jpeg`/`.png`, `.idml`, and `.mif` are billed a minimum of 50,000 characters on DeepL API plans, no matter how many characters the document contains. Text-like formats (`.txt`, `.html`, `.xml`, `.json`, `.yaml`/`.yml`, `.properties`, `.strings`, `.md`, `.dita`, `.xlf`/`.xliff`, `.srt`, `.vtt`, `.resx`) are billed for their exact character count with no minimum.


The two lists here (and the same lists in the changelog, usage-limits.mdx and the quickstart warning) don't match the supported-formats list:

.doc is listed for billing but is not a supported format in the openapi format list.

.htm, .jpg and .markdown are supported but missing from the billing lists.

Since each list reads as a closed set, please make them consistent (or add a "and their alternate extensions" note).

Fixed in 855fc8d — all four billing lists (this section, changelog, usage-limits, quickstart warning) now match the supported-format list: added .jpg, .htm/.html, and .md/.markdown; the Images row is now .jpeg/.jpg/.png. Kept .doc since it's accepted by the API (Word legacy) even though it's not a separate bullet in the openapi list — happy to drop it if you'd rather the list mirror the bullets exactly.

…st consistency - Move the Nov 2 GA entry into the November 2026 <Update> block. - State the billing change directly: beta formats were not billed, now they count toward character usage with the rules below. - Remove orphaned ** markers from the usage-limits table rows (footnote deleted) and give the billing sentence its own paragraph. - Align billing lists with the supported-format list: add .jpg, .htm, .markdown; Images row now .jpeg/.jpg/.png.

kabraham13

Checked 855fc8d against the earlier comments: changelog entry is in the November block, orphaned footnote markers are gone, the billing sentence is explicit, and the format lists now include .jpg/.htm/.markdown. Keeping .doc is fine since the usage-limits table lists Word as .docx / .doc.

yoshiamakino requested a review from shirgoldbird November 2, 2026 15:40

yoshiamakino self-assigned this Nov 2, 2026

yoshiamakino requested a review from kabraham13 November 2, 2026 15:41

kabraham13 reviewed Nov 2, 2026

View reviewed changes

kabraham13 requested changes Nov 2, 2026

View reviewed changes

kabraham13 approved these changes Nov 2, 2026

View reviewed changes

yoshiamakino merged commit 0438488 into DeepL:main Nov 2, 2026
1 of 2 checks passed

Navigation Menu

Repository navigation

docs: new file formats GA — drop beta labels, document the 50k billing floor - #481

docs: new file formats GA — drop beta labels, document the 50k billing floor#481
yoshiamakino merged 2 commits into
DeepL:mainfrom
yoshiamakino:docs/ga-new-file-formats

yoshiamakino commented Nov 2, 2026

Uh oh!

mintlify Bot commented Nov 2, 2026 •

edited

Loading

Uh oh!

kabraham13 Nov 2, 2026

Uh oh!

yoshiamakino Nov 2, 2026

Uh oh!

kabraham13 Nov 2, 2026

Uh oh!

yoshiamakino Nov 2, 2026

Uh oh!

kabraham13 Nov 2, 2026

Uh oh!

yoshiamakino Nov 2, 2026

Uh oh!

kabraham13 Nov 2, 2026

Uh oh!

yoshiamakino Nov 2, 2026

Uh oh!

kabraham13 left a comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

yoshiamakino commented Nov 2, 2026

What

Verification

Uh oh!

mintlify Bot commented Nov 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Preview approval required

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kabraham13 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mintlify Bot commented Nov 2, 2026 •

edited

Loading