Vai al contenuto

API di conversione file

Converti file dal tuo codice con gli stessi convertitori del sito: una chiave API, una semplice interfaccia REST, crediti e webhook.

Avvio rapido

Crea una chiave nella pagina del tuo account, poi invia un file e il formato desiderato:

curl -X POST https://api.101convert.com/v1/conversions \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@photo.jpg" \
  -F "target=webp" \
  -F "quality=85" \
  -F "wait=30"

La risposta descrive la conversione. Con wait=30 una conversione rapida è già pronta nella stessa risposta; altrimenti chiedi lo stato più tardi. Poi scarica il risultato:

{
  "id": "cnv_01j9z3k8q4x7m2n5p6r8s9t0v1",
  "status": "succeeded",
  "source": "jpg",
  "target": "webp",
  "credits": 2,
  "result": {
    "filename": "photo.webp",
    "size": 48213,
    "download_url": "https://api.101convert.com/v1/conversions/cnv_01j9z3k8q4x7m2n5p6r8s9t0v1/download",
    "expires_at": "…"
  }
}

curl -o photo.webp -H "Authorization: Bearer $API_KEY" \
  https://api.101convert.com/v1/conversions/cnv_01j9z3k8q4x7m2n5p6r8s9t0v1/download

Autenticazione

Invia la chiave nell'intestazione Authorization come "Bearer ". Le chiavi si creano e si revocano nella pagina del tuo account e vengono mostrate una sola volta. Tienile segrete: chiunque abbia la tua chiave può usare i tuoi crediti.

Endpoint

Metodo Percorso Descrizione
POST /v1/conversions Avvia una conversione da un file o da un URL (anche POST /v1/convert)
GET /v1/conversions/{id} Stato di una conversione, con il risultato quando è terminata
GET /v1/conversions/{id}/download Scarica il risultato tutte le volte che serve fino alla scadenza
DELETE /v1/conversions/{id} Annulla una conversione ancora in attesa o elimina un risultato in anticipo
GET /v1/conversions Le tue conversioni, dalla più recente
GET /v1/formats Tutte le conversioni supportate
GET /v1/formats/{source} Formati di destinazione di un formato di origine con opzioni, varianti, limiti di dimensione e prezzi
GET /v1/account Il tuo piano, i crediti rimasti e i limiti

Input, opzioni e formati

Invia il file come campo multipart "file", oppure un link pubblico come "url" (lo scaricano i nostri server). Il formato di origine si ricava dal nome del file; se non ce l'ha, invia "source". Le opzioni come la qualità si possono inviare come campi semplici (quality=85) o come options[quality]=85. GET /v1/formats/{source} elenca tutti i formati di destinazione con opzioni e limiti.

curl -X POST https://api.101convert.com/v1/conversions \
  -H "Authorization: Bearer $API_KEY" \
  -d "url=https://example.com/report.docx" \
  -d "target=pdf"

curl -H "Authorization: Bearer $API_KEY" https://api.101convert.com/v1/formats/jpg

Attendere il risultato

Le conversioni vengono elaborate in coda. Interroga GET /v1/conversions/{id} finché lo stato non è succeeded o failed, attendi fino a 30 secondi nella richiesta stessa con wait=30, oppure invia una callback_url e ti avviseremo noi. Un risultato si può scaricare più volte per 24 ore.

Crediti e limiti

Una conversione costa gli stessi crediti del sito: il peso del tipo di conversione per la fascia di dimensione del file, e solo se riesce. I piani a pagamento usano i loro crediti mensili. Un account gratuito riceve ogni mese 100 crediti API gratuiti.

Piano Crediti al mese Conversioni contemporanee Richieste al minuto
Free 100 crediti API gratuiti 2 30
Lite 1,000 5 120
Standard 2,500 10 300
Pro 5,000 20 600

Una risposta 429 contiene l'intestazione Retry-After. Le conversioni contano anche per il limite di conversioni del tuo piano, condiviso con il sito.

Confronta i piani

Webhook

Con una callback_url (solo https) ti inviamo un POST con la conversione in JSON quando termina. Verifica l'intestazione X-101convert-Signature: contiene t, un orario Unix, e v1, l'HMAC-SHA256 di "t.body" calcolato con il segreto dei webhook della pagina del tuo account. Rifiuta i timestamp vecchi per evitare replay. Le consegne non riuscite vengono ritentate per circa un'ora e mezza.

