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, nhiều phần, nhập từ URL và tạo tài nguyên.

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.

Điền content_type là loại thật của tệp (ví dụ image/png). Loại không phải định dạng ảnh, video hoặc âm thanh sẽ được lưu là application/octet-stream; khi nhập kho, nền tảng nhận diện định dạng thật theo phần đầu tệp, không theo phần mở rộng hay loại khai báo.

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.

Tạo tài nguyên

Trong POST /v1/assets, name là bắt buộc (tối đa 200 ký tự), group_id là tùy chọn. trust_class khai báo loại tài nguyên, mặc định normal; nhân vật ảo và ảnh người thật xem Loại tài nguyên và xác minh người thật. Không thể đổi loại tài nguyên sau khi tạo.

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 và thời lượng
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 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://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://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://api.aitoken.tools/v1/assets \
  -H "Authorization: Bearer $AITOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"upload_id":"upl_xxx","name":"hero"}'