Hướng dẫn sử dụng Image to 3D Model API: Hướng dẫn đầy đủ 2026

API Chuyển Ảnh Thành Mô Hình 3D biến một bức ảnh đơn lẻ thành mô hình 3D sẵn sàng sản xuất trong vài giây—không cần mô hình hóa thủ công. Việc tạo mô hình thủ công từng tài sản rất chậm và tốn kém, và đối với các studio game, ứng dụng AR và nhóm thương mại điện tử, nó nhanh chóng trở thành nút thắt cổ chai làm trì hoãn việc ra mắt. API chuyển ảnh thành mô hình 3D của Meshy loại bỏ sự cản trở đó: gửi một hình ảnh, chuyển đổi nó thành mô hình 3D trong vài giây và tải xuống một lưới được kết cấu đầy đủ ở các định dạng như GLB, FBX và OBJ. Hướng dẫn này sẽ hướng dẫn bạn toàn bộ quy trình—từ tạo khóa API đến tải xuống mô hình đầu tiên—với mã sao chép-dán mà bạn có thể chạy trong vài phút.

API Chuyển Ảnh Thành Mô Hình 3D là gì?

Về cốt lõi, API Chuyển Ảnh Thành Mô Hình 3D là một điểm cuối REST được hỗ trợ bởi AI chuyển ảnh thành mô hình 3D của Meshy. Bạn gửi một hình ảnh duy nhất (JPG, JPEG hoặc PNG) dưới dạng URL công khai hoặc chuỗi base64, và API trả về một mô hình 3D có kết cấu—bao gồm hình học và kết cấu màu cơ bản—ở các định dạng tiêu chuẩn như GLB, FBX, OBJ, USDZ, STL và 3MF. Các tiện ích bổ sung tùy chọn bao gồm bản đồ PBR, kết cấu lên đến 4K và hình thu nhỏ xem trước đa góc.

Được hỗ trợ bởi mô hình Meshy 6 mới nhất của chúng tôi, API cho phép bạn cấu hình cấu trúc liên kết và số lượng đa giác, thiết lập chế độ tư thế và hướng dẫn tạo kết cấu bằng lời nhắc văn bản hoặc hình ảnh tham chiếu—lý tưởng để tạo tài sản cho game, AR/VR, in 3D và trực quan hóa sản phẩm.

Bạn cần gì để sử dụng API Chuyển Ảnh Thành Mô Hình 3D?

Bạn không cần nhiều để làm theo hướng dẫn này. Hãy đảm bảo bạn có:

• Một tài khoản Meshy — đăng ký miễn phí nếu bạn chưa có. Bạn sẽ tạo khóa API từ bảng điều khiển trong Bước 1.

• Một khóa API — được sử dụng để xác thực mọi yêu cầu. Chúng tôi sẽ hướng dẫn cách tạo một khóa và bạn có thể sử dụng khóa chế độ kiểm tra miễn phí để làm theo mà không tốn tín dụng.

• Một hình ảnh đầu vào — một tệp .jpg, .jpeg hoặc .png rõ ràng được lưu trữ tại một URL có thể truy cập công khai (hoặc được mã hóa dưới dạng base64). Nền sạch và đối tượng có thể nhìn thấy rõ ràng sẽ cho kết quả tốt nhất.

• Một cách để thực hiện yêu cầu HTTP — curl (được sử dụng trong các ví dụ bên dưới), Postman hoặc bất kỳ thư viện HTTP nào trong ngôn ngữ bạn chọn. Sự quen thuộc cơ bản với REST API và JSON rất hữu ích nhưng không bắt buộc.

Vậy là xong—không cần kinh nghiệm tạo mô hình 3D. Hãy bắt đầu.

Cách Chuyển Đổi Ảnh Thành Mô Hình 3D với API (Hướng dẫn Từng Bước)

Bước 1: Thiết Lập Cài Đặt API của Bạn

Mọi thứ bạn cần để bắt đầu xây dựng đều có trên trang cài đặt API. Đây là trung tâm điều khiển của bạn cho API Meshy và nó có ba phần chính:

• Khóa API — tạo và quản lý các khóa xác thực yêu cầu của bạn.

• Webhook — tự động nhận thông báo khi tác vụ của bạn hoàn thành.

