API បកប្រែឯកសារ

API បកប្រែឯកសាររបស់ InKhmer បកប្រែឯកសារ PDF រវាងខ្មែរ និងអង់គ្លេស (និងគូភាសាផ្សេងទៀតដែលគាំទ្រ) ដោយម៉ាស៊ីនដដែលដែលដំណើរការឧបករណ៍បកប្រែលើគេហទំព័រ inkhmer.com។ វាជាប្រព័ន្ធបង់ប្រាក់ជាមុន៖ ការងារនីមួយៗកាត់ក្រេឌីតពីកាបូប InKhmer របស់អ្នកនៅពេលបង្កើតការងារ ហើយក្រេឌីតដែលមិនបានប្រើត្រូវបានសងវិញដោយស្វ័យប្រវត្តិ ប្រសិនបើការងារបរាជ័យ ឬត្រូវបានបោះបង់មុនពេលបញ្ចប់។

• PDF ចូល PDF ចេញ — ទំព័រ និងពុម្ពអក្សរត្រូវបានរក្សាទុក; ទំព័រស្កេនឆ្លងកាត់ OCR។
• យល់ភាសាខ្មែរ — បណ្តុះបណ្តាល និងវាយតម្លៃលើឯកសារសិក្សា និងឯកសាររដ្ឋាភិបាលខ្មែរជាចម្បង។
• ធ្វើការងារបែប asynchronous — បង្កើតការងារ តាមដានស្ថានភាព រួចទាញយកលទ្ធផល។ ការងារធម្មតាបញ្ចប់ក្នុងរយៈពេលពីរបីវិនាទីក្នុងមួយទំព័រ។
• បង់ប្រាក់ជាមុន — គ្មានការជាវរៀបរាប់; អ្នកបង់តែទំព័រដែលបានបកប្រែពិតប្រាកដប៉ុណ្ណោះ។

Base URL: https://api.inkhmer.com/v1/public/document-translator

បង្កើតការងារដោយ multipart POST មួយ តាមដានរហូតស្ថានភាពឈានដល់ done រួចទាញយក PDF។ ជំនួស sk_test_… ដោយកូនសោរបស់អ្នក និង contract.pdf ដោយឯកសាររបស់អ្នក។

# Create a job
curl -X POST https://api.inkhmer.com/v1/public/document-translator/jobs \
  -H "Authorization: Bearer $INKHMER_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "file=@contract.pdf" \
  -F "source=auto" \
  -F "target=km"
# → 202 { "jobId": "019a…", "pagesTotal": 72, "tier": "t4",
#         "priceCredits": 999, "walletAfter": 1301,
#         "pollUrl": "/v1/public/document-translator/jobs/019a…" }

# Poll until done / error / cancelled (~every 2 s)
JOB_ID=019a…   # from the 202 response
while :; do
  STATE=$(curl -s https://api.inkhmer.com/v1/public/document-translator/jobs/$JOB_ID \
    -H "Authorization: Bearer $INKHMER_KEY" | jq -r .state)
  echo "$STATE"
  [ "$STATE" = done ] && break
  [ "$STATE" = error ] && exit 1
  [ "$STATE" = cancelled ] && exit 1
  sleep 2
done

# Download the watermark-free PDF
curl -o translation.pdf https://api.inkhmer.com/v1/public/document-translator/jobs/$JOB_ID/pdf \
  -H "Authorization: Bearer $INKHMER_KEY"

// Requires Node 18+ (global fetch / FormData / Blob).
import { randomUUID } from 'node:crypto';
import fs from 'node:fs';

const BASE = 'https://api.inkhmer.com/v1/public/document-translator';
const ORIGIN = 'https://api.inkhmer.com';
const KEY = process.env.INKHMER_KEY; // sk_test_… / sk_live_…
const headers = { Authorization: `Bearer ${KEY}` };

// 1. Create the job (multipart upload)
const form = new FormData();
form.append('file', new Blob([fs.readFileSync('contract.pdf')]), 'contract.pdf');
form.append('source', 'auto');
form.append('target', 'km');

