Chấm điểm

Stable

Trả về điểm từng tiêu chí kèm nhận xét, trích dẫn đúng câu bị lỗi và mã lỗi tương ứng để hệ thống của bạn xử lý tiếp.

Chạy thử

Thao tác từng bước trên trình duyệt và xem đúng những lệnh gọi mà backend thực hiện.

Mở demo ›

Danh mục

Bộ API xử lý bài viết IELTS — chấm điểm, sinh bài tập bám đúng lỗi sai, và dựng lộ trình luyện tập cá nhân hoá.

Xem tất cả sản phẩm ›

1. Tổng quan

Chấm bài viết IELTS Writing theo 4 tiêu chí, trả về band từng tiêu chí kèm lý do, góp ý và trích dẫn đúng câu cần sửa trong bài.

Base URLapi.aihubproduction.com
Định dạngapplication/json
Xác thựcAPI key (scope writing.grade) + X-User-Identity (bắt buộc)
Idempotency-KeyBắt buộc, giữ 24 giờ
Trạng tháiStable

2. Các bước tích hợp

Luồng tích hợp chấm điểm vào hệ thống của bạn, theo từng bước dưới đây.

Lấy API key có scope writing.grade
AIHUB cấp API key cho Organization, mỗi key chỉ dùng được trong các Environment được phép và nên được gọi từ server của bạn. Key hiển thị đúng một lần lúc tạo hoặc xoay vòng — lưu vào secret manager ngay. Key thiếu scope writing.grade sẽ bị từ chối với 403 FORBIDDEN.
Chọn đúng dạng User Identity của Organization
Cả hai endpoint đều là user-scoped nên X-User-Identity không được thiếu. Organization có Identity configuration đang hoạt động thì gửi Signed User Assertion — một JWT ngắn hạn do backend của bạn ký; Organization chưa có cấu hình nào đang hoạt động (kể cả cấu hình bị tắt) thì gửi Declared User ID dạng văn bản thuần, 1–256 ký tự ASCII hiển thị, không có khoảng trắng. Cấu hình của Organization quyết định dạng, không phải hình dạng giá trị.
Gán một Idempotency-Key cho mỗi lần chấm
Chấm Writing có phí và có thể mất tới 60 giây. Mỗi lần chấm — mỗi bài làm — cần một Idempotency-Key riêng. Retry thì gửi lại đúng key cũ và đúng body cũ: AIHUB trả lại kết quả đã lưu kèm header Idempotent-Replay: true thay vì chấm lại. Đổi bất kỳ trường nào trong body thì phải lấy key mới, nếu không sẽ nhận 409 IDEMPOTENCY_CONFLICT.
Gửi đề bài và bài làm
Task 1 cần thêm image_url tới ảnh biểu đồ AIHUB có thể truy cập, cùng chart_type đúng loại biểu đồ. Task 2 không cần ảnh, chỉ cần topic. Cả hai đều trả nhận xét tiếng Việt. Đặt timeout phía client tối thiểu 90 giây.
Hiển thị feedback theo đúng thứ tự tiêu chí
criteria luôn có đúng 4 phần tử theo thứ tự cố định; Task 1 bắt đầu bằng task_achievement, Task 2 bắt đầu bằng task_response. annotations trích nguyên văn câu trong bài kèm criterion và issue, dùng để ghim nhận xét vào đúng chỗ.