// PHP
[$t, $v1] = array_map(fn ($p) => explode('=', $p, 2)[1],
    explode(',', $_SERVER['HTTP_X_101CONVERT_SIGNATURE']));
$body  = file_get_contents('php://input');
$valid = abs(time() - (int) $t) < 300
    && hash_equals(hash_hmac('sha256', "$t.$body", $webhookSecret), $v1);

// Node.js
const [t, v1] = req.headers['x-101convert-signature'].split(',').map(p => p.split('=')[1]);
const expected = crypto.createHmac('sha256', webhookSecret).update(`${t}.${rawBody}`).digest('hex');
const valid = Math.abs(Date.now() / 1000 - t) < 300
    && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));

Tentativi ripetuti sicuri

Invia un'intestazione Idempotency-Key con un tuo valore univoco. Se la richiesta viene ripetuta, ad esempio dopo un timeout, ricevi la conversione originale invece di una nuova e paghi una sola volta.

curl -X POST https://api.101convert.com/v1/conversions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: invoice-2026-0042" \
  -F "file=@invoice.docx" -F "target=pdf"

Errori

Tutti gli errori hanno la stessa forma. Decidi in base a code, che non cambia mai; message è per le persone e segue l'intestazione Accept-Language.

{
  "error": {
    "code": "file_too_large",
    "message": "…",
    "details": { "max_upload_mb": 60 }
  }
}
Codice HTTP Significato
unauthenticated 401 Chiave API mancante o non valida. Inviala come "Authorization: Bearer <chiave>".
forbidden 403 Questa chiave API non ha il permesso di farlo.
validation_failed 422 Alcuni parametri della richiesta mancano o non sono validi.
unsupported_conversion 422 La conversione da A a B non è supportata.
file_too_large 413 File troppo grande. Massimo N MB.
insufficient_credits 402 Crediti insufficienti: questa conversione costa N, il tuo saldo è N.
free_quota_exhausted 402 Il credito mensile gratuito dell'API è esaurito (restano N crediti su N, questa conversione costa N). Passa a un piano a pagamento per continuare.
rate_limited 429 Troppe richieste. Attendi il tempo indicato nell'intestazione Retry-After e riprova.
concurrency_limit 429 Troppe conversioni in corso (il tuo piano ne consente N alla volta). Attendi che alcune finiscano.
idempotency_conflict 409 Questa Idempotency-Key è già stata usata per un'altra richiesta.
not_ready 409 La conversione non si è conclusa correttamente, quindi non c'è nulla da scaricare.
expired 410 Il risultato è scaduto ed è stato eliminato. Converti di nuovo il file.
api_disabled 503 L'API non è temporaneamente disponibile. Riprova più tardi.

Esempi

# Python
import requests, time

API = "https://api.101convert.com/v1"
headers = {"Authorization": f"Bearer {API_KEY}"}

with open("interview.mp3", "rb") as f:
    c = requests.post(f"{API}/conversions", headers=headers,
                      files={"file": f}, data={"target": "docx"}).json()

while c["status"] not in ("succeeded", "failed"):
    time.sleep(5)
    c = requests.get(c["links"]["self"], headers=headers).json()

if c["status"] == "succeeded":
    open("interview.docx", "wb").write(
        requests.get(c["result"]["download_url"], headers=headers).content)
// PHP (Laravel)
$c = Http::withToken($apiKey)
    ->attach('file', fopen('slides.pptx', 'r'), 'slides.pptx')
    ->post('https://api.101convert.com/v1/conversions', ['target' => 'pdf', 'wait' => 30])
    ->json();

if ($c['status'] === 'succeeded') {
    file_put_contents('slides.pdf', Http::withToken($apiKey)->get($c['result']['download_url'])->body());
}
// JavaScript (Node 18+)
const form = new FormData();
form.append('file', new Blob([await fs.promises.readFile('scan.png')]), 'scan.png');
form.append('target', 'pdf');
form.append('callback_url', 'https://example.com/hooks/101convert');

const res = await fetch('https://api.101convert.com/v1/conversions', {
  method: 'POST',
  headers: { Authorization: `Bearer ${apiKey}` },
  body: form,
});
const conversion = await res.json(); // status "queued"; the webhook follows

Già scaricato

Questo file è già stato scaricato. Per tutelare la tua privacy lo abbiamo eliminato dal nostro server subito dopo il download, quindi non può essere scaricato di nuovo. Se ti serve ancora, converti di nuovo il file.