API do konwersji plików

Konwertuj pliki z własnego kodu tymi samymi konwerterami co na stronie: klucz API, prosty interfejs REST, kredyty i webhooki.

Szybki start

Utwórz klucz na stronie konta, a potem wyślij plik i wybrany format:

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"

Odpowiedź opisuje konwersję. Z wait=30 szybka konwersja jest gotowa już w tej samej odpowiedzi; w przeciwnym razie sprawdź jej status później. Następnie pobierz wynik:

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

Uwierzytelnianie

Wysyłaj klucz w nagłówku Authorization jako "Bearer ". Klucze tworzy się i unieważnia na stronie konta i są pokazywane tylko raz. Trzymaj je w tajemnicy: każdy, kto ma Twój klucz, może zużywać Twoje kredyty.

Endpointy

Wejście, opcje i formaty

Wyślij plik jako pole multipart "file" albo publiczny link jako "url" (pobiorą go nasze serwery). Format źródłowy jest odczytywany z nazwy pliku; jeśli jej brak, wyślij "source". Opcje takie jak jakość można wysłać jako zwykłe pola (quality=85) lub jako options[quality]=85. GET /v1/formats/{source} wyświetla wszystkie formaty docelowe z opcjami i limitami.

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

Czekanie na wynik

Konwersje są przetwarzane w kolejce. Pytaj GET /v1/conversions/{id}, aż status będzie succeeded lub failed, poczekaj do 30 sekund bezpośrednio w żądaniu z wait=30 albo wyślij callback_url, a my damy znać. Wynik można pobierać wielokrotnie przez 24 godzin.

Kredyty i limity

Konwersja kosztuje tyle samo kredytów co na stronie: waga typu konwersji razy przedział rozmiaru pliku, i tylko gdy się powiedzie. Płatne plany zużywają swoje miesięczne kredyty. Darmowe konto dostaje co miesiąc 100 darmowych kredytów API.

Odpowiedź 429 zawiera nagłówek Retry-After. Konwersje liczą się też do limitu Twojego planu na liczbę konwersji w ciągu 10 minut, wspólnego ze stroną.

Porównaj plany

Webhooki

Z callback_url (tylko https) po zakończeniu wyślemy POST z konwersją w formacie JSON. Sprawdź nagłówek X-101convert-Signature: zawiera t, czas uniksowy, oraz v1, HMAC-SHA256 z "t.body" utworzony sekretem webhooków ze strony konta. Odrzucaj stare znaczniki czasu, aby zapobiec powtórkom. Nieudane dostarczenia ponawiamy przez około półtorej godziny.

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

Bezpieczne ponawianie

Wyślij nagłówek Idempotency-Key z własną unikalną wartością. Jeśli żądanie zostanie powtórzone, na przykład po przekroczeniu czasu, dostaniesz pierwotną konwersję zamiast nowej i zapłacisz tylko raz.

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"

Błędy

Wszystkie błędy mają ten sam kształt. Decyduj na podstawie code, który nigdy się nie zmienia; message jest dla ludzi i stosuje się do nagłówka Accept-Language.

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

Przykłady

# 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