• Sử dụng — theo dõi số dư tín dụng còn lại và mức tiêu thụ API của bạn trong thời gian thực.

Hãy cùng xem qua từng phần.

Lấy Khóa API của Bạn

Trước khi thực hiện bất kỳ yêu cầu nào, bạn cần một khóa API để xác thực an toàn. Trên trang cài đặt API, nhấp vào Tạo Khóa API. Mọi khóa đều tuân theo định dạng msy-<chuỗi-ngẫu-nhiên>.

Mẹo: Sau khi được tạo, hãy lưu trữ khóa API của bạn ở nơi an toàn (ví dụ: trình quản lý mật khẩu hoặc biến môi trường). Hãy coi nó như mật khẩu—không bao giờ commit nó vào kiểm soát mã nguồn hoặc để lộ nó trong mã phía máy khách.

Khóa API Chế Độ Kiểm Tra

Trong quá trình phát triển và thử nghiệm, bạn có thể sử dụng khóa API chế độ kiểm tra để khám phá API mà không tiêu tốn tín dụng của bạn:

msy_dummy_api_key_for_test_mode_12345678

Khóa đặc biệt này có các đặc điểm sau:

• Nó có thể được sử dụng để thực hiện yêu cầu đến tất cả các điểm cuối API của Meshy.

• Không tốn tín dụng khi sử dụng khóa này.

• Tất cả các yêu cầu hợp lệ đều trả về cùng một kết quả tác vụ mẫu, bất kể tham số đầu vào.

• Cấu trúc dữ liệu phản hồi khớp chính xác với API sản xuất.

Điều này làm cho nó trở nên hoàn hảo để kiểm tra tích hợp của bạn trước khi chuyển sang khóa API thực của bạn.

Thiết Lập Webhook (Tùy chọn)

Việc tạo mô hình 3D cần có thời gian, vì vậy thay vì liên tục gọi API để kiểm tra xem tác vụ đã hoàn thành chưa, bạn có thể để Meshy thông báo cho bạn ngay khi nó hoàn thành. Đó là mục đích của webhook.

Trong phần Webhook của trang cài đặt, hãy thêm một URL điểm cuối nơi Meshy sẽ gửi thông báo sự kiện. Khi một tác vụ thay đổi trạng thái (ví dụ: khi nó hoàn thành hoặc thất bại), Meshy sẽ gửi một yêu cầu HTTP POST đến URL của bạn với thông tin chi tiết về tác vụ trong tải trọng.

Mẹo: Webhook là phương pháp được khuyến nghị cho sản xuất. Chúng giảm các lệnh gọi API không cần thiết và cho phép ứng dụng của bạn phản ứng với kết quả trong thời gian thực. Đối với các thử nghiệm nhanh, việc gọi vẫn hoạt động tốt. Để kiểm tra mã webhook cục bộ, hãy trỏ nó đến một URL proxy từ một dịch vụ như smee.io.

Dùng Thử Mà Không Cần Mã — API Playground (Tùy chọn)

Đã có Khóa API? Trước khi viết bất kỳ mã nào, bạn có thể chạy một tác vụ Chuyển Ảnh Thành 3D thực tế trực tiếp trong trình duyệt của mình.

Mở meshy.ai/api-playground, chọn Image to 3D từ bảng điều khiển bên trái và điền ba thứ:

1. Authorization — dán Khóa API của bạn (msy-xxxxxxxxxx)

2. Image — tải lên tệp .jpg, .jpeg hoặc .png từ máy tính của bạn

3. Nhấn Send

Playground gửi tác vụ và tự động gọi để lấy kết quả. Khi hoàn tất, bạn sẽ thấy bản xem trước mô hình 3D và các liên kết tải xuống ngay trong trình duyệt — không cần mã.

Mẹo chuyên nghiệp: Bảng yêu cầu/phản hồi thô ở bên phải hiển thị chính xác những gì API gửi và trả về. Bạn có thể sao chép nội dung trực tiếp — lấy task_id từ phản hồi và model_urls khi tác vụ hoàn tất. Bạn sẽ sử dụng cả hai trong các bước tiếp theo.

Bước 2: Gửi Một Tác Vụ Chuyển Ảnh Thành 3D

