Tài liệu API · Tài nguyên

Loại tài nguyên và xác minh người thật

trust_class, nhân vật ảo và xác minh khuôn mặt cho ảnh người thật.

Khi tạo tài nguyên, khai báo loại bằng trust_class. Nền tảng không tự nhận diện chân dung, khai báo của bạn là căn cứ; không thể đổi sau khi tạo, nếu khai báo sai hãy xóa rồi tải lên lại.

trust_class	Dùng cho	Điều kiện sử dụng
`normal`	Ảnh, video, âm thanh thông thường (mặc định)	Dùng được ngay sau khi xử lý
`virtual_avatar`	Nhân vật ảo như hình do AI tạo hoặc hoạt hình, để giữ nhất quán nhân vật	Dùng được ngay sau khi xử lý; lần đầu dùng trong tác vụ, nền tảng đồng bộ tài nguyên sang thư viện tài nguyên của kênh xử lý (trạng thái tác vụ preparing) và chỉ phân vào các kênh có thư viện tài nguyên
`real_person`	Ảnh người thật (chỉ ảnh)	Ban đầu là authorization_required; chỉ dùng được sau khi chính người trong ảnh hoàn tất xác minh người thật

Quy trình xác minh người thật

Gọi POST /v1/assets/{id}/portrait-authorizations với { "model": "…" } (mô hình sẽ dùng tài nguyên này). Trả về 201 và đối tượng xác minh: status là pending, kèm h5_link và expires_at (sau 30 phút).
Gửi h5_link cho người trong ảnh (ví dụ dạng mã QR). Người đó mở bằng điện thoại và làm theo hướng dẫn để xác minh khuôn mặt. Khi xong, trang chuyển đến trang thông báo của trang này; hãy chờ kết quả trong ứng dụng của bạn.
Truy vấn GET /v1/portrait-authorizations/{id} khoảng 5 giây một lần cho đến khi status thành verified, failed hoặc expired. Nền tảng cũng kiểm tra ngầm, nên trạng thái vẫn cập nhật dù bạn không truy vấn.
Khi đã verified, tài nguyên chuyển thành available và dùng được trong tác vụ của mô hình đó.

Bạn cũng có thể bắt đầu ngay trong chi tiết tài nguyên tại Bảng điều khiển · Tài nguyên; trang hiển thị mã QR và tự cập nhật kết quả.GET /v1/assets/{id}/portrait-authorizations liệt kê các lần xác minh gần đây của tài nguyên.

Trạng thái xác minh

status	Ý nghĩa
`pending`	Đang chờ người đó xác minh khuôn mặt; h5_link chỉ trả về ở trạng thái này
`verified`	Đã xác minh; verified_at là thời điểm thông qua
`failed`	Không đạt; error cho biết nguyên nhân. Có thể bắt đầu lại
`expired`	Không hoàn tất trong 30 phút. Có thể bắt đầu lại

Xác minh áp dụng theo mô hình

Xác minh chỉ có hiệu lực với mô hình đã chọn khi bắt đầu. Gửi tác vụ của mô hình khác với tài nguyên này sẽ trả về 422 authorization_required; hãy bắt đầu xác minh thêm một lần cho mô hình đó. Nếu tài nguyên đã được xác minh cho cùng mô hình, bắt đầu lại sẽ trả về bản ghi verified sẵn có.

Lỗi

HTTP	code	Khi nào
422	`invalid_parameter`	Tài nguyên không phải real_person, không phải ảnh, hoặc model không tồn tại
403	`permission_denied`	Tài khoản chưa được mở mô hình này
404	`not_found`	Tài nguyên hoặc bản ghi xác minh không tồn tại, hoặc không thuộc về bạn
503	`no_available_channel`	Hiện chưa có kênh xác minh người thật cho mô hình này; thử lại sau

Người trong ảnh phải là người đã xác minh khuôn mặt

Upstream so sánh tài nguyên với khuôn mặt đã xác minh. Nếu không khớp, tài nguyên không dùng được để tạo video và các tác vụ dùng nó thất bại với asset_rejected.

# Bắt đầu xác minh: trả về h5_link, hiệu lực 30 phút
curl https://api.aitoken.tools/v1/assets/asset_xxx/portrait-authorizations \
  -H "Authorization: Bearer $AITOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"seedance-2.0-standard"}'

# Gửi h5_link cho người trong ảnh để xác minh khuôn mặt, rồi truy vấn đến khi status là verified / failed / expired
curl https://api.aitoken.tools/v1/portrait-authorizations/auth_xxx \
  -H "Authorization: Bearer $AITOKEN_API_KEY"