Dịch vụ AI

Cách tích hợp nhận diện biển số xe

Gửi ảnh phương tiện, nhận về biển số đã chuẩn hóa kèm loại xe, vùng đăng ký và độ tin cậy. Đã tối ưu cho biển số Việt Nam.

Chọn endpoint

Endpoint	Dùng khi
`POST /v1/ai/license-plates/recognize`	Ảnh chụp cả phương tiện. Hệ thống tự tìm biển số trong ảnh.
`POST /v1/ai/license-plates/recognize-cropped`	Ảnh đã cắt sát biển số. Bỏ qua bước dò tìm nên nhanh hơn.

Nội dung request

Gửi dạng multipart/form-data:

file là tham số bắt buộc. JPEG, PNG, WebP, GIF, BMP hoặc TIFF, tối đa 10 MB.
image_base64 là cách thay thế cho file: chuỗi Base64 thuần, hoặc data URL dạng data:image/...;base64. Gửi kèm filename nếu muốn kết quả có tên tệp.

Ví dụ

curl -X POST https://core.roammoon.com/v1/ai/license-plates/recognize \
  -H "X-API-Key: rm_live_YOUR_KEY" \
  -F "file=@motorbike.jpg"

Kết quả trả về

Trả về mảng plates, sắp theo độ tin cậy giảm dần:

JSON

{
  "country": "Vietnam",
  "filename": "motorbike.jpg",
  "plates": [
    {
      "is_valid": true,
      "best_raw": "47-AB\n123.45",
      "best_normalized": "47AB12345",
      "vehicle": "motorcycle",
      "type": "Private organization / individual",
      "region_code": "47",
      "region_name": "Dak Lak",
      "current_administrative_region": "Dak Lak",
      "era": "current",
      "layout": "double",
      "background": "white",
      "votes": 3,
      "confidence": 0.9,
      "validation_reason": null
    }
  ],
  "processing_time_ms": 142.517
}

Khi không tìm thấy biển số

Mảng plates rỗng. Nếu OCR đọc được chuỗi nhưng không khớp quy tắc biển số Việt Nam, chuỗi vẫn được trả về kèm is_valid = false, và bạn tự quyết định có dùng hay không.

Các trường quan trọng

Trường	Ý nghĩa
`best_normalized`	Chỉ gồm chữ và số, không dấu phân cách. Dùng trường này để so khớp và lưu trữ.
`best_raw`	Giữ nguyên dấu chấm, gạch nối và xuống dòng như trên biển thật. Dùng để hiển thị.
`is_valid`	Kết quả có khớp quy tắc biển số Việt Nam hay không.
`confidence`, `votes`	votes là số lượt OCR cùng đọc ra kết quả này. Nhiều phiếu và confidence cao thì đáng tin hơn.
`region_code`, `current_administrative_region`	Mã tỉnh gốc và đơn vị hành chính hiện nay, hữu ích với các tỉnh đã sáp nhập.

Tính phí

Chỉ khi nhận diện thành công và trả về kết quả thì mới bị trừ 1 credit. Mọi trường hợp thất bại đều được hoàn lại, dù là ảnh bị từ chối hay chính dịch vụ không xử lý được.

Chính sách tính phí là charge-on-success: credit được giữ chỗ khi tiếp nhận request và chỉ thực sự trừ khi xử lý thành công. Thất bại thì hoàn lại.

Mẹo đạt độ chính xác cao

Ảnh nét, biển số chiếm phần đáng kể khung hình. Ảnh mờ do rung là nguyên nhân sai số phổ biến nhất.
Nếu đã biết vị trí biển số, dùng recognize-cropped để nhanh hơn và ít nhiễu hơn.
Luôn kiểm tra is_valid trước khi ghi vào cơ sở dữ liệu, thay vì tin tuyệt đối vào chuỗi trả về.

Lỗi

Mọi lỗi đều dùng chung một cấu trúc. Hãy xử lý theo trường code, không phải theo message, vì message có thể thay đổi.

JSON

{
  "error": {
    "code": "IMAGE_TOO_LARGE",
    "message": "The uploaded image is too large."
  }
}

HTTP	Mã lỗi	Nên làm gì
401	`API_KEY_REQUIRED`	Thiếu header X-API-Key.
401	`API_KEY_INVALID`	Key sai, đã bị vô hiệu hóa hoặc hết hạn. Kiểm tra lại hoặc tạo key mới.
403	`API_KEY_FORBIDDEN`	Key không có quyền dùng dịch vụ này.
400	`INVALID_LICENSE_PLATE_REQUEST`	Ảnh hoặc tùy chọn không hợp lệ. Không bị trừ credit.
402	`CREDIT_LIMIT_EXCEEDED`	Hết credit trong chu kỳ. Nâng gói hoặc chờ sang chu kỳ mới.
413	`IMAGE_TOO_LARGE`	Ảnh vượt quá 10 MB. Nén hoặc giảm kích thước rồi gửi lại.
415	`UNSUPPORTED_IMAGE_TYPE`	Định dạng ảnh không được hỗ trợ.
429	`RATE_LIMIT_EXCEEDED`	Vượt giới hạn request mỗi phút.
429	`LICENSE_PLATE_SERVICE_BUSY`	Dịch vụ đang quá tải. Thử lại sau vài giây.
502	`LICENSE_PLATE_UPSTREAM_ERROR`	Mô hình không hoàn tất được request. Thử lại sau.
503	`LICENSE_PLATE_SERVICE_UNAVAILABLE`	Dịch vụ tạm thời không khả dụng. Thử lại sau.

Thử lại an toàn

Lỗi 429, 502 và 503 đều thử lại được, hãy dùng backoff tăng dần. Với các lỗi khác, thử lại sẽ cho cùng kết quả. Vì chỉ lần nhận diện thành công mới bị trừ credit nên thử lại sau khi lỗi không tốn thêm gì. Riêng khi mạng timeout mà lần gọi đầu thực ra đã thành công, lần thử lại sẽ bị tính thêm một credit.

Tiếp theo: Tham chiếu API →