API pro převod souborů

Převádějte soubory z vlastního kódu stejnými převodníky jako na webu: API klíč, jednoduché REST rozhraní, kredity a webhooky.

Rychlý start

Vytvořte si klíč na stránce účtu a pak pošlete soubor a požadovaný formát:

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"

Odpověď popisuje převod. S wait=30 je rychlý převod hotový už ve stejné odpovědi, jinak se na stav zeptejte později. Potom si výsledek stáhněte:

{
  "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

Ověření

Klíč posílejte v hlavičce Authorization jako "Bearer ". Klíče se vytvářejí a ruší na stránce účtu a zobrazí se jen jednou. Uchovávejte je v tajnosti: kdokoli s vaším klíčem může čerpat vaše kredity.

Endpointy

Vstup, volby a formáty

Pošlete soubor jako multipart pole "file", nebo veřejný odkaz jako "url" (stáhnou ho naše servery). Zdrojový formát se bere z názvu souboru; pokud ho nemá, pošlete "source". Volby jako kvalitu můžete poslat jako běžná pole (quality=85) nebo jako options[quality]=85. GET /v1/formats/{source} vypíše všechny cílové formáty s volbami a limity.

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

Čekání na výsledek

Převody běží ve frontě. Ptejte se GET /v1/conversions/{id}, dokud stav není succeeded nebo failed, počkejte až 30 sekund přímo v požadavku pomocí wait=30, nebo pošlete callback_url a my se ozveme. Výsledek lze opakovaně stahovat 24 hodin.

Kredity a limity

Převod stojí stejně kreditů jako na webu: váha typu převodu krát pásmo velikosti souboru, a jen když se povede. Placené plány čerpají své měsíční kredity. Bezplatný účet dostává každý měsíc 100 bezplatných API kreditů.

Odpověď 429 obsahuje hlavičku Retry-After. Převody se také počítají do limitu vašeho plánu na počet převodů za 10 minut, který je společný s webem.

Porovnat plány

Webhooky

S callback_url (jen https) vám po dokončení pošleme POST s převodem ve formátu JSON. Ověřte hlavičku X-101convert-Signature: obsahuje t, unixový čas, a v1, HMAC-SHA256 z "t.body" vytvořený tajným klíčem webhooků ze stránky účtu. Staré časové značky odmítejte, abyste zabránili opakovanému přehrání. Nedoručené zprávy zkoušíme znovu zhruba hodinu a půl.

// 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));

Bezpečné opakování

Pošlete hlavičku Idempotency-Key s vlastní jedinečnou hodnotou. Když se požadavek zopakuje, třeba po vypršení spojení, dostanete zpět původní převod místo nového a zaplatíte jen jednou.

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"

Chyby

Všechny chyby mají stejný tvar. Rozhodujte se podle code, který se nikdy nemění; message je pro lidi a řídí se hlavičkou Accept-Language.

{
  "error": {
    "code": "file_too_large",
    "message": "…",
    "details": { "max_upload_mb": 60 }
  }
}

Příklady

# 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