Với khóa API đã sẵn sàng, hãy bắt đầu một tác vụ bằng một yêu cầu POST duy nhất:

curl -X POST https://api.meshy.ai/openapi/v1/image-to-3d \
  -H "Authorization: Bearer $MESHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://example.com/your-image.png"
  }'

Bạn sẽ nhận lại phản hồi như thế này:

{
  "result": "018a210d-8ba4-705c-b111-1f1776f7f578"
}

Giá trị result đó là task_id của bạn — hãy lưu nó lại. Bạn sẽ cần nó trong bước tiếp theo để kiểm tra tiến độ và lấy mô hình của mình.

Tùy chọn: Để tự động nhận thông báo khi tác vụ hoàn tất, hãy thêm trường webhook_url vào nội dung JSON — ví dụ: "webhook_url": "https://yourapp.com/webhooks/meshy". Xem Bước 3, Tùy chọn B để biết cách nó hoạt động.

Bước 3: Lấy Kết Quả của Bạn

Tác vụ của bạn không hoàn thành ngay lập tức — Meshy xử lý nó trong nền. Bạn có hai cách để lấy kết quả:

Tùy chọn A: Gọi để Kiểm Tra Trạng Thái (Đơn giản nhất)

Gửi một yêu cầu GET mỗi 5 giây cho đến khi status chuyển thành SUCCEEDED:

curl https://api.meshy.ai/openapi/v1/image-to-3d/{task_id} \
  -H "Authorization: Bearer $MESHY_API_KEY"

Phản hồi trông như thế này:

{
  "id": "018a210d-8ba4-705c-b111-1f1776f7f578",
  "status": "SUCCEEDED",
  "progress": 100,
  "model_url": "https://assets.meshy.ai/.../model.glb",
  "model_urls": {
    "glb": "https://assets.meshy.ai/.../model.glb",
    "fbx": "https://assets.meshy.ai/.../model.fbx",
    "obj": "https://assets.meshy.ai/.../model.obj",
    "usdz": "https://assets.meshy.ai/.../model.usdz",
    "stl": "https://assets.meshy.ai/.../model.stl",
    "mtl": "https://assets.meshy.ai/.../model.mtl"
  },
  "thumbnail_url": "https://assets.meshy.ai/.../thumbnail.png",
  "consumed_credits": 30
}

Một vài trường đáng chú ý:

• model_urls chứa một liên kết tải xuống cho mọi định dạng được tạo. Theo mặc định, điều này bao gồm glb, fbx, obj, usdz, stl và mtl (tệp vật liệu đi kèm với obj).

• model_url là một lối tắt đến liên kết GLB — tiện lợi khi bạn chỉ cần GLB.

• consumed_credits hiển thị số tín dụng mà tác vụ đã sử dụng (là 0 cho các tác vụ thất bại, vì tín dụng được hoàn lại).

• thumbnail_url luôn có mặt và trỏ đến hình thu nhỏ góc nhìn trước.

• thumbnail_urls chỉ xuất hiện khi multi_view_thumbnails: true và chứa các góc nhìn trước, phải, sau và trái.

• alpha_thumbnail_url chỉ xuất hiện khi alpha_thumbnail: true và chứa hình thu nhỏ nền trong suốt.

Các giá trị status có thể có: PENDING → IN_PROGRESS → SUCCEEDED / FAILED / CANCELED

Tùy chọn B: Webhook (Được khuyến nghị cho Sản xuất)

Nếu bạn đã đặt webhook_url trong Bước 2, Meshy sẽ tự động POST đối tượng tác vụ đã hoàn thành đến URL của bạn — không cần gọi.

{
  "image_url": "https://example.com/your-image.png",
  "webhook_url": "https://yourapp.com/webhooks/meshy"
}

💡 Tôi nên sử dụng cái nào? Gọi là tốt cho việc tạo mẫu thử và các tác vụ một lần. Sử dụng webhook trong sản xuất — nó đáng tin cậy hơn và tiết kiệm các lệnh gọi API.

Bước 4: Tải Xuống Mô Hình 3D của Bạn

Khi status là SUCCEEDED, hãy lấy các URL tải xuống từ model_urls và tải xuống định dạng bạn cần:

