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

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.

Una risposta 429 contiene l'intestazione Retry-After. Le conversioni contano anche per il limite del tuo piano di conversioni ogni 10 minuti, 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 }
  }
}

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