const created = await fetch(`${BASE}/jobs`, {
  method: 'POST',
  headers: { ...headers, 'Idempotency-Key': randomUUID() },
  body: form,
}).then((r) => r.json());

// 2. Poll the job (~every 2 s) until a terminal state.
//    created.pollUrl is the relative /v1/… path from the 202 response.
while (true) {
  const job = await fetch(`${ORIGIN}${created.pollUrl}`, { headers })
    .then((r) => r.json());
  if (job.state === 'done') break;
  if (job.state === 'error' || job.state === 'cancelled')
    throw new Error(`job ${job.state}: ${job.error}`);
  await new Promise((r) => setTimeout(r, 2000));
}

// 3. Download the watermark-free PDF
const pdf = await fetch(`${BASE}/jobs/${created.jobId}/pdf`, { headers });
fs.writeFileSync('translation.pdf', Buffer.from(await pdf.arrayBuffer()));

import os, time, uuid
import requests

BASE = 'https://api.inkhmer.com/v1/public/document-translator'
KEY = os.environ['INKHMER_KEY']  # sk_test_… / sk_live_…
HEADERS = {'Authorization': f'Bearer {KEY}'}

# 1. Create the job (multipart upload)
with open('contract.pdf', 'rb') as f:
    created = requests.post(
        f'{BASE}/jobs',
        headers={**HEADERS, 'Idempotency-Key': str(uuid.uuid4())},
        files={'file': ('contract.pdf', f, 'application/pdf')},
        data={'source': 'auto', 'target': 'km'},
    ).json()

# 2. Poll the job (~every 2 s) until a terminal state
while True:
    job = requests.get(
        f"{BASE}/jobs/{created['jobId']}", headers=HEADERS
    ).json()
    if job['state'] == 'done':
        break
    if job['state'] in ('error', 'cancelled'):
        raise RuntimeError(f"job {job['state']}: {job['error']}")
    time.sleep(2)

# 3. Download the watermark-free PDF
pdf = requests.get(
    f"{BASE}/jobs/{created['jobId']}/pdf", headers=HEADERS
)
with open('translation.pdf', 'wb') as f:
    f.write(pdf.content)

ការងារដែលមានទំហំលើស ~20 MiB គួរប្រើលំហូរ direct-to-storage ជំនួស៖ POST /jobs/intent ដើម្បីយក URL ផ្ទុកឡើង presigned បញ្ជូន bytes ដោយ PUT រួច POST /jobs/{jobId}/finalize។ មើលផ្នែកឯកសារយោងសម្រាប់លំហូរទាំងពីរ។

ការងារត្រូវបូកជាក្រេឌីតកាបូបតាមក្រុមទំព័រ — ក្រុមតម្លៃដដែលនឹងឧបករណ៍លើ inkhmer.com។ ១ ក្រេឌីត = $០.០១ USD។ តម្លៃត្រូវបានបញ្ជាក់នៅពេលបង្កើតការងារ ហើយកាត់មុនពេលបកប្រែចាប់ផ្តើម; ក្រេឌីតដែលមិនបានប្រើពីការងារបរាជ័យ ឬបោះបង់ ត្រូវបានសងវិញដោយស្វ័យប្រវត្តិ។

បំពេញក្រេឌីតដោយ Bakong KHQR (ឬកាត) នៅទំព័រវិក្កយបត្ររបស់អ្នក — ក្រេឌីតចែករំលែករវាងឧបករណ៍គេហទំព័រ និង API។

លើសពី ១,០០០ ទំព័រក្នុងមួយឯកសារ? ទាក់ទងមកយើងសម្រាប់សម្រង់តម្លៃផ្ទាល់ខ្លួន។

សំណើរនីមួយៗដឹកកូនសោ TosKey API ក្នុង header Authorization: Bearer។ ចេញកូនសោនៅ TosKey Console ផ្នែក InKhmer (S5) — កូនសោថ្មីជ្រើស scopes translator ទាំងបីដោយស្វ័យប្រវត្តិ។

Authorization: Bearer sk_live_…
# scopes: translator:translate | translator:read | translator:cancel