curl -o model.glb "https://assets.meshy.ai/.../model.glb"

Cờ -o model.glb lưu tệp vào thư mục làm việc hiện tại của bạn với tên đó — sử dụng một đường dẫn đầy đủ (ví dụ: -o /path/to/model.glb) để lưu nó ở nơi khác.

Theo mặc định, mọi tác vụ đều trả về GLB, FBX, OBJ, USDZ, STL và MTL (tệp vật liệu cho OBJ). 3MF là tùy chọn — bạn chỉ nhận được nó khi bạn yêu cầu rõ ràng qua target_formats (xem bảng tham số bên dưới).

⚠️ Các liên kết hết hạn sau 3 ngày (Gói Enterprise có liên kết vĩnh viễn). Hãy tải xuống và lưu trữ các mô hình của bạn kịp thời — các liên kết sẽ không hoạt động sau khi hết hạn và bạn sẽ cần chạy lại tác vụ.

Sẵn sàng sử dụng mô hình này trong công cụ DCC của bạn? Xem hướng dẫn Bridge to Blender — Meshy cũng có các cầu nối cho Unity, Unreal, Maya và nhiều hơn nữa.

Làm thế nào để có kết quả chuyển ảnh thành 3D tốt nhất?

• Sử dụng một đối tượng duy nhất, có thể nhìn thấy rõ ràng. Một đối tượng chính, được căn giữa và đầy đủ trong khung hình, cung cấp cho AI tham chiếu rõ ràng nhất — tránh các cảnh lộn xộn, cắt xén nhiều và các góc cực đoan.

• Ưu tiên nền sạch, không lộn xộn. Nền đặc hoặc đơn giản giúp mô hình tách biệt đối tượng khỏi môi trường xung quanh.

• Sử dụng ánh sáng khuếch tán đồng đều. Bóng đổ mạnh và điểm sáng cao có thể làm sai lệch chi tiết vào kết cấu được tạo ra.

• Bắt đầu với hình ảnh sắc nét, độ phân giải cao. Càng nhiều chi tiết đầu vào thì càng nhiều chi tiết đầu ra — đầu vào mờ hoặc độ phân giải thấp tạo ra các mô hình mềm hơn.

Tôi có thể sử dụng ngôn ngữ lập trình nào với API Chuyển Ảnh Thành 3D?

Bất kỳ ngôn ngữ nào có thể thực hiện yêu cầu HTTP — bạn gửi POST với JSON và gọi với GET. Các tùy chọn phổ biến:

• Python — sử dụng thư viện requests hoặc httpx

• JavaScript / TypeScript — sử dụng fetch (tích hợp sẵn) hoặc axios

• Go — sử dụng net/http từ thư viện chuẩn

• cURL — tuyệt vời để kiểm tra nhanh từ terminal

Bạn cũng có thể tìm thấy các mẫu mã sẵn sàng sao chép cho cả bốn ngôn ngữ trong API Playground.

Một tác vụ Chuyển Ảnh Thành 3D tốn bao nhiêu tín dụng?

Chi phí phụ thuộc vào phiên bản mô hình và việc bạn có tạo kết cấu hay không. Thiết lập mặc định (meshy-6 với tạo kết cấu) tốn 30 tín dụng cho mỗi tác vụ:

Các tác vụ thất bại được hoàn tiền tự động — consumed_credits trả về 0. Luôn kiểm tra Bảng giá để biết tỷ giá mới nhất.

API Chuyển Ảnh Thành 3D chấp nhận những tham số nào?

Gửi POST đến /openapi/v1/image-to-3d với các tham số này: Bắt buộc (một trong hai):

Tùy chọn:

Các bước tiếp theo với API Chuyển Ảnh Thành 3D

Bây giờ bạn đã có quy trình hoàn chỉnh: tạo khóa API, gửi hình ảnh, gọi hoặc sử dụng webhook để lấy kết quả, sau đó tải xuống mô hình của bạn. Bốn bước tương tự này có thể mở rộng từ một nguyên mẫu nhanh đến một đường ống sản xuất tự động biến hàng nghìn hình ảnh thành tài sản 3D. Lấy khóa của bạn từ trang cài đặt API và gửi mô hình đầu tiên của bạn ngay hôm nay. Thích bắt đầu từ lời nhắc thay vì ảnh? Sử dụng API Chuyển Văn Bản Thành Mô Hình 3D.

