Tải file lên

File audio và video tải lên luôn dùng AI để chuyển giọng nói thành văn bản. Chọn source là auto hoặc stt. Nếu cần đặt ngôn ngữ hay nhận diện người nói, xem cách dùng language và diarize trong Link video và tùy chọn.

Định dạng và dung lượng file

Kiểm tra đuôi file trước khi gửi: mp3, wav, m4a, flac, ogg, opus, mp4, mov, webm hoặc mkv. Đuôi khác sẽ nhận 422 unsupported_media. File cũng phải có track audio; thiếu track này, job báo unsupported_media.

Nếu file quá lớn, API trả 413 media_too_large. Trường max_bytes trong lỗi cho biết dung lượng tối đa bạn được gửi.

Gửi bằng một request

Gọi POST /v1/transcriptions với body multipart/form-data cho file tối đa 95 MB. Đặt phần chứa file là file. Bạn có thể thêm các trường form language, diarize (true hoặc false), source (auto hoặc stt) và webhook_url.

curl -X POST "https://api.transcript1.com/v1/transcriptions?wait=60" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
  -F [email protected] \
  -F language=en \
  -F diarize=true

API trả object transcription có source.platform là upload. Giống với link video, mã HTTP là 202 nếu job đang xử lý và 200 nếu đã kết thúc. Gửi file rỗng sẽ nhận 422 invalid_request.

Chia file thành các chunk

Với file lớn, gửi từng chunk riêng biệt. Cách này cho phép tải tiếp phần còn thiếu nếu kết nối bị ngắt. Quy trình có bốn bước.

1. Tạo phiên tải lên

Gửi JSON chứa tên và dung lượng file; mime_type có thể bỏ qua. Kèm header Idempotency-Key để gửi lại request tạo phiên mà không tạo thêm job:

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"},"language":"auto","diarize":true}'

API trả 201, trạng thái awaiting_upload và object upload chứa thông tin để gửi chunk:

{
  "id": "tr_8fK2Lm0PqRsTuVwXyZaBcD",
  "object": "transcription",
  "status": "awaiting_upload",
  "upload": {
    "chunk_url_template": "https://api.transcript1.com/v1/transcriptions/tr_8fK2Lm0PqRsTuVwXyZaBcD/upload/chunks/{index}",
    "headers": { "X-Upload-Token": "t1u_..." },
    "expires_at": "2026-10-13T10:30:00.000Z",
    "chunks": [
      { "index": 0, "offset": 0, "size": 8388608 },
      { "index": 1, "offset": 8388608, "size": 8388608 }
    ]
  }
}

Server quyết định cách chia file và trả danh sách chunks. Mỗi chunk khoảng 8 MiB (8.388.608 byte); ví dụ trên chỉ hiển thị một phần danh sách. Giữ kín X-Upload-Token: token chỉ dùng cho phiên tải lên này và hết hạn sau 1 giờ, tại expires_at.

2. Gửi từng chunk

Với từng chunk, thay {index} trong chunk_url_template bằng giá trị index, rồi gửi PUT. Đọc đúng size byte từ vị trí offset của file và dùng chúng làm body application/octet-stream. Không gửi thừa hoặc thiếu byte so với danh sách server trả về. Request này xác thực bằng X-Upload-Token, không cần Authorization.

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

Gửi thành công sẽ nhận { "object": "upload_chunk", "index": 0, "size": 8388608 }. Bạn có thể gửi lại để ghi đè chunk đó. Sai dung lượng hoặc dùng index ngoài danh sách sẽ nhận 422 invalid_request. Thiếu token hay token hết hạn sẽ nhận 401 unauthorized.

3. Tải tiếp sau khi mất kết nối

Gọi GET /v1/transcriptions/:id/upload để kiểm tra server đã nhận những chunk nào:

{
  "object": "upload",
  "status": "awaiting_upload",
  "total_bytes": 48210334,
  "uploaded_bytes": 16777216,
  "received_chunks": [0, 1],
  "chunks": [ { "index": 0, "offset": 0, "size": 8388608 } ],
  "expires_at": "2026-10-13T10:30:00.000Z"
}

Đối chiếu received_chunks và chỉ gửi những chunk chưa có trong danh sách. Nếu token hết hạn, gửi lại request ở bước 1, giữ nguyên Idempotency-Key và các tham số. API trả lại cùng job nhưng cấp token tải lên mới.

4. Ghép file và bắt đầu xử lý

curl -X POST "https://api.transcript1.com/v1/transcriptions/tr_8fK2Lm0PqRsTuVwXyZaBcD/upload/complete" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY"

Gọi POST /v1/transcriptions/:id/upload/complete sau khi gửi đủ chunk. Server kiểm tra số chunk và dung lượng từng chunk, ghép file rồi đưa job vào hàng đợi. Response là 202 kèm object transcription.

Nếu nhận 409 upload_incomplete, đọc missing_chunks để biết các index cần gửi lại. Nếu phiên tải lên đã hoàn tất hoặc đã hủy, API trả 409 invalid_state. Khi job đã vào hàng đợi, dùng GET /v1/transcriptions/:id?wait=60 để chờ hoặc nhận thông báo qua webhook.

Toàn bộ quy trình bằng Python

import os
import requests
 
API = "https://api.transcript1.com"
auth = {"Authorization": f"Bearer {os.environ['TRANSCRIPT1_API_KEY']}"}
path = "interview.m4a"
 
created = requests.post(
    f"{API}/v1/transcriptions",
    headers={**auth, "Idempotency-Key": "interview-2026-10-13"},
    json={"upload": {"filename": os.path.basename(path), "size": os.path.getsize(path)}},
)
created.raise_for_status()
transcription = created.json()
upload = transcription["upload"]
 
with open(path, "rb") as file:
    for chunk in upload["chunks"]:
        file.seek(chunk["offset"])
        url = upload["chunk_url_template"].replace("{index}", str(chunk["index"]))
        response = requests.put(
            url,
            data=file.read(chunk["size"]),
            headers={**upload["headers"], "Content-Type": "application/octet-stream"},
        )
        response.raise_for_status()
 
done = requests.post(f"{API}/v1/transcriptions/{transcription['id']}/upload/complete", headers=auth)
done.raise_for_status()
print(done.json()["status"])

Giới hạn và thời hạn lưu file

• Mỗi team có tối đa 20 phiên tải lên ở trạng thái awaiting_upload cùng lúc. Tạo thêm sẽ nhận 429 too_many_active_jobs kèm Retry-After.
• Bạn có 24 giờ từ khi tạo phiên để tải xong. Quá thời hạn, hệ thống hủy phiên và xóa các chunk.
• Hệ thống xóa file audio hoặc video sau 24 giờ kể từ khi job chuyển sang completed, failed hoặc canceled. Transcript vẫn còn cho đến khi bạn gọi DELETE /v1/transcriptions/:id.
• Khi biết thời lượng file, hệ thống tính số phút sử dụng và làm tròn lên. Nếu job thất bại hoặc bạn hủy, bạn không mất phí. Xem Thanh toán và giới hạn.