API phát hiện âm thanh AI

1. Lấy URL tải lên đã ký sẵn

Yêu cầu URL ký sẵn từ API để tải tệp âm thanh lên máy chủ lưu trữ an toàn.

GET https://detect-audio.truthscan.com/get-presigned-url?file_name=example.mp3

Ví dụ yêu cầu

curl -X GET 'https://detect-audio.truthscan.com/get-presigned-url?file_name=example.mp3' \
--header 'apikey: YOUR API KEY GOES HERE'

Ví dụ phản hồi

{
  "status": "success",
  "presigned_url": "https://audio-presigned-upload.ai-assets-cdn.com?file_name=581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.mp3...",
  "file_path": "/uploads/581d47c7-3ef4-42af-88d9-6dab6bf69389_20250901-090201_example.mp3"
}

2. Tải lên âm thanh

Dùng 'presigned_url' để tải lên bằng PUT. Đặt đúng Content-Type theo định dạng.

Ví dụ yêu cầu

curl -X PUT 'https://audio-presigned-upload.ai-assets-cdn.com?file_name=581d47c7-3ef4-42af-88d9-6dab6bf69389_20250611-121955_example.mp3...' \
  --header 'Content-Type: audio/<FILE_FORMAT - mp3, wav, m4a, flac, ogg, mp4>' \
  --header 'x-amz-acl: private' \
  --data-binary '@example.mp3' # Attachment

Giữ nguyên định dạng trong suốt quá trình tải. Tải thành công trả về mã 200.

3. Gửi âm thanh để phát hiện AI

Sau khi tải, gửi âm thanh phát hiện AI với 'file_path' từ bước trước.

POST https://detect-audio.truthscan.com/detect

Ví dụ yêu cầu

curl -X 'POST' \
  'https://detect-audio.truthscan.com/detect' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": "YOUR-API-KEY-GOES-HERE",
  "url": "<FILE_PATH>",
  "document_type": "Audio",
  "analyzeUpToSeconds": 60
}'

'FILE_PATH' là đường dẫn từ phản hồi bước 'Lấy URL tải lên đã ký sẵn'.

Ví dụ phản hồi

{
    "id": "77565038-9e3d-4e6a-8c80-e20785be5ee9",
    "status": "pending"
}

Phản hồi gồm ID duy nhất để theo dõi trạng thái phát hiện.

"User verification failed" (403)

Nguyên nhân: API key không hợp lệ hoặc hết hạn

Cách xử lý:

1. Xác minh API key đúng
2. Kiểm tra API key còn hoạt động
3. Thử tạo lại API key

"Not enough credits" (403)

Nguyên nhân: Không đủ credit xử lý âm thanh

Cách xử lý:

1. Kiểm tra credit bằng /check-user-credits
2. Mua thêm credit nếu cần
3. Dùng analyzeUpToSeconds để phân tích ít giây hơn, tiêu ít credit hơn

"Unsupported file format" (400)

Nguyên nhân: Định dạng âm thanh không hỗ trợ hoặc không hợp lệ

Cách xử lý:

1. Xác minh định dạng được hỗ trợ (MP3, WAV, M4A, FLAC, OGG, MP4)
2. Đảm bảo tệp không hỏng
3. Kiểm tra header Content-Type khi tải lên

"File too large" (400)

Nguyên nhân: Vượt giới hạn 100MB

Cách xử lý:

1. Nén hoặc chuyển đổi dưới 100MB
2. Kiểm tra kích thước trước khi tải
3. Ưu tiên định dạng hiệu quả như MP3

"Audio processing took too long"

Nguyên nhân: Xử lý quá lâu hoặc timeout

Cách xử lý:

1. Thử tệp nhỏ hơn hoặc ngắn hơn
2. Dùng analyzeUpToSeconds chỉ phân tích vài giây đầu
3. Kiểm tra tải dịch vụ
4. Thử lại sau vài phút

Trạng thái "failed" trong phản hồi /query

Nguyên nhân: Xử lý thất bại vì nhiều lý do

Cách xử lý:

1. Kiểm tra âm thanh trong khoảng 1KB–100MB
2. Xác minh định dạng được hỗ trợ
3. Đảm bảo tải lên hoàn tất trước khi gửi phát hiện
4. Liên hệ hỗ trợ nếu vẫn lỗi

"Audio upload failed" (403/400)

Nguyên nhân: URL ký sẵn không hợp lệ/hết hạn hoặc lỗi máy chủ lưu trữ

Cách xử lý:

1. Dùng URL ký sẵn ngay sau khi nhận (có thể hết hạn)
2. Xác minh Content-Type đúng định dạng âm thanh
3. Xóa khoảng trắng trong tên tệp trước khi tải
4. Tạo URL ký sẵn mới nếu hết hạn

"Invalid pre-signed URL" (400)

Nguyên nhân: Tên tệp có khoảng trắng hoặc URL ký sẵn hết hạn/hỏng

Cách xử lý:

1. Xóa mọi khoảng trắng trong tên tệp trước khi yêu cầu URL
2. Chỉ dùng chữ số, gạch ngang và gạch dưới trong tên tệp
3. Tạo URL ký sẵn mới nếu cần