---
title: "API di conversione documenti"
description: "L'API di conversione documenti è un'API HTTPS che accetta un file, un URL o HTML in una sola chiamata POST /v1/convert/{name} e restituisce Markdown."
url: https://markitdown.ai/developers
updated: 2026-09-26
source: markitdown.ai
---

# API di conversione documenti

> L'API di conversione documenti è un'API HTTPS che accetta un file, un URL o HTML in una sola chiamata POST /v1/convert/{name} e restituisce Markdown.

La prova anonima accetta file fino a 10 MB e 25 pagine, con 3 conversioni per IP all'ora e 10 al giorno. Lite parte da $20 al mese con file fino a 100 MB. Pro costa $50 al mese; Max costa $100 al mese.

- Una chiamata POST /v1/convert/{name} per file, URL o testo in linea
- Markdown nella risposta entro 60 secondi, oppure una conversione da monitorare
- Lo stesso motore di conversione dell'app web

## Come funziona l'API di conversione documenti

Tre passaggi dalla chiave al Markdown. Ogni chiamata attende fino a 60 secondi e risponde con il risultato; le richieste più lunghe o con più file restituiscono 202 e una conversione da monitorare invece di tenere aperta la connessione.

**Richiesta**

```bash
# Upload a local file; Markdown comes back in the same response
curl -X POST https://api.markitdown.ai/v1/convert/pdf \
  -H "x-api-key: mdai_…" \
  -F file=@nist-cswp-29-csf-2.0.pdf

# Or convert a public web page
curl -X POST https://api.markitdown.ai/v1/convert/url \
  -H "x-api-key: mdai_…" \
  -H "content-type: application/json" \
  -d '{"url":"https://markitdown.ai/blog/why-pdfs-break-llms"}'

# Took longer than the wait window? Long-poll the conversion
curl "https://api.markitdown.ai/v1/conversions/<id>?wait=100" \
  -H "x-api-key: mdai_…"
```

1. Crea una chiave API — Crea una chiave in Impostazioni → Sviluppatori (serve un abbonamento attivo) e inviala nell'header x-api-key.
2. POST /v1/convert/{name} — Invia un file, un URL pubblico o testo in linea all'endpoint di quel formato. Un tipo di input per chiamata.
3. Usa il Markdown — Leggi l'output dalla risposta, oppure attendi su /v1/conversions/{id} dopo un 202.

## Risposta e webhook

La risposta qui sotto illustra il contratto dell'API usando l'output verificato di un parser DOCX; l'ID della conversione è un segnaposto. Una conversione conclusa restituisce il Markdown con i crediti che è costata. Un 202 porta un header Location verso la conversione; monitorala con ?wait=, trasmetti i suoi eventi oppure lascia che un webhook ti avvisi quando si conclude.

**La risposta, oppure un webhook conversion.completed**

```text
{
  "id": "cnv_3f7c…",
  "object": "conversion",
  "name": "word",
  "status": "completed",
  "files": [ { "outputs": [ { "format": "markdown", "content": "## Review Findings\n\nRisk ratings follow the standard High / Medium / Low scale defined in the vendor risk management policy.\n\n| Vendor | Risk Rating | Finding | Owner |\n| --- | --- | --- | --- |\n| CloudScan OCR | Medium | No documented data retention limit on uploaded scans | Security |\n| PayBridge | Low | SOC 2 Type II renewed; no open items | Finance |\n| LingoTrans API | High | Sub-processor list not disclosed on request | Legal |\n| ArchiveNow Storage | Medium | Encryption at rest confirmed; key rotation overdue | Security |\n" } ] } ],
  "usage": { "credits_charged": 1 }
}

POST https://your-app.example.com/webhooks
{
  "type": "conversion.completed",
  "data": { "id": "cnv_3f7c…", "object": "conversion", "status": "completed" }
}
```

