API konversi file

Konversikan file dari kode Anda sendiri dengan pengonversi yang sama seperti di situs web: kunci API, antarmuka REST sederhana, kredit, dan webhook.

Mulai cepat

Buat kunci di halaman akun Anda, lalu kirim file dan format yang Anda inginkan:

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"

Jawabannya menjelaskan konversi tersebut. Dengan wait=30, konversi yang cepat sudah selesai dalam jawaban yang sama; jika tidak, tanyakan statusnya nanti. Lalu unduh hasilnya:

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

Autentikasi

Kirim kunci Anda di header Authorization sebagai "Bearer ". Kunci dibuat dan dicabut di halaman akun Anda dan hanya ditampilkan sekali. Rahasiakan kunci: siapa pun yang memilikinya dapat memakai kredit Anda.

Endpoint

Masukan, opsi, dan format

Kirim file sebagai bidang multipart "file", atau tautan publik sebagai "url" (server kami yang mengunduhnya). Format sumber diambil dari nama file; jika tidak ada, kirim "source". Opsi seperti kualitas dapat dikirim sebagai bidang biasa (quality=85) atau sebagai options[quality]=85. GET /v1/formats/{source} menampilkan semua format tujuan beserta opsi dan batasnya.

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

Menunggu hasil

Konversi dijalankan dalam antrean. Tanyakan GET /v1/conversions/{id} sampai statusnya succeeded atau failed, tunggu hingga 30 detik langsung di permintaan dengan wait=30, atau kirim callback_url dan kami akan menghubungi Anda. Hasil dapat diunduh berulang kali selama 24 jam.

Kredit dan batasan

Konversi memerlukan kredit yang sama seperti di situs web: bobot jenis konversi dikali kelompok ukuran file, dan hanya jika berhasil. Paket berbayar memakai kredit bulanannya. Akun gratis mendapat 100 kredit API gratis setiap bulan.

Jawaban 429 menyertakan header Retry-After. Konversi juga dihitung dalam batas paket Anda untuk jumlah konversi per 10 menit, yang dipakai bersama dengan situs web.

Bandingkan paket

Webhook

Dengan callback_url (hanya https), kami mengirim POST berisi konversi dalam JSON saat selesai. Periksa header X-101convert-Signature: isinya t, waktu Unix, dan v1, HMAC-SHA256 dari "t.body" yang dibuat dengan rahasia webhook dari halaman akun Anda. Tolak stempel waktu lama untuk mencegah pengulangan. Pengiriman yang gagal dicoba lagi selama sekitar satu setengah jam.

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

Pengulangan yang aman

Kirim header Idempotency-Key dengan nilai unik milik Anda. Jika permintaan diulang, misalnya setelah waktu habis, Anda menerima konversi semula alih-alih konversi baru dan hanya membayar sekali.

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"

Kesalahan

Semua kesalahan memiliki bentuk yang sama. Putuskan berdasarkan code, yang tidak pernah berubah; message ditujukan untuk manusia dan mengikuti header Accept-Language.

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

Contoh

# 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