Baca dokumen

Lampirkan PDF atau gambar dokumen ke request chat biasa. kenari membaca dokumen menjadi teks sebelum request dirutekan, lalu memberi teks itu ke model yang kamu pilih. Model apa pun bisa dipakai, termasuk model yang tidak bisa melihat gambar sama sekali.

Dokumennya sendiri tidak pernah dikirim ke model. Yang model terima adalah teks hasil pembacaan.

Pembacaan dokumen bisa dipakai lewat dua jalur. Plugin file-parser di POST /v1/chat/completions kalau kamu mau model menjawab sesuatu tentang dokumennya. Endpoint POST /v1/ocr kalau kamu mau teksnya saja, tanpa giliran model dan tanpa biaya token di atas harga per halaman.

Cara pakai

Tambahkan dua hal ke POST /v1/chat/completions: satu content part bertipe file, dan plugin file-parser.

curl https://kenari.id/v1/chat/completions \
  -H "Authorization: Bearer $KENARI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "step-3-7-flash",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "Berapa total pada faktur ini?"},
        {"type": "file", "file": {
          "filename": "faktur.pdf",
          "file_data": "data:application/pdf;base64,JVBERi0xLjcK..."
        }}
      ]
    }],
    "plugins": [{"id": "file-parser", "pdf": {"engine": "ocr"}}]
  }'

file_data adalah data URL: data:<tipe>;base64,<isi>. URL http biasa tidak diambil, jadi unggah isinya sendiri.

Satu request membawa satu dokumen. Kirim dokumen kedua sebagai request terpisah.

Tipe yang diterima

application/pdf, image/png, image/jpeg, image/webp, image/gif, image/tiff. Tipe lain ditolak dengan status 400 sebelum ada biaya.

Plugin wajib

Content part file tanpa plugin file-parser ditolak 400. Ini disengaja: tanpa plugin, dokumen akan diteruskan ke model yang tidak bisa membacanya dan kamu tetap dibayar untuk jawaban yang mengarang.

engine saat ini hanya menerima ocr.

Jawaban

Selain jawaban model, response membawa teks hasil pembacaan di annotations.

{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "Totalnya Rp 417.000.",
      "annotations": [{
        "type": "file",
        "file": {
          "hash": "sha256:a3b6919a...",
          "name": "faktur.pdf",
          "content": [{"type": "text", "text": "# FAKTUR\n..."}],
          "confidence": 0.9892,
          "low_confidence": false,
          "reuse_id": "ocr_8f286cec-075b-4083-a462-fc89170feb4f"
        }
      }]
    }
  }]
}

Response streaming (stream: true) tidak membawa annotation ini. Pembacaan tetap berjalan dan tetap ditagih, tapi teks dan reuse_id hanya ada di response non-streaming.

low_confidence adalah peringatan, bukan jaminan

confidence adalah skor rata-rata per halaman dari mesin pembaca. low_confidence bernilai true kalau skornya di bawah ambang kenari, atau kalau mesin tidak melaporkan skor sama sekali.

Perlakukan ini sebagai peringatan saja. Pada pengukuran kami, dokumen yang terbaca benar dan yang terbaca salah punya rentang skor yang bertumpang tindih: satu struk yang isinya salah total masih mendapat skor di atas empat dokumen yang terbaca sempurna. Mesin pembaca cenderung mengarang nilai yang masuk akal daripada mengosongkannya, jadi angka yang dibaca dari dokumen pindaian tetap perlu diperiksa manusia, apa pun nilai low_confidence-nya.

Tanya lagi tanpa bayar lagi

Simpan reuse_id dari jawaban pertama, lalu kirimkan kembali di giliran berikutnya tanpa content part file:

{
  "model": "step-3-7-flash",
  "messages": [{"role": "user", "content": "Siapa nama penjualnya?"}],
  "plugins": [{"id": "file-parser", "pdf": {"engine": "ocr", "reuse_id": "ocr_8f286cec-..."}}]
}

Giliran ini tidak membaca ulang dokumen dan tidak menambah biaya halaman. reuse_id hanya berlaku untuk akun yang menerimanya.

Mengirim ulang dokumen yang sama persis juga tidak ditagih dua kali, jadi kamu bisa mengulang request yang gagal tanpa membayar lagi.

Membaca dokumen lewat endpoint /v1/ocr

Endpoint POST /v1/ocr mengembalikan teks hasil pembacaan saja, tanpa model. Harga per halaman sama dengan jalur plugin, dan tidak ada biaya token.

curl https://kenari.id/v1/ocr \
  -H "Authorization: Bearer $KENARI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file": {
      "filename": "faktur.pdf",
      "file_data": "data:application/pdf;base64,JVBERi0xLjcK..."
    }
  }'