Iscriviti a `conversion.completed` e `conversion.failed` per reagire nel momento in cui una conversione lunga o con più file si conclude, invece di fare polling. Le consegne sono firmate con gli header di Standard Webhooks.

## API di parsing documenti e API di conversione Markdown

I team cercano un'API di parsing documenti quando devono estrarre struttura dai file, e un'API di conversione Markdown quando l'output deve finire in un prompt o in un archivio. Entrambe le espressioni descrivono questo servizio. Le pagine specifiche per formato, come l'[API PDF to Markdown](/pdf-to-markdown) e l'[API URL to Markdown](/url-to-markdown), sono ancore a quei convertitori: usano gli stessi endpoint `/v1/convert/{name}`.

- Endpoint di conversione — POST /v1/convert/{name} — un endpoint per formato — accetta un file, un URL o testo e restituisce Markdown, testo, HTML o output per pagina.
- Chiavi API — Chiavi per account inviate con l'header x-api-key, così la conversione si adatta a qualsiasi server o script.
- Più file e webhook — Invia molti file a una sola chiamata di conversione e ricevi una sola conversione; i webhook segnalano ogni conversion.completed o conversion.failed.
- Markdown Render — POST /v1/convert/markdown/html o /markdown/text riconverte il Markdown in HTML o testo semplice senza costi in crediti.

## Dove lo integrano i team

- Ingestione per RAG — Converti i documenti dentro i job di ingestione prima di suddividerli ed embarli.
- Agenti IA — Lascia che gli agenti trasformino file arbitrari in testo pulito a metà pipeline.
- Pipeline di contenuti — Porta il Markdown in un CMS, in un sito di documentazione o in una knowledge base in modo automatico.
- Strumenti interni — Aggiungi la conversione documenti ai prodotti e agli strumenti interni che già usi.

## Autenticazione, uso e limiti

- Le chiavi API appartengono al tuo account, funzionano solo su /v1 e si inviano con l'header x-api-key; l'account deve avere un abbonamento Lite, Pro o Max attivo
- L'uso consuma gli stessi crediti dell'app web: le pagine standard e OCR costano 1 credito per pagina
- I limiti di richieste per piano sono Lite 20, Pro 40 e Max 60 richieste al minuto
- Idempotency-Key su ogni chiamata POST /v1/convert/{name}, così un nuovo tentativo non addebita mai due volte
- Ogni endpoint v1, campo della richiesta e risposta è documentato nella [referenza API](/docs/api) generata; gli errori usano problem+json con una URI `type` che risolve alla [pagina del codice di errore](/docs/errors) corrispondente

## Gestire il completamento

Gestisci sia il completamento in linea sia l'elaborazione asincrona in un client dell'API di conversione documenti. Un invio riuscito può restituire un risultato già completato, mentre l'HTTP 202 indica che il lavoro continua dopo la risposta. Conserva l'identificatore della conversione e usa l'endpoint documentato di Location o di stato della conversione prima di leggere gli output. Non indicizzare direttamente in un presunto primo output solo perché la richiesta HTTP è andata a buon fine. Una conversione completata può contenere anche errori a livello di file, quindi ispeziona ogni file in una richiesta con più origini. Salva contesto sufficiente per collegare ogni risultato restituito all'origine inviata dalla tua applicazione. Così eviti che una conversione lenta o un errore parziale diventino in silenzio un documento vuoto nel tuo sistema a valle.

## Limiti di richiesta e limiti del piano

L'API di conversione documenti applica limiti sia alle richieste sia agli account. Una richiesta multipart può includere fino a 100 file con un limite complessivo di 100 MB. Una richiesta per URL accetta fino a 20 origini. Il tuo abbonamento controlla separatamente crediti, archiviazione, limiti per file e concorrenza. Un file consentito da un piano Pro può esserlo per il suo abbonamento e allo stesso tempo essere troppo grande per una singola richiesta multipart; in quel caso usa il flusso documentato di upload a blocchi. Non aggirare una richiesta rifiutata dando per scontato che il piano più alto elimini i limiti di trasporto. Leggi l'errore e usa il metodo di input previsto per la dimensione dell'origine.