• translator:translate — បង្កើតការងារ បង្កើត upload intent និង finalize ការផ្ទុកឡើង។
• translator:read — តាមដានស្ថានភាពការងារ និងទាញយក PDF។
• translator:cancel — បោះបង់ការងារកំពុងដំណើរការ និងសងក្រេឌីតទំព័រដែលមិនទាន់បកប្រែ។
• translator:* — wildcard គ្របដណ្តប់ទាំងបី; ត្រូវបានជ្រើសជាលំនាំដើមលើកូនសោថ្មី។

បើក TosKey Console

TosKey gateway អនុវត្តដែនកំណត់ក្នុងមួយកូនសោមុនពេលសំណើរឈានដល់ API។ ចម្លើយនីមួយៗមាន X-RateLimit-Limit / -Remaining / -Reset ហើយនៅពេល 429 មាន Retry-After ប្រាប់ចំនួនវិនាទីត្រូវរង់ចាំ។

50 req/min — កូនសោទាំងអស់របស់អត្តសញ្ញាណតែមួយចែករំលែកដែនកំណត់ burst កម្រិតគណនី ៥០ សំណើ/នាទី — សំណើទី ៥១ ក្នុងមួយនាទីត្រូវបដិសេធនៅ gateway។

pro-translator-rate pro-translator-rate លើកដែនកំណត់សរសេរទៅ ១០០/នាទី · ១,០០០/ម៉ោង · ១០,០០០/ថ្ងៃ ក្នុងមួយកូនសោ។ វាត្រូវបានកំណត់ដោយប្រតិបត្តិករក្នុង TosKey Console — ទាក់ទងមកយើងដើម្បីស្នើសុំ; វាមិនមែន self-serve ទេ។

អាន X-RateLimit-Remaining ដើម្បីបន្ថយល្បឿនមុនពេលឈប់ ហើយគោរព Retry-After លើចម្លើយ 429។ X-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-ResetRetry-After

ប្រតិបត្តិការនីមួយៗខាងក្រោមត្រូវបានបង្ហាញពីឯកសារ OpenAPI ផ្ទាល់ — request/response body, parameter និងឧទាហរណ៍កំហុសពិតប្រាកដដែល API ត្រឡប់មក។

ទាញយក openapi.jsonPostman collectionកូដឧទាហរណ៍ (zip)

idempotency-key — ប្រតិបត្តិការផ្លាស់ប្តូរទទួល header Idempotency-Key។ ការហៅឡើងវិញដោយកូនសោដដែលក្នុងរយៈពេល ២៤ ម៉ោង ត្រឡប់ចម្លើយដើមដោយមិនកាត់ក្រេឌីតពីរដង។

• កូនសោមានវិសយក្នុងមួយកូនសោ API — កូនសោពីរផ្សេងគ្នាប្រើតម្លៃដដែលចាប់ផ្តើមការងារឯករាជ្យ។
• ការហៅឡើងវិញដោយកូនសោដដែលប៉ុន្តែ payload ផ្សេង ត្រឡប់ 409 idempotency_conflict។
• ការព្យាយាមឡើងវិញដោយសុវត្ថិភាព៖ ប្រសិនបើការហៅបង្កើត timeout សូម retry ដោយ Idempotency-Key ដដែល — ការហៅទីពីរបានការងារដើមវិញជំនួសឱ្យការកាត់ក្រេឌីតពីរដង។
• Idempotency-Key ត្រូវមានប្រវែង ៨–២៥៥ តួអក្សរ; យើងណែនាំ uuidv4/uuidv7។

v1 គ្មាន webhooks ទេ — សូមហៅ GET /jobs/{jobId} រៀងរាល់ ~២ វិនាទី រហូតស្ថានភាពជា done, error ឬ cancelled។ webhook job.done ស្ថិតក្នុងផែនទីផ្លូវ។

ការប្រើប្រាស់ API មានន័យថាអ្នកទទួលយកលក្ខខណ្ឌ API របស់ InKhmer — ការប្រើប្រាស់ដែលទទួលយកបាន ការរក្សាទុក និងការអនុវត្តដែនកំណត់អត្រា។ អានលក្ខខណ្ឌ API