Câu Hỏi Thường Gặp

Làm cách nào để chuyển đổi hình ảnh thành mô hình 3D qua API?

Gửi một yêu cầu POST đến /openapi/v1/image-to-3d với image_url và khóa API của bạn, sau đó gọi tác vụ (hoặc sử dụng webhook) cho đến khi status của nó là SUCCEEDED. Phản hồi trả về các liên kết tải xuống cho mô hình đã tạo. Quy trình bốn bước đầy đủ — khóa, gửi, lấy, tải xuống — được trình bày trong hướng dẫn từng bước ở trên.

API hỗ trợ những định dạng đầu ra (STL, GLB, OBJ) nào?

Mọi tác vụ đều trả về GLB, FBX, OBJ, USDZ, STL và MTL theo mặc định, với 3MF có sẵn theo yêu cầu qua target_formats. GLB tốt nhất cho web và AR, FBX và OBJ cho các công cụ DCC và game engine, USDZ cho AR trên iOS và STL cho in 3D.

Tôi có thể tải lên những định dạng hình ảnh nào?

API Chuyển Ảnh Thành 3D hỗ trợ hình ảnh JPG, JPEG và PNG lên đến 100 MB — lớn hơn giới hạn 20 MB trong giao diện Meshy Workspace. Để có kết quả chính xác nhất, hãy sử dụng PNG có nền trong suốt hoặc trắng sạch, giúp API cô lập đối tượng và tạo ra mô hình 3D chất lượng cao hơn.

Tôi có thể nhận được mô hình 3D có kết cấu từ API không?

Có. Tạo kết cấu được bật theo mặc định ("should_texture": true). Để thêm bản đồ PBR (metallic, roughness, normal), hãy đặt "enable_pbr": true — trên meshy-6/latest, điều này cũng bao gồm bản đồ emission. Để có kết cấu màu cơ bản 4K, hãy đặt "hd_texture": true (chỉ được hỗ trợ trên meshy-6/latest; bản đồ PBR vẫn ở 2K). Bạn cũng có thể định hướng phong cách kết cấu bằng texture_prompt hoặc texture_image_url.

Tôi có thể tạo mô hình 3D sẵn sàng cho in 3D (STL) không?

Có — STL được tạo theo mặc định, vì vậy việc chuyển đổi ảnh thành STL 3D không cần tham số bổ sung: chỉ cần lấy model_urls.stl khi tác vụ hoàn tất. Điều này làm cho quy trình in ảnh thành 3D trở nên đơn giản, vì STL là định dạng tiêu chuẩn mà các máy cắt (slicer) mong đợi. Nếu bạn chỉ muốn STL, hãy đặt "target_formats": ["stl"] để bỏ qua các định dạng khác và giảm thời gian tạo.

Những gói nào bao gồm quyền truy cập API?

Quyền truy cập API có sẵn trên các gói Pro, Studio và Enterprise — đây là tính năng dành cho Pro trở lên. Gói Starter miễn phí không bao gồm quyền truy cập API. Xem Bảng giá để biết chi tiết.

Các liên kết tải xuống có hiệu lực trong bao lâu?

Các liên kết tải xuống có hiệu lực trong 3 ngày trên các gói Pro và Studio. Khách hàng Enterprise nhận được các liên kết vĩnh viễn. Hãy lưu các tệp của bạn kịp thời — các liên kết đã hết hạn không thể khôi phục và bạn sẽ cần chạy lại tác vụ.

Tôi có thể chạy nhiều tác vụ cùng một lúc không?

Có, các yêu cầu đồng thời được hỗ trợ. Nếu bạn gặp lỗi 429 Too Many Requests, tài khoản của bạn đã đạt đến giới hạn tốc độ — hãy triển khai backoff theo cấp số nhân và thử lại. Xem trang Giới hạn tốc độ để biết giới hạn của gói bạn.

Tác vụ hiển thị FAILED — tôi phải làm gì?

Kiểm tra task_error.message để biết nguyên nhân. Một số nguyên nhân phổ biến:

Nếu