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.insert và captions.update. Tính năng tự động đồng bộ hoá phụ đề vẫn hoạt động trong YouTube Creator Studio. Xem Nhật ký sửa đổi API cho chi tiết hơn.

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

Phương thức

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

list
Truy xuất danh sách phụ đề có liên kết với một video cụ thể. Lưu ý rằng phản hồi của API không chứa phụ đề thực tế và phương thức captions.download cho phép truy xuất phụ đề. Thử ngay.
chèn
Tải phụ đề lên.
cập nhật
Cập nhật 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.
xóa
Xoá một bản phụ đề được chỉ định. Thử ngay.
tải xuống
Tải bản phụ đề xuống. Phụ đề sẽ được trả về ở định dạng gốc trừ phi yêu cầu chỉ định một giá trị cho tham số tfmt và bằng ngôn ngữ gốc, trừ phi yêu cầu chỉ định một giá trị cho tham số tlang.

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ã nhận dạng mà YouTube sử dụng để xác định riêng biệt phụ đề gốc.
snippet object
Đối tượng snippet chứa các thông tin 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 phụ đề gần đây nhất. 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ụ đề sẽ phát khi không có bản phụ đề 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 – Phụ đề thông thường. Đây là giá trị mặc định.
snippet.language string
Ngôn ngữ của phụ đề. Giá trị thuộc tính là thẻ ngôn ngữ BCP-47.
snippet.name string
Tên của phụ đề. Tên này nhằm hiển thị cho người dùng dưới dạng một lựa chọn trong khi phát lại. Độ dài tên tối đa được hỗ trợ là 150 ký tự.
snippet.audioTrackType string
Loại bản âm thanh được liên kết với phụ đề.

Các giá trị hợp lệ cho thuộc tính này là:
  • commentary – Phụ đề tương ứng với một bản âm thanh thay thế bao gồm lời bình luận, chẳng hạn như bình luận trong danh bạ.
  • descriptive – Phụ đề tương ứng với bản âm thanh thay thế có âm thanh mô tả bổ sung.
  • 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 phụ đề có sử dụng chữ 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 phụ đề có được định dạng cho "dễ đọc" hay không nghĩa là bài học ở cấp độ ba đối với người học ngôn ngữ. Giá trị mặc định là false.
snippet.isDraft boolean
Cho biết 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 liệu YouTube có đồng bộ hoá phụ đề với bản âm thanh trong video hay không. Giá trị sẽ là true nếu yêu cầu đồng bộ hoá được yêu cầu rõ ràng khi tải 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 bản 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 phụ đề.

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

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ụ đề được tải lên.
  • unknownFormat – Không nhận dạng được định dạng của phụ đề.
  • unsupportedFormat – Định dạng của phụ đề không được hỗ trợ.