Request membawa file atau reuse_id, tidak keduanya. file berisi filename dan file_data. file_data adalah data URL (data:<tipe>;base64,<isi>) dan hanya base64: URL http biasa tidak diambil, jadi unggah isinya sendiri. Tipe yang diterima sama dengan plugin: application/pdf, image/png, image/jpeg, image/webp, image/gif, image/tiff. engine opsional, dan saat ini hanya ocr yang diterima.

Response:

{
  "id": "req_8f286cec-075b-4083",
  "pages": 3,
  "cost_micro_idr": 900000,
  "name": "faktur.pdf",
  "hash": "sha256:a3b6919a...",
  "content": [{"type": "text", "text": "# FAKTUR\n..."}],
  "confidence": 0.9892,
  "low_confidence": false,
  "reuse_id": "ocr_8f286cec-075b-4083-a462-fc89170feb4f"
}

content adalah teks hasil pembacaan. pages adalah halaman yang benar-benar dibaca dan menjadi dasar biaya. cost_micro_idr adalah biaya dalam mikro-Rupiah (Rupiah dikali 1.000.000), bernilai nol kalau request hanya memakai reuse_id. confidence dan low_confidence punya arti yang sama seperti pada response plugin.

Dua batas berlaku, dan yang mana pun bisa menolak lebih dulu. Batas halaman diatur oleh kenari dan saat ini 100 halaman. Batas ukuran dokumen sekitar 15 MB. Dokumen yang melewati salah satu batas itu ditolak, tidak ditagih, dan tidak dibaca.

reuse_id bekerja di kedua jalur

reuse_id bisa dipakai di kedua arah. Yang dikeluarkan plugin pada giliran chat bisa diputar ulang di endpoint ini, dan yang dikeluarkan endpoint bisa dipakai pada giliran chat. Keduanya menyajikan hasil pembacaan yang sama tanpa biaya halaman tambahan. reuse_id hanya berlaku untuk akun yang menerimanya.

Kunci yang dibagikan hanya bisa memakai bacaannya sendiri

Kunci yang kamu bagikan ke orang lain hanya bisa memakai ulang pembacaan yang dibuat oleh kunci itu sendiri. Kunci lain yang kamu miliki dan bukan share tetap bisa memakai ulang pembacaan apa pun di akunmu. Kalau kunci share mencoba menebus reuse_id buatan kunci lain, request ditolak dengan status 400, dokumen tidak dibaca, dan pemegang kunci harus mengunggah dokumennya sendiri dan membayar.

Ini disengaja. Share adalah pemberian yang terbatas, dan reuse_id ikut terbawa kalau log chat diekspor. Kalau kunci share bisa menebus reuse_id buatan kunci lain, pemegangnya mendapat isi dokumen yang tidak pernah diunggahnya dan tidak membayar apa pun.

Biaya

Ditagih per halaman yang dibaca, dipotong dari saldo Rupiah yang sama dengan pemakaian token. Harga per halaman ada di dashboard.

Halaman dihitung dari yang benar-benar dibaca mesin, bukan dari ukuran berkas. Gambar dihitung satu halaman.

Biaya pembacaan terpisah dari biaya token model: satu request membuat dua baris di Pemakaian, satu untuk pembacaan dan satu untuk jawaban model.

Ada batas jumlah halaman per dokumen, diatur oleh kenari dan saat ini 100 halaman. Ada juga batas ukuran dokumen sekitar 15 MB. Batas-batas ini berdiri sendiri: salah satu yang terlampaui menolak dokumen tanpa biaya.

Kunci API yang dibatasi modelnya

Kunci API yang dibatasi ke model tertentu tidak bisa memakai pembacaan dokumen sampai kamu memberinya izin. Waktu membuat kunci atau share, centang Pembacaan dokumen di daftar kemampuan. Ini berlaku juga untuk kunci yang kamu bagikan ke orang lain.

Alasannya, pembacaan dokumen adalah biaya tersendiri di luar biaya model. Kunci yang kamu batasi ke beberapa model saja tidak otomatis boleh mengeluarkan biaya per halaman, karena itu bukan bagian dari yang kamu izinkan waktu membuat kunci.

Kunci tanpa batas model tidak terpengaruh dan bisa langsung memakai pembacaan dokumen. Daftar kemampuan hanya muncul kalau kunci itu dibatasi modelnya.

Kunci lama yang memuat ocr di daftar modelnya tetap jalan tanpa perlu diubah.

Kunci yang ditolak menerima galat 400, baik lewat plugin maupun endpoint, tidak ditagih apa pun, dan dokumennya tidak dibaca. Aturan yang sama berlaku untuk reuse_id: kunci yang tidak diizinkan tidak bisa memakai hasil pembacaan lama, walaupun pemakaian ulang itu gratis.