Hướng dẫn media
Tạo mô hình 3D
Tạo các mô hình 3D có thể tải xuống từ văn bản hoặc hình ảnh
Việc tạo 3D là không đồng bộ (asynchronous). POST /v1/3d/generations tạo ra một tác vụ TokenLab; các phản hồi trạng thái hoàn thành sẽ trả về các tài nguyên mô hình có thể tải xuống như model_url và các URL định dạng cụ thể nếu có.
Các tệp mô hình 3D có thể tải xuống được lưu giữ dưới dạng bản sao tự động trong 30 ngày và các URL của chúng là các URL phương tiện kết quả của TokenLab. Các bản ghi tác vụ và tài nguyên được lưu riêng biệt tuân theo vòng đời riêng của chúng. Xem Lưu giữ dữ liệu.
Chọn loại đầu vào
| Đầu vào | Bắt buộc | Các trường tùy chọn | Ghi chú |
|---|---|---|---|
| Text-to-3D | model, prompt | format, quality, style, seed | Tốt nhất để tạo tài nguyên mới từ mô tả |
| Image-to-3D | model, image_url hoặc image; cũng cần prompt khi mô hình yêu cầu | format, quality, style, seed | Chỉ sử dụng khi mô hình được chọn hỗ trợ đầu vào hình ảnh |
operation là tùy chọn và có giá trị là text-to-3d hoặc image-to-3d. Nếu bạn bỏ qua, TokenLab sẽ sử dụng image-to-3d khi bạn gửi image hoặc image_url, và text-to-3d trong các trường hợp khác. Nếu bạn gửi tham số này, nó phải khớp với các đầu vào. Một mô hình có text-to-3d chấp nhận các prompt; một mô hình có image-to-3d chấp nhận đầu vào hình ảnh.
curl "https://api.tokenlab.sh/v1/models?recommended_for=3d" \
-H "Authorization: Bearer sk-your-api-key"Đừng mặc định rằng mọi mô hình 3D đều hỗ trợ cả hai loại đầu vào hoặc mọi định dạng đầu ra. Hãy kiểm tra chi tiết mô hình đã chọn trước khi gửi image, image_url, format, quality, style, hoặc seed.
Tạo tác vụ 3D
curl https://api.tokenlab.sh/v1/3d/generations \
-H "Authorization: Bearer sk-your-api-key" \
-H "Content-Type: application/json" \
-d '{
"model": "tripo-h3.1",
"prompt": "A stylized low-poly robot mascot with clean topology"
}'Đối với image-to-3D, hãy sử dụng URL https khi nguồn có thể được truy cập từ internet. Chỉ sử dụng image dạng base64 nội dòng trên mô hình có chi tiết liệt kê image; một số mô hình chỉ chấp nhận image_url.
Các định dạng đầu ra
glbhoạt động tốt cho các bản xem trước trên web.fbxvàobjhữu ích cho các quy trình DCC khi mô hình được chọn hỗ trợ chúng.usdzhữu ích cho các quy trình làm việc AR của Apple khi được mô hình cung cấp.- Các giá trị
qualitycao hơn có thể làm tăng thời gian chờ và chi phí. Hãy hiển thị lựa chọn đó cho người dùng. seedchỉ ảnh hưởng đến khả năng lặp lại trên các mô hình hỗ trợ nó.
Nhận mô hình đã hoàn thành
Gọi GET /v1/tasks/{id} với id hoặc task_id được trả về.
curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
-H "Authorization: Bearer sk-your-api-key"Các tác vụ hoàn thành sẽ trả về model_url và có thể bao gồm glb_url, fbx_url, obj_url, hoặc usdz_url. Hãy tải xuống hoặc lưu vào bộ nhớ đệm tài nguyên đã chọn trong sản phẩm của riêng bạn nếu người dùng cần truy cập lại, lịch sử phiên bản hoặc các tệp tải xuống lâu dài.
Giữ cho kết quả luôn khả dụng
- Lưu trữ
task_id,poll_url, model, định dạng đã yêu cầu và ID bản ghi tài nguyên của riêng bạn. - Tiếp tục thăm dò (polling) sau khi làm mới trang thay vì tạo tác vụ trùng lặp.
- Xác thực kích thước và khả năng truy cập của hình ảnh nguồn trước khi tạo tác vụ.
- Giữ các URL tài nguyên đã tạo khỏi các trang công khai trừ khi người dùng có quyền truy cập vào tài nguyên đó.
- Ghi lại
billing_transaction_idkhi có mặt để đối soát sau này.
Các lỗi thường gặp
| Triệu chứng | Nguyên nhân có thể | Khắc phục |
|---|---|---|
| Phản hồi tạo không có URL tài nguyên | Việc tạo 3D là không đồng bộ | Thăm dò cho đến khi đạt trạng thái cuối cùng |
| Thiếu định dạng yêu cầu | Mô hình không trả về định dạng đó | Quay lại sử dụng model_url hoặc chọn mô hình hỗ trợ định dạng đó |
| Image-to-3D bị từ chối | Mô hình được chọn chỉ hỗ trợ văn bản hoặc URL hình ảnh không thể truy cập | Kiểm tra chi tiết mô hình và xác thực URL |
| Tài nguyên trùng lặp | Đường dẫn thử lại đã tạo lại tác vụ sau khi hết thời gian chờ | Lưu trữ định danh tác vụ trước khi thử lại |
Tài liệu tham khảo API
| Chủ đề | Tham chiếu |
|---|---|
| Tạo 3D | Tạo 3D |
| Nhận trạng thái 3D | Nhận trạng thái 3D |
| Nhận trạng thái tác vụ | Nhận trạng thái tác vụ |
| Liệt kê các mô hình | Liệt kê các mô hình |
| Thanh toán & Giá cả | Thanh toán & Giá cả |