Captions

Lưu ý: Vào ngày 13 tháng 3 năm 2024, YouTube đã thông báo rằng họ sẽ ngừng sử dụng thông số sync cho các điểm cuối API captions.insertcaptions.update. Tính năng tự động đồng bộ hoá phụ đề vẫn có trong YouTube Creator Studio. Hãy xem nhật ký sửa đổi API để biết thêm thông tin chi tiết.

Tài nguyên caption đại diện cho một bản chú thích trên YouTube. Một bản phụ đề được liên kết với đúng một video trên YouTube.

Phương thức

API này hỗ trợ các phương thức sau cho tài nguyên captions:

list
Truy xuất danh sách các bản phụ đề được liên kết với một video cụ thể. Xin lưu ý rằng phản hồi API không chứa phụ đề thực tế và phương thức captions.download cung cấp khả năng truy xuất kênh phụ đề. Thử ngay.
chèn
Tải bản phụ đề lên. Thử ngay.
update
Cập nhật bản phụ đề. Khi cập nhật một bản phụ đề, bạn có thể thay đổi trạng thái bản nháp của bản phụ đề, tải tệp phụ đề mới lên cho bản phụ đề đó hoặc làm cả hai việc. Thử ngay.
tải xuống
Tải bản phụ đề xuống. Phiên bản phụ đề được trả về ở định dạng ban đầu, trừ phi yêu cầu chỉ định giá trị cho tham số tfmt và ở ngôn ngữ ban đầu, trừ phi yêu cầu chỉ định giá trị cho tham số tlang. Thử ngay.
xóa
Xoá một bản phụ đề được chỉ định. Thử ngay.

Biểu thị tài nguyên

Cấu trúc JSON sau đây cho thấy định dạng của tài nguyên captions:

{
  "kind": "youtube#caption",
  "etag": etag,
  "id": string,
  "snippet": {
    "videoId": string,
    "lastUpdated": datetime,
    "trackKind": string,
    "language": string,
    "name": string,
    "audioTrackType": string,
    "isCC": boolean,
    "isLarge": boolean,
    "isEasyReader": boolean,
    "isDraft": boolean,
    "isAutoSynced": boolean,
    "status": string,
    "failureReason": string
  }
}

Thuộc tính

Bảng sau đây xác định các thuộc tính xuất hiện trong tài nguyên này:

Thuộc tính
kind string
Xác định loại tài nguyên API. Giá trị sẽ là youtube#caption.
etag etag
Etag của tài nguyên này.
id string
Mã mà YouTube sử dụng để xác định riêng biệt bản phụ đề.
snippet object
Đối tượng snippet chứa thông tin chi tiết cơ bản về chú thích.
snippet.videoId string
Mã mà YouTube sử dụng để xác định riêng biệt video được liên kết với bản phụ đề.
snippet.lastUpdated datetime
Ngày và giờ cập nhật gần đây nhất của bản phụ đề. Giá trị được chỉ định ở định dạng ISO 8601.
snippet.trackKind string
Loại của bản lồng tiếng.

Các giá trị hợp lệ cho thuộc tính này là:
  • ASR – Một bản phụ đề được tạo bằng công nghệ nhận dạng giọng nói tự động.
  • forced – Một bản phụ đề phát khi không có bản nhạc nào khác được chọn trong trình phát. Ví dụ: video có cảnh người ngoài hành tinh nói bằng ngôn ngữ ngoài hành tinh có thể có một kênh phụ đề bắt buộc chỉ hiển thị phụ đề cho ngôn ngữ ngoài hành tinh đó.
  • standard – Bản phụ đề thông thường. Đây là giá trị mặc định.
snippet.language string
Ngôn ngữ của bản phụ đề. Giá trị thuộc tính là thẻ ngôn ngữ BCP-47.
snippet.name string
Tên của bản lồng tiếng. Người dùng sẽ nhìn thấy tên này dưới dạng một tuỳ chọn trong khi phát. Độ dài tối đa của tên được hỗ trợ là 150 ký tự.
snippet.audioTrackType string
Loại kênh âm thanh liên kết với kênh phụ đề.

Các giá trị hợp lệ cho thuộc tính này là:
  • commentary – Bản phụ đề tương ứng với một bản âm thanh thay thế có bình luận, chẳng hạn như bình luận của thư mục.
  • descriptive – Bản âm thanh mô tả tương ứng với một bản âm thanh thay thế có thêm âm thanh mô tả.
  • primary – Bản phụ đề tương ứng với bản âm thanh chính của video, tức là bản âm thanh thường được liên kết với video.
  • unknown – Đây là giá trị mặc định.
snippet.isCC boolean
Cho biết liệu bản nhạc có chứa phụ đề dành cho người khiếm thính hay không. Giá trị mặc định là false.
snippet.isLarge boolean
Cho biết liệu bản lồng tiếng có sử dụng văn bản lớn cho người khiếm thị hay không. Giá trị mặc định là false.
snippet.isEasyReader boolean
Cho biết liệu bản phụ đề có được định dạng cho "người đọc dễ hiểu" hay không, nghĩa là bản phụ đề ở cấp độ lớp 3 dành cho người học ngôn ngữ. Giá trị mặc định là false.
snippet.isDraft boolean
Cho biết liệu bản dịch phụ đề có phải là bản nháp hay không. Nếu giá trị là true, thì bản nhạc sẽ không hiển thị công khai. Giá trị mặc định là false.
snippet.isAutoSynced boolean
Cho biết YouTube có đồng bộ hoá bản phụ đề với bản âm thanh trong video hay không. Giá trị này sẽ là true nếu bạn yêu cầu đồng bộ hoá rõ ràng khi tải bản phụ đề lên. Ví dụ: khi gọi phương thức captions.insert hoặc captions.update, bạn có thể đặt tham số sync thành true để hướng dẫn YouTube đồng bộ hoá bản nhạc đã tải lên với video. Nếu giá trị là false, YouTube sẽ sử dụng mã thời gian trong kênh phụ đề đã tải lên để xác định thời điểm hiển thị phụ đề.
snippet.status string
Trạng thái của bản lồng tiếng.

Các giá trị hợp lệ cho thuộc tính này là:
  • failed
  • serving
  • syncing
snippet.failureReason string
Lý do YouTube không xử lý được bản phụ đề. Thuộc tính này chỉ xuất hiện nếu giá trị của thuộc tính statefailed.

Các giá trị hợp lệ cho thuộc tính này là:
  • processingFailed – YouTube không xử lý được bản phụ đề đã tải lên.
  • unknownFormat – Không nhận dạng được định dạng của bản phụ đề.
  • unsupportedFormat – Định dạng của bản phụ đề không được hỗ trợ.