Đã xem lại 2026-11-10 · Phiên bản API 2026-11-09 · Đọc Markdown
Tải lên và lưu giữ media
Dữ liệu media đi trực tiếp đến nơi lưu trữ đối tượng riêng tư tạm thời. REST và MCP
trả về hướng dẫn tải lên; chúng không nhận nội dung tệp nhị phân trong JSON của công cụ.
Phải cấu hình lưu trữ trên bản triển khai, nếu không việc tạo lần tải lên sẽ trả về
provider_unavailable.
Vòng đời tải lên
- Gọi
POST /api/v1/media/upload-intentsvới tên tệp, MIME khai báo và số byte. LưuassetIdvàsessionIdđược trả về như hai định danh riêng biệt. - Kiểm tra
method. Vớipresigned_put, tải toàn bộ tệp lênuploadUrlbằng các header được trả về. Vớimultipart_initiated, chia bằngpartSizeBytes, tải từng phần được đánh số lên URL của nó và giữ lại biên nhận ETag. Không bao giờ thêm bearer key của AiVideoEditor vào các yêu cầu lưu trữ. - Hoàn tất tại
POST /api/v1/media/{assetId}/finalizevớisessionIdvà, đối với multipart,multipart.partschứa từngpartNumbervàetag. - Dùng ID tài sản đã hoàn tất trong
mediaIdscủa bản nháp. Chỉ riêng intent tải lên chưa làm cho tài sản có thể đăng.
Máy chủ quan sát các byte và định dạng thực tế trên bản sao cuối bất biến. Kích thước/MIME khai báo là đầu vào đặt chỗ, không phải bằng chứng tệp hợp lệ. Các nhóm định dạng cơ sở được hỗ trợ là JPEG, PNG và MP4; từng điểm đến có thể áp giới hạn nghiêm ngặt hơn. Kích thước tệp tối đa hiện tại là 500 MiB (524,288,000 byte). Tệp từ 50 MiB trở lên dùng multipart, thường với các phần 16 MiB. Luôn tuân theo kích thước, URL và thời hạn hết hạn được trả về thay vì suy ra chúng từ các giá trị mặc định này.
{
"sessionId": "<session UUID from upload-intents>",
"multipart": {
"parts": [
{ "partNumber": 1, "etag": "<ETag returned by storage>" }
]
}
}
Đây là minh họa cấu trúc multipart; hãy đưa vào mọi phần thực tế. Hoàn tất
single-PUT chỉ gửi sessionId. Cho mỗi thao tác thay đổi API mới một
Idempotency-Key riêng; giữ lại nó để thử lại giống hệt một cách an toàn.
Tiếp tục hoặc từ bỏ
URL đã ký đã hết hạn không phải là địa chỉ media vĩnh viễn. Yêu cầu URL phần multipart mới
bằng POST /media/{id}/upload-parts với fromPart và toPart (một khoảng bao gồm tối đa 64 phần). Xem tài liệu tham khảo API để biết cấu trúc
yêu cầu có giới hạn. Không tải lại các phần đã hoàn thành một cách không cần thiết hay hoàn tất
việc ghép multipart trực tiếp qua lưu trữ: việc hoàn tất do máy chủ kiểm soát.
Dùng POST /media/{id}/abandon khi hủy một lần tải chưa hoàn thành. Thao tác này
giải phóng phần đặt chỗ của nó qua quy trình dọn dẹp dùng chung. Hết hạn phiên hoặc trạng thái
multipart đã tiêu thụ có thể đòi hỏi một intent mới; không đoán các khóa đối tượng lưu trữ.
Lưu giữ tạm thời
GET /media/{id} trả về trạng thái và thông tin deleteAfter động, không phải
URL công khai vĩnh viễn. Các sử dụng đã lên lịch và đang thực hiện bảo vệ media trong suốt
quá trình công việc. Chính sách mặc định giữ media bản nháp không dùng 14 ngày, media đã kết thúc
72 giờ, và công việc thất bại hoặc mơ hồ 7 ngày sau lần thử tương ứng. Việc lưu giữ
thực tế phụ thuộc vào mọi tham chiếu còn lại; deleteAfter có thể là null.
Giữ các bản gốc. Nếu media đã hết hạn hoặc đang bị xóa, hãy tải lên lại trước khi đăng.