Chấm Speaking

Stable

Gửi câu hỏi và bản ghi âm để nhận transcript, độ liên quan, band ước tính và gợi ý cải thiện ngữ pháp, từ vựng, phát âm.

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 luyện và chấm IELTS Speaking — lấy câu hỏi theo Part, nhận audio và trả về transcript cùng phân tích theo rubric.

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

1. Tổng quan

Chấm phần nói IELTS Speaking từ file âm thanh, trả về transcript, band ước tính theo 5 tiêu chí phát âm và độ trôi chảy, cùng gợi ý sửa lỗi ngữ pháp và từ vựng.

Base URLapi.aihubproduction.com
Định dạngmultipart/form-data, hoặc application/json cho dạng URL
Xác thựcAPI key (scope speaking.grade) + X-User-Identity cho endpoint chấm
Lấy câu hỏiGET không cần xác thực, không user-scoped
Idempotency-KeyEndpoint chấm không hỗ trợ
Trạng tháiStable

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

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

Lấy API key có scope speaking.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 speaking.grade sẽ bị từ chối với 403 FORBIDDEN.
Chọn đúng dạng User Identity của Organization
Hai endpoint chấm đề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ị. Endpoint lấy câu hỏi không user-scoped nên không cần header này.
Lấy câu hỏi trước khi chấm
Gọi GET /v1/ielts/speaking/questions?part=1 (hoặc part=2, part=3) để lấy question_id và prompt_text thật. Gửi question_id từ danh mục này, đừng tự đặt — mỗi Part có bộ câu hỏi riêng.
Gửi file âm thanh
Dạng chính nhận một tệp wav, mp3, m4a, webm hoặc ogg, tối đa 25 MiB. Dạng dự phòng nhận audio_url trỏ tới một đối tượng trên s3.wispace.app, dùng khi bạn không thể tải tệp lên. Cả hai cùng nhận part, question_id và các trường tuỳ chọn.
Đọc kết quả theo đúng thứ tự
Kiểm tra scorability trước: is_scorable false nghĩa là lượt nói không đủ để chấm, và message_vi giải thích vì sao. Khi chấm được, estimated_band.overall cho band tổng, còn transcript cho nội dung đã nghe và pronunciation_detail cho chi tiết từng âm.