Tài liệu API · Tài nguyên

Tải lên tài nguyên

Tải lên một lần, tải lên nhiều phần và nhập từ URL.

Trước tiên hãy tải tài nguyên lên nền tảng, sau đó tham chiếu qua asset_id trong inputs của tác vụ; cùng một tài nguyên có thể dùng lại trong nhiều tác vụ. Mỗi tệp tối đa 2 GiB; phiên tải lên có hiệu lực trong 1 giờ (xem expires_at được trả về).

Tải lên một lần

Với tệp không quá 100 MB, POST /v1/uploads trả về method: "single" cùng upload_url đã ký sẵn. Dùng PUT để tải nội dung tệp lên kèm các headers được trả về, sau đó gọi complete.

Tải lên nhiều phần

Tệp lớn hơn sẽ nhận method: "multipart" kèm part_size (thường là 16.0 MB) và part_count:

Gọi POST /v1/uploads/{id}/parts với { "part_numbers": [1, 2, …] } (tối đa 100 phần mỗi lần), API trả về { "parts": [{ "part_number": 1, "url": "…" }] }.
Chia tệp theo thứ tự, PUT từng phần và ghi lại ETag trong header phản hồi.
Gọi complete với { "parts": [{ "part_number": 1, "etag": "…" }] }.

Nhập từ URL

Gọi POST /v1/assets với source_url thay cho upload_id, nền tảng sẽ tải tệp từ địa chỉ đó: chỉ hỗ trợ địa chỉ công khai http / https, tệp không quá 250 MB và phải tải xong trong 60 giây. Tài nguyên chỉ được lưu lâu dài khi tải về và lưu thành công; nếu tải về thất bại, trạng thái chuyển thành failed và status_reason cho biết nguyên nhân.

Trạng thái tài nguyên

status	Ý nghĩa
Đang tải lên	Nhập từ URL: đang tải tệp về
Đang xử lý	Nền tảng đang phân tích định dạng, kích thước, thời lượng và kiểm duyệt nội dung
Sẵn sàng	Có thể dùng trong tác vụ
Cần ủy quyền	Tài nguyên được khai báo là người thật (real_person), cần hoàn tất ủy quyền người thật
Thất bại	Sai định dạng, tải về thất bại, không qua kiểm duyệt nội dung hoặc giá trị kiểm tra không khớp, xem status_reason
Đang xóa	Đã yêu cầu xóa; nếu vẫn được tác vụ đang chạy tham chiếu, sẽ dọn sau khi tác vụ kết thúc

Gửi tác vụ trước khi tài nguyên chuyển sang available sẽ nhận 422 asset_not_ready (có thể thử lại).

# 1. Yêu cầu tải lên
curl https://cn-api.aitoken.tools/v1/uploads \
  -H "Authorization: Bearer $AITOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename":"hero.png","content_type":"image/png","size_bytes":1832211}'

# 2. PUT tệp lên upload_url được trả về (kèm headers được trả về)
curl -X PUT "$UPLOAD_URL" -H "Content-Type: image/png" --data-binary @hero.png

# 3. Hoàn tất tải lên
curl -X POST https://cn-api.aitoken.tools/v1/uploads/upl_xxx/complete \
  -H "Authorization: Bearer $AITOKEN_API_KEY" \
  -H "Content-Type: application/json" -d '{}'

# 4. Tạo tư liệu
curl https://cn-api.aitoken.tools/v1/assets \
  -H "Authorization: Bearer $AITOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"upload_id":"upl_xxx","name":"hero"}'