Imbasan API
Imbasan API menukar PDF menjadi hasil imbasan yang meyakinkan melalui satu panggilan REST, sesuai untuk aliran kerja automatik dan penyepaduan aplikasi. Cipta tugas, muat naik PDF, kemudian tinjau statusnya atau tunggu webhook: tiga langkah, daripada mana-mana persekitaran atau bahasa yang boleh menghantar permintaan HTTP. Ruang warna, resolusi, putaran, kekaburan, hingar, kecerahan, kontras dan sempadan semuanya boleh ditetapkan.
Bagaimana satu panggilan berjalan
Cipta tugas
POST /v1/scan-jobs
Hantar config anda dan, jika mahu, webhookUrl; anda menerima jobID dan uploadURL yang telah ditandatangani.
Muat naik PDF
PUT {uploadURL}
Lakukan PUT fail terus ke alamat S3 bertandatangan daripada langkah sebelumnya — tanpa token.
Ambil hasil imbasan
GET /v1/scan-jobs/{jobID}
Tinjau statusnya atau tunggu webhook; sebaik tugas berstatus completed, muat turun melalui downloadURL.
Sesuai untuk keadaan ini
Pengeluaran pukal di bahagian pelayan
Kontrak, invois dan laporan yang dijana pada pelayan terus melalui kesan imbasan, tanpa sesiapa mengulanginya secara manual di halaman web.
Dalam sistem sedia ada
Tambahkan tindakan «eksport hasil imbasan» pada CRM, ERP atau sistem tiket, dan biarkan ia memanggil API.
Rantaian automasi
CI, n8n, Zapier dan seumpamanya memulakan tugas apabila sesuatu berlaku, dan webhook menyerahkannya kepada langkah seterusnya setelah selesai.
Baris gilir fail yang besar
Tugas bersifat tak segerak: setelah dicipta, setiap satu diproses sendiri, dan kemajuannya boleh disemak melalui status dan createdAfter.
Bahasa dan persekitaran
API ini ialah HTTP dan JSON biasa, jadi mana-mana bahasa atau platform automasi yang boleh menghantar permintaan mampu memanggilnya.
Contoh kod
Add Look Scanned API Scan to this project, so I can turn a PDF into a
realistic scanned copy from code.
API docs: https://lookscanned.io/en/scan/api
Write one function that:
1. POST https://api.lookscanned.io/v1/scan-jobs
Header: Authorization: Bearer $LOOKSCANNED_API_TOKEN
Body: {"config": {"colorspace": "gray", "resolution": 150, "rotate": 1}}
It returns jobID and a presigned uploadURL.
2. PUT the PDF bytes to uploadURL with Content-Type: application/pdf.
Send no Authorization header — that URL is already signed.
3. Poll GET /v1/scan-jobs/{jobID} until status is "completed" (or "failed"),
then return downloadURL.
Read the token from the LOOKSCANNED_API_TOKEN environment variable. Use the
language and HTTP client this project already uses, and add one test.interface ScanConfig {
rotate?: number // degrees to rotate the document
rotate_var?: number // degrees to rotate the document randomly
colorspace?: 'gray' | 'sRGB' // the colorspace of the output image
blur?: number // the amount of blur to apply to the image
noise?: number // the amount of noise to apply to the image
border?: boolean // whether to add a border to the image
brightness?: number // the brightness of the image. 1 is no change
contrast?: number // the contrast of the image. 1 is no change
resolution?: number // the resolution of the image in DPI
output_format?: 'image/png' | 'image/jpeg' // the format of the output image
}
interface ScanOptions {
config: ScanConfig
webhookUrl?: string // webhook URL to notify when job is completed
}
interface ScanResponse {
jobID: string // UUID of the scan job
userID: string // UUID of the user who created the job
createdAt: number // timestamp of job creation
status: 'pending' | 'processing' | 'completed' | 'failed'
config: ScanConfig
inputUploadedAt?: number // timestamp when input file was uploaded
completedAt?: number // timestamp when job was completed
webhookUrl?: string // webhook URL for notifications
uploadURL?: string // S3 presigned URL for file upload
downloadURL?: string // S3 presigned URL for file download
}
async function apiScan(pdfBlob: Blob, scanOptions: ScanOptions, token: string): Promise<ScanResponse> {
const response = await fetch('https://api.lookscanned.io/v1/scan-jobs', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`
},
body: JSON.stringify(scanOptions)
})
const result: ScanResponse = await response.json()
// PUT PDF Blob to upload URL
const uploadURL = result.uploadURL
await fetch(uploadURL, {
method: 'PUT',
headers: {
'Content-Type': 'application/pdf',
'Content-Length': pdfBlob.size.toString()
},
body: pdfBlob
})
// get scan job status
const jobStatusResponse = await fetch(`https://api.lookscanned.io/v1/scan-jobs/${result.jobID}`, {
headers: {
'Authorization': `Bearer ${token}`
}
})
return await jobStatusResponse.json()
}import requests
def api_scan(pdf_file, scan_options, token):
# Create scan job
response = requests.post(
'https://api.lookscanned.io/v1/scan-jobs',
headers={'Authorization': f'Bearer {token}'},
json=scan_options
)
result = response.json()
# Upload PDF to presigned URL
upload_url = result['uploadURL']
requests.put(
upload_url,
headers={
'Content-Type': 'application/pdf',
'Content-Length': str(len(pdf_file))
},
data=pdf_file
)
# Get scan job status
job_status = requests.get(
f'https://api.lookscanned.io/v1/scan-jobs/{result["jobID"]}',
headers={'Authorization': f'Bearer {token}'}
)
return job_status.json()
# Example usage
if __name__ == "__main__":
with open('document.pdf', 'rb') as f:
pdf_content = f.read()
options = {
'config': {
# Optional parameters:
# 'rotate': 0, # degrees to rotate the document
# 'colorspace': 'gray', # gray or sRGB
# 'resolution': 300, # DPI
# 'rotate_var': 0, # random rotation variance in degrees
# 'blur': 0, # amount of blur
# 'noise': 0, # amount of noise
# 'border': False, # whether to add border
# 'brightness': 1, # 1 is no change
# 'contrast': 1, # 1 is no change
# 'output_format': 'image/png' # image/png or image/jpeg
},
'webhookUrl': 'https://example.com/webhook'
}
result = api_scan(pdf_content, options, 'your-api-token')
print(f"Scan job created with ID: {result['jobID']}")# Set your API token and PDF file as environment variables
export LOOKSCANNED_API_TOKEN='your_api_token_here'
# Create a new scan job
curl -X POST 'https://api.lookscanned.io/v1/scan-jobs' \
-H "Authorization: Bearer ${LOOKSCANNED_API_TOKEN}" \
-H 'Content-Type: application/json' \
-d '{
"config": {
"rotate": 0,
"rotate_var": 1,
"colorspace": "gray",
"blur": 0.2,
"noise": 0.1,
"border": true,
"brightness": 1.0,
"contrast": 1.0,
"resolution": 300,
"output_format": "image/jpeg"
},
"webhookUrl": "https://your-domain.com/webhook"
}'
# Response will include uploadURL and jobID
# {
# "jobID": "550e8400-e29b-41d4-a716-446655440000",
# "userID": "446655440000-e29b-41d4-a716-550e8400",
# "createdAt": 1616161616,
# "status": "created",
# "uploadURL": "...",
# "config": { ... }
# }
# Upload PDF file to the presigned URL
curl -X PUT 'PRESIGNED_UPLOAD_URL' \
-H 'Content-Type: application/pdf' \
-H "Content-Length: PDF_FILE_SIZE" \
--data-binary "@path/to/your/file.pdf"
# Check job status
curl 'https://api.lookscanned.io/v1/scan-jobs/JOB_ID' \
-H "Authorization: Bearer ${LOOKSCANNED_API_TOKEN}"
# Response will include status and downloadURL when completed
# {
# "jobID": "550e8400-e29b-41d4-a716-446655440000",
# "status": "completed",
# "downloadURL": "...",
# ...
# }
# Download the PDF
curl -o scanned.pdf 'DOWNLOAD_URL'API Bearer Token
Token terikat pada akaun anda dan boleh dijana semula bila-bila masa. Imbasan API memerlukan akaun Pro: tanpa token yang sah API membalas 401, dan tanpa peranan Pro ia membalas 403.
Imbasan API ialah ciri Pro
Akaun ini belum Pro; selepas menaik taraf, token akan muncul di sini. Tanpa token, atau tanpa peranan itu, API membalas 401 / 403.
Cuba
Tetapkan parameternya, lihat kandungan permintaan berubah mengikutnya, kemudian jalankan tiga panggilan ke API.
Parameter imbasan
Larian percubaan memanggil API dengan token anda dan memerlukan akaun Pro; parameter dan kandungan permintaan bebas dibaca.
{
"config": {
"rotate": 1,
"rotate_var": 0.5,
"colorspace": "gray",
"blur": 0,
"noise": 0,
"border": false,
"brightness": 1.3,
"contrast": 1.3,
"resolution": 150,
"output_format": "image/jpeg"
}
}Maklumat Tugas Imbasan
contoh{
"jobID": "3f9c1e64-0000-4000-8000-00000000a71b",
"userID": "8f21c4b0-0000-4000-8000-000000004a17",
"createdAt": 1724409600,
"status": "completed",
"inputUploadedAt": 1724409601,
"completedAt": 1724409602,
"numPages": 6,
"downloadURL": "https://…/output/3f9c.pdf?X-Amz-…"
}Rujukan API
| Kaedah | Laluan | Keterangan |
|---|---|---|
| POST | /v1/scan-jobs | Mencipta tugas imbasan. Hantar config dan, jika perlu, webhookUrl; anda menerima objek tugas berstatus created serta uploadURL bertandatangan. |
| PUT | {uploadURL}Alamat S3 bertandatangan daripada langkah sebelumnya, yang bukan di api.lookscanned.io | Memuat naik PDF sumber dengan Content-Type: application/pdf dan Content-Length. Alamat itu sudah membawa tandatangannya sendiri, jadi jangan tambah pengepala Authorization. |
| GET | /v1/scan-jobs/{jobID} | Membaca satu tugas, untuk tinjauan berkala. Pada created ia mengandungi uploadURL, pada completed pula downloadURL. |
| GET | /v1/scan-jobs | Menyenaraikan tugas anda sendiri, ditapis mengikut jobID, status atau createdAfter. |
401tiada token yang sah403akaun bukan Pro404tugas tidak wujud
Kandungan permintaan
| Medan | Jenis | Lalai | Keterangan |
|---|---|---|---|
| webhookUrl | string · — | — | Dipanggil sekali sebaik tugas selesai, jadi anda tidak perlu meninjau statusnya. |
| config.colorspace | 'gray' | 'sRGB' · gray | gray | Ruang warna imej keluaran; gray bermaksud hasil imbasan hitam putih. |
| config.resolution | number · 72 | 72 | Resolusi imej keluaran, dalam DPI. |
| config.rotate | number · — | — | Putaran seluruh dokumen, dalam darjah. |
| config.rotate_var | number · — | — | Julat putaran rawak bagi setiap halaman, dalam darjah — kesan kertas yang diletakkan senget. |
| config.blur | number · 0 | 0 | Tahap kekaburan. |
| config.noise | number · 0 | 0 | Tahap hingar. |
| config.brightness | number · 1 | 1 | Kecerahan; 1 bermakna tiada perubahan. |
| config.contrast | number · 1 | 1 | Kontras; 1 bermakna tiada perubahan. |
| config.border | boolean · false | false | Sama ada halaman diberi sempadan imbasan. |
| config.output_format | 'image/png' | 'image/jpeg' · image/jpeg | image/jpeg | Format imej semasa halaman diterjemah. |
Setiap medan boleh ditinggalkan. Nilai permulaan dalam bahagian «Cuba» — resolusi 150, putaran 1, kecerahan dan kontras 1.3 — ialah gabungan yang disyorkan aplikasi web, bukan nilai lalai API.
Medan dalam objek tugas yang perlu diberi perhatian
- status
- created / processing / completed / failed — menentukan sama ada dua alamat di bawah muncul.
- uploadURL
- Hanya semasa berstatus created. Alamat muat naik bertandatangan yang ada tempoh sah.
- downloadURL
- Hanya setelah berstatus completed. Alamat muat turun bertandatangan yang ada tempoh sah.
- inputUploadedAt / completedAt
- Bila muat naik sumber selesai dan bila tugas selesai; bezanya ialah masa pemprosesan.
Soalan lazim
Adakah imbasan API memerlukan Pro?
Ya. Tanpa token yang sah API membalas 401, dan akaun tanpa peranan Pro menerima 403. Selepas menaik taraf dan log masuk, token itu ada pada halaman ini.
Bagaimana saya tahu tugas sudah selesai?
Dua cara: tinjau GET /v1/scan-jobs/{jobID}, atau hantar webhookUrl semasa mencipta tugas dan biarkan perkhidmatan menghubungi anda sekali.
Adakah hasilnya sama seperti mengimbas di halaman web?
Sama. Kedua-duanya menggunakan pelaksanaan kesan imbasan yang sama, dan ruang warna, resolusi, putaran, kekaburan, hingar, kecerahan, kontras serta sempadan dalam config ialah pilihan bernama sama di halaman web: parameter sama memberi keluaran sama. Yang berbeza hanyalah tempat pemprosesan — setempat pada halaman, jauh melalui API.
Bolehkah saya menyimpan alamat muat naik dan muat turun untuk digunakan semula?
Lebih baik jangan. uploadURL dan downloadURL ialah alamat bertandatangan yang ada tempoh sah; setelah tamat tempoh anda perlu membaca semula tugas itu untuk mendapat yang baharu.
Berapa lama satu tugas diproses?
Bergantung pada bilangan halaman dan resolusi. Dokumen beberapa halaman biasanya siap dalam beberapa saat; resolusi lebih tinggi dan dokumen lebih panjang mengambil masa lebih lama. Beza antara inputUploadedAt dan completedAt memberi masa sebenar.
Bagaimana jika sesuatu tugas gagal?
Statusnya bertukar kepada failed. Puncanya lazimnya fail yang bukan PDF sah, sekatan penyulitan, atau muat naik yang terputus. Pastikan fail itu boleh dibuka, kemudian cipta tugas baharu.
Bolehkah saya menyemak tugas lampau?
Boleh. GET /v1/scan-jobs menyenaraikan tugas anda sendiri dan boleh ditapis mengikut jobID, status dan createdAfter — memadai untuk penyesuaian rekod atau muat turun semula.