## Conservare il contesto dell'origine

Tieni il tuo identificatore di origine accanto all'identificatore della conversione, così un risultato può essere ricondotto al job che lo ha inviato. Il campo metadata dell'API trasporta dati forniti da chi chiama; non è una promessa di estrarre titoli di pagina, autori o date di pubblicazione. Se la tua applicazione ha bisogno di quei dati, raccoglili e verificali in un passaggio separato adeguato. Prima di leggerne il testo, controlla se un output viene restituito in linea o tramite un artefatto referenziato, e conserva il documento originale quando il tuo flusso richiede una traccia di audit. Un'API di conversione documenti prepara il contenuto per la fase successiva, mentre la tua applicazione resta responsabile di associare quel contenuto alla sua origine e di decidere per quanto tempo conservarlo.

## Prova prima del rilascio

Prova più di un piccolo file corretto prima di integrare l'API di conversione documenti in un flusso di produzione. Includi un input che richiede completamento asincrono, un file non supportato o danneggiato, una richiesta con più origini e risultati misti, e una risposta che il tuo client deve trattare come errore di limite. Verifica che la tua logica di ritentativo non invii di nuovo file corretti dopo un errore parziale. Conserva le credenziali API sul tuo server ed evita di metterle nel codice del browser o in esempi pubblici. Esamina il Markdown reale dei tipi di origine rappresentativi prima di valutare il retrieval o il comportamento del modello a valle. Un client che gestisce bene gli errori di trasporto ha comunque bisogno di controlli a livello di contenuto per dimostrare che i documenti risultanti sono utili.

## FAQ

### Come mi autentico nell'API di conversione documenti?

Crea una chiave API nel tuo account e inviala nell'header `x-api-key`. Le chiavi sono limitate al tuo account.

### Qual è il flusso reale di conversione?

POST /v1/convert/{name} con un file, un URL pubblico o testo. Il Markdown torna nella stessa risposta quando il documento finisce entro la finestra di attesa; altrimenti ricevi 202 e una conversione su cui attendere con GET /v1/conversions/{id}?wait=.

### La conversione è sincrona?

Per impostazione predefinita, fino alla finestra di attesa: POST /v1/convert/{name} attende un risultato e lo restituisce in linea, oppure restituisce 202 con una Location quando la conversione non riesce a finire in tempo. Invia Prefer: respond-async per saltare l'attesa.

### A quali eventi posso iscrivermi?

I webhook in uscita supportano conversion.completed e conversion.failed, così reagisci non appena una conversione si conclude invece di fare polling.

### Quali piani includono l'accesso API?

L'accesso API è disponibile nei piani a pagamento. Consulta la pagina dei prezzi per i limiti e i crediti attuali di ogni piano.

### Come viene fatturato l'uso dell'API?

Le conversioni via API attingono allo stesso saldo crediti dell'app web. Le pagine standard e quelle OCR costano 1 credito per pagina.

### Dove trovo un'API PDF to Markdown o un'API URL to Markdown?

Quelle espressioni sono pagine di formato, non host aggiuntivi. Usa le note dell'API PDF to Markdown su /pdf-to-markdown e quelle dell'API URL to Markdown su /url-to-markdown, poi chiama gli stessi endpoint di upload e conversione documentati qui.

### Quali sono i limiti di richieste delle chiavi API?

Le richieste sono limitate per account: Lite 20, Pro 40 e Max 60 richieste al minuto.

## Related

- [Introduction](https://markitdown.ai/docs)
- [PDF to Markdown Converter](https://markitdown.ai/pdf-to-markdown)
- [markitdown.ai pricing for document conversion](https://markitdown.ai/pricing)