API chuyển audio thành văn bản: gửi file đến 95 MB
Đặt dữ liệu file trong phần multipart tên file. Bạn có thể thêm language, diarize, source và webhook_url. Xem request tải file một lần, hoặc dùng webhook để nhận thông báo khi xử lý xong.
Nếu server đã có một file nhỏ trên ổ đĩa, multipart là cách đơn giản để bắt đầu. Hãy gửi byte thật của file, không gửi chuỗi đường dẫn trong JSON. Để HTTP client tự đặt multipart boundary. File rỗng hay sai phần mở rộng cần sửa đầu vào, không nên gửi lại liên tục.
Chọn cách tải theo dung lượng, rồi kiểm tra thời lượng riêng. File nén dưới 95 MB vẫn có thể dài quá 5 giờ. Ngược lại, video độ phân giải cao có thể vượt giới hạn multipart dù chỉ có một đoạn thoại ngắn.
curl -X POST "https://api.transcript1.com/v1/transcriptions?wait=60" \
-H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
-F [email protected] \
-F language=autoTải file lớn mà không phải làm lại khi mất kết nối
Gửi tên và dung lượng để tạo upload. API trả danh sách chunk cùng X-Upload-Token dành riêng cho lần tải này. Làm theo quy trình tải từng phần để gửi đủ file.
Mỗi chunk có index, vị trí byte bắt đầu và dung lượng. Đọc đúng vùng byte API yêu cầu; chunk cuối có thể ngắn hơn. Dùng X-Upload-Token cho các request PUT gửi dữ liệu. Token có hiệu lực 1 giờ và không thay thế khóa API của bạn.
Dùng một Idempotency-Key cố định cho request tạo upload cần gửi lại. Khi token hết hạn, gửi lại cùng key và cùng tham số để nhận token mới cho upload đang có. Tạo upload mới sau mỗi lần ngắt sẽ để lại nhiều job chờ và khó theo dõi tiến độ.
curl -X POST "https://api.transcript1.com/v1/transcriptions" \
-H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
-H "Idempotency-Key: interview-2026-10-13" \
-H "Content-Type: application/json" \
-d '{"upload":{"filename":"interview.m4a","size":48210334,"mime_type":"audio/mp4"}}'Gửi chunk còn thiếu rồi xác nhận hoàn tất
PUT từng chunk đến URL của nó với upload token, sau đó gọi endpoint hoàn tất. transcript1 kiểm tra đủ chunk rồi mới đưa file vào hàng đợi xử lý. Tài liệu upload có endpoint xem tiến độ và hoàn tất.
Khi tiếp tục upload, gọi GET /v1/transcriptions/:id/upload và đối chiếu received_chunks với kế hoạch ban đầu. Chỉ gửi phần còn thiếu. Gửi lại một chunk sẽ ghi đè chunk đó, nhưng body vẫn phải đúng dung lượng đã quy định.
Lỗi 401 có thể là token hết hạn, không phải file bị hỏng. Lỗi 409 upload_incomplete cho biết index còn thiếu để bạn gửi bù. Khi job đã vào hàng đợi, đọc trạng thái transcription hoặc chờ webhook. Giao diện nên phân biệt tiến độ tải file với tiến độ xử lý âm thanh.
curl -X PUT "https://api.transcript1.com/v1/transcriptions/tr_8fK2Lm0PqRsTuVwXyZaBcD/upload/chunks/0" \
-H "X-Upload-Token: t1u_..." \
-H "Content-Type: application/octet-stream" \
--data-binary @chunk-0.bin
curl -X POST "https://api.transcript1.com/v1/transcriptions/tr_8fK2Lm0PqRsTuVwXyZaBcD/upload/complete" \
-H "Authorization: Bearer $TRANSCRIPT1_API_KEY"Tải xong chưa có nghĩa là đã có transcript
awaiting_upload nghĩa là job còn chờ dữ liệu, chưa xử lý âm thanh. Chỉ sau khi hoàn tất upload thành công, file mới vào hàng đợi. Nếu mất kết nối ngay sau bước hoàn tất, đọc trạng thái job trước khi quyết định gửi lại.
Mỗi team được có tối đa 20 upload chưa hoàn tất. Sau 24 giờ, upload còn dở bị hủy và các chunk bị xóa. Với job đã kết thúc, file được xóa sau 24 giờ nữa; transcript vẫn lưu cho đến khi bạn xóa. Nếu sản phẩm cần phát lại âm thanh về sau, bạn phải tự giữ file gốc.
Upload chỉ là bước đầu. Nếu làm công cụ cho người dùng, xem cách chuẩn bị và kiểm tra file ghi âm. Với bản ghi phỏng vấn, hướng dẫn gỡ băng giúp bạn đối chiếu người tham gia và giữ nguồn cho các trích dẫn.