TokenLab

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àoBắt buộcCác trường tùy chọnGhi chú
Text-to-3Dmodel, promptformat, quality, style, seedTốt nhất để tạo tài nguyên mới từ mô tả
Image-to-3Dmodel, image_url hoặc image; cũng cần prompt khi mô hình yêu cầuformat, quality, style, seedChỉ 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

  • glb hoạt động tốt cho các bản xem trước trên web.
  • fbx và obj hữu ích cho các quy trình DCC khi mô hình được chọn hỗ trợ chúng.
  • usdz hữ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ị quality cao 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.
  • seed chỉ ả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_id khi có mặt để đối soát sau này.

Các lỗi thường gặp

Triệu chứngNguyên nhân có thểKhắc phục
Phản hồi tạo không có URL tài nguyênViệ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ầuMô 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ốiMô hình được chọn chỉ hỗ trợ văn bản hoặc URL hình ảnh không thể truy cậpKiể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 3DTạo 3D
Nhận trạng thái 3DNhậ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ìnhLiệt kê các mô hình
Thanh toán & Giá cảThanh toán & Giá cả

Trên trang này