From 68b2d80cc87fd973c272cb1680a3515825df421a Mon Sep 17 00:00:00 2001 From: Nuno Pereira Date: Thu, 23 Oct 2025 14:23:09 +0100 Subject: [PATCH 1/2] Add documentation regarding new endpoint for ToMarkdown --- .../features/markdown-conversion.mdx | 93 +++++++++++++++++-- 1 file changed, 83 insertions(+), 10 deletions(-) diff --git a/src/content/docs/workers-ai/features/markdown-conversion.mdx b/src/content/docs/workers-ai/features/markdown-conversion.mdx index 56c5137a772de6..fd628d438fd58f 100644 --- a/src/content/docs/workers-ai/features/markdown-conversion.mdx +++ b/src/content/docs/workers-ai/features/markdown-conversion.mdx @@ -13,23 +13,23 @@ import { Code, Type, MetaInfo, Details, Render } from "~/components"; For these reasons, document conversion plays an important role when designing and developing AI applications. Workers AI provides the `toMarkdown` utility method that developers can use from the [`env.AI`](/workers-ai/configuration/bindings/) binding or the REST APIs for quick, easy, and convenient conversion and summary of documents in multiple formats to Markdown language. -## Methods and definitions +## Methods ### async env.AI.toMarkdown() -Takes a list of documents in different formats and converts them to Markdown. +Takes a document or list of documents in different formats and converts them to Markdown. #### Parameter -- documents: - An array of - `toMarkdownDocument`s. +- files: - an instance of or an array of + `MarkdownDocument`s. #### Return values -- results: - An array of - `toMarkdownDocumentResult`s. +- results: - An instance of or an array of + `ConversionResult`s. -### `toMarkdownDocument` definition +#### `MarkdownDocument` definition - `name` @@ -39,23 +39,54 @@ Takes a list of documents in different formats and converts them to Markdown. - A new [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob/Blob) object with the document content. -### `toMarkdownDocumentResult` definition +#### `ConversionResult` definition - `name` - Name of the converted document. Matches the input name. +- `format` + + - The format of this `ConversionResult` object + - `mimetype` - The detected [mime type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/MIME_types/Common_types) of the document. - `tokens` - - The estimated number of tokens of the converted document. + - The estimated number of tokens of the converted document. Only present if `format` is equal to `markdown`. - `data` - - The content of the converted document in Markdown format. + - The content of the converted document in Markdown format. Only present if `format` is equal to `markdown`. + +- `error` + + - The error message explaining why this conversion failed. Only present if `format` is equal to `error`. + +### async env.AI.toMarkdown().transform() + +This method is similar to `env.AI.toMarkdown` except that it is exposed through a new handle. It takes the same arguments and returns the same values. + +### async env.AI.toMarkdown().supported() + +Returns a list of file formats that are currently supported for markdown conversion. See [Supported formats](#supported-formats) for the full list of file formats that can be converted into Markdown. + +#### Return values + +- results: - An array of all formats supported for markdown conversion. + +#### `SupportedFormat` definition + +- `extension` + + - Extension of files in this format. + +- `mimeType` + + - The [mime type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/MIME_types/Common_types) of files of this format + ## Supported formats @@ -65,6 +96,8 @@ This is the list of support formats. We are constantly adding new formats and up ## Example +### Converting files + In this example, we fetch a PDF document and an image from R2 and feed them both to `env.AI.toMarkdown`. The result is a list of converted documents. Workers AI models are used automatically to detect and summarize the image. ```typescript @@ -79,6 +112,7 @@ export default { const cat = await env.R2.get("cat.jpeg"); return Response.json( + // env.AI.toMarkdown().transform(...) would return the same result await env.AI.toMarkdown([ { name: "somatosensory.pdf", @@ -119,10 +153,42 @@ This is the result: ] ``` +### Getting supported file formats + +```typescript +import { Env } from "./env"; + +export default { + async fetch(request: Request, env: Env, ctx: ExecutionContext) { + return Response.json( + await env.AI.toMarkdown().supported(), + ); + }, +}; +``` + +results in + +```json +[ + { + "extension": ".pdf", + "mimeType": "application/pdf", + }, + { + "extension": ".jpeg", + "mimeType": "image/jpeg", + }, + ... +] +``` + ## REST API In addition to the Workers AI [binding](/workers-ai/configuration/bindings/), you can use the [REST API](/workers-ai/get-started/rest-api/): +### Conversion + ```bash curl https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai/tomarkdown \ -H 'Authorization: Bearer {API_TOKEN}' \ @@ -130,6 +196,13 @@ curl https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai/tomarkdown \ -F "files=@somatosensory.pdf" ``` +### Supported formats + +```bash +curl https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai/tomarkdown/supported \ + -H 'Authorization: Bearer {API_TOKEN}' \ +``` + ## Pricing `toMarkdown` is free for most format conversions. In some cases, like image conversion, it can use Workers AI models for object detection and summarization, which may incur additional costs if it exceeds the Workers AI free allocation limits. See the [pricing page](/workers-ai/platform/pricing/) for more details. From d98b113b8739425bf74a4421a8b4dbfc8ee2aa01 Mon Sep 17 00:00:00 2001 From: Nuno Pereira Date: Thu, 23 Oct 2025 14:49:01 +0100 Subject: [PATCH 2/2] Added changelog entry --- ...10-23-new-markdown-conversion-endpoint.mdx | 38 +++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 src/content/changelog/workers-ai/2025-10-23-new-markdown-conversion-endpoint.mdx diff --git a/src/content/changelog/workers-ai/2025-10-23-new-markdown-conversion-endpoint.mdx b/src/content/changelog/workers-ai/2025-10-23-new-markdown-conversion-endpoint.mdx new file mode 100644 index 00000000000000..7d646eff8fa699 --- /dev/null +++ b/src/content/changelog/workers-ai/2025-10-23-new-markdown-conversion-endpoint.mdx @@ -0,0 +1,38 @@ +--- +title: 'Workers AI Markdown Conversion: New endpoint to list supported formats' +description: You can now programmatically get a list of all supported file formats that can be converted by our Markdown Conversion utility. +date: 2025-10-23 +--- + +Developers can now programmatically retrieve a list of all file formats supported by the [Markdown Conversion utility](/workers-ai/features/markdown-conversion/) in Workers AI. + +You can use the [`env.AI`](/workers-ai/configuration/bindings/) binding: + +```typescript +await env.AI.toMarkdown().supported() +``` + +Or call the REST API: + +```bash +curl https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai/tomarkdown/supported \ + -H 'Authorization: Bearer {API_TOKEN}' +``` + +Both return a list of file formats that users can convert into Markdown: + +```json +[ + { + "extension": ".pdf", + "mimeType": "application/pdf", + }, + { + "extension": ".jpeg", + "mimeType": "image/jpeg", + }, + ... +] +``` + +Learn more about our [Markdown Conversion utility](/workers-ai/features/markdown-conversion/). \ No newline at end of file