How to Use Image to 3D Model API: A Complete Guide 2026

The Image to 3D Model API turns a single photo into a production-ready 3D model in seconds—no manual modeling required. Hand-modeling every asset is slow and costly, and for game studios, AR apps, and e-commerce teams it quickly becomes the bottleneck that delays launches. Meshy's image-to-3D model API removes that friction: send an image, convert it to a 3D model in seconds, and download a fully textured mesh in formats like GLB, FBX, and OBJ. This guide walks you through the entire workflow—from creating your API key to downloading your first model—with copy-paste code you can run in minutes.

What is the Image to 3D Model API?

At its core, the Image to 3D Model API is a REST endpoint powered by Meshy's image to 3D model AI. You send a single image (JPG, JPEG, or PNG) as a public URL or base64 string, and the API returns a textured 3D model—geometry and base color textures included—in standard formats like GLB, FBX, OBJ, USDZ, STL, and 3MF. Optional add-ons include PBR maps, up-to-4K textures, and multi-angle preview thumbnails.

Powered by our latest Meshy 6 model, the API lets you configure topology and polygon counts, set pose modes, and guide texturing with a text prompt or reference image—ideal for generating assets for games, AR/VR, 3D printing, and product visualization.

What do you need to use the Image to 3D API?

You don't need much to follow this guide. Make sure you have:

• A Meshy account — sign up for free if you don't have one. You'll generate your API key from the dashboard in Step 1.

• An API key — used to authenticate every request. We'll walk through creating one, and you can use the free test mode key to follow along without spending credits.

• An input image — a clear .jpg, .jpeg, or .png hosted at a publicly accessible URL (or encoded as base64). A clean background and a clearly visible subject give the best results.

• A way to make HTTP requests — curl (used in the examples below), Postman, or any HTTP library in your language of choice. Basic familiarity with REST APIs and JSON is helpful but not required.

That's it—no 3D modeling experience needed. Let's get started.

How to Convert an Image to a 3D Model with the API (Step-by-Step Guide)

Step 1: Set Up Your API Settings

Everything you need to start building lives on the API settings page. This is your control center for the Meshy API, and it has three key sections:

• API Keys — generate and manage the keys that authenticate your requests.

• Webhooks — get notified automatically when your tasks finish.

• Usage — track your remaining credit balance and API consumption in real time.

Let's walk through each one.

Get Your API Key

Before making any requests, you need an API key to securely authenticate. On the API settings page, click Generate API Key. Every key follows the format msy-<random-string>.

Tip: Once generated, store your API key somewhere secure (e.g., a password manager or environment variable). Treat it like a password—never commit it to source control or expose it in client-side code.

Test Mode API Key

During development and testing, you can use the test mode API key to explore the API without consuming your credits:

msy_dummy_api_key_for_test_mode_12345678

This special key has the following characteristics:

• It can be used to make requests to all Meshy API endpoints.

• No credits are consumed when using this key.

• All valid requests return the same sample task result, regardless of the input parameters.

• The response data structure matches the production API exactly.

This makes it perfect for testing your integration before switching to your real API key.

Set Up Webhooks (Optional)

Generating a 3D model takes time, so instead of repeatedly polling the API to check whether a task is done, you can let Meshy notify you the moment it finishes. That's what webhooks are for.

In the Webhooks section of the settings page, add an endpoint URL where Meshy should send event notifications. When a task changes status (for example, when it completes or fails), Meshy sends an HTTP POST request to your URL with the task details in the payload.

Tip: Webhooks are the recommended approach for production. They reduce unnecessary API calls and let your application react to results in real time. For quick tests, polling still works fine. To test webhook code locally, point it at a proxy URL from a service like smee.io.

Try It Without Code — API Playground (Optional)

Already have your API Key? Before writing any code, you can run a real Image to 3D task directly in your browser.

Open meshy.ai/api-playground, select Image to 3D from the left panel, and fill in three things:

1. Authorization — paste your API Key (msy-xxxxxxxxxx)

2. Image — upload a .jpg, .jpeg, or .png from your computer

3. Hit Send

The Playground submits the task and polls for results automatically. Once it's done, you'll see the 3D model preview and download links right in the browser — no code required.

Pro tip: The raw request/response panel on the right shows exactly what the API sends and returns. You can copy the content directly — grab the task_id from the response, and the model_urls once the task finishes. You'll use both in the next steps.

Step 2: Submit an Image to 3D Task

With your API key ready, kick off a task with a single POST request:

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"
  }'

You'll get back a response like this:

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

That result value is your task_id — save it. You'll need it in the next step to check progress and retrieve your model.

Optional: To get notified automatically when the task finishes, add a webhook_url field to the JSON body—for example "webhook_url": "https://yourapp.com/webhooks/meshy". See Step 3, Option B for how it works.

Step 3: Get Your Results

Your task doesn't finish instantly—Meshy processes it in the background. You have two ways to get the result:

Option A: Poll for Status (Simplest)

Send a GET request every 5 seconds until status changes to SUCCEEDED:

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

The response looks like this:

{
  "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
}

A few fields worth knowing:

• model_urls holds a download link for every generated format. By default this includes glb, fbx, obj, usdz, stl, and mtl (the material file that pairs with obj).

• model_url is a shortcut to the GLB link—handy when GLB is all you need.

• consumed_credits shows how many credits the task used (it's 0 for failed tasks, since credits are refunded).

• thumbnail_url is always present and points to the front-view thumbnail.

• thumbnail_urls appears only when multi_view_thumbnails: true, and contains the front, right, back, and left views.

• alpha_thumbnail_url appears only when alpha_thumbnail: true, and holds the transparent-background thumbnail.

Possible status values: PENDING → IN_PROGRESS → SUCCEEDED / FAILED / CANCELED

Option B: Webhook (Recommended for Production)

If you set a webhook_url in Step 2, Meshy will POST the completed task object to your URL automatically—no polling needed.

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

💡 Which should I use? Polling is fine for prototyping and one-off tasks. Use webhooks in production — it's more reliable and saves API calls.

Step 4: Download Your 3D Model

Once status is SUCCEEDED, grab the download URLs from model_urls and download the format you need:

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

The -o model.glb flag saves the file to your current working directory under that name—use a full path (e.g. -o /path/to/model.glb) to save it elsewhere.

By default, every task returns GLB, FBX, OBJ, USDZ, STL, and MTL (the material file for OBJ). 3MF is opt-in—you only get it when you explicitly request it via target_formats (see the parameters table below).

⚠️ Links expire in 3 days (Enterprise plans get permanent links). Download and store your models promptly — the links won't work after expiry, and you'll need to re-run the task.

Ready to use this model in your DCC tool? See the Bridge to Blender guide—Meshy also has bridges for Unity, Unreal, Maya, and more.

How to get the best image-to-3D results?

• Use a single, clearly visible subject. One main object, centered and fully in frame, gives the AI the cleanest reference—avoid busy scenes, heavy cropping, and extreme angles.

• Prefer a clean, uncluttered background. Solid or simple backgrounds help the model separate the subject from its surroundings.

• Use even, diffuse lighting. Harsh shadows and strong highlights can bake misleading detail into the generated texture.

• Start with a high-resolution, sharp image. More detail in equals more detail out—blurry or low-res inputs produce softer models.

Which programming languages can I use with the Image to 3D API?

Any language that can make HTTP requests—you send a POST with JSON and poll with GET. Common options:

• Python — use the requests or httpx library

• JavaScript / TypeScript — use fetch (built-in) or axios

• Go — use net/http from the standard library

• cURL — great for quick testing from the terminal

You can also find ready-to-copy code samples for all four in the API Playground.

How many credits does an Image to 3D task cost?

The cost depends on the model version and whether you generate textures. The default setup (meshy-6 with texturing) costs 30 credits per task:

Failed tasks are refunded automatically—consumed_credits returns 0. Always check Pricing for the latest rates.

What parameters does the Image to 3D API accept?

Send a POST to /openapi/v1/image-to-3d with these parameters: Required (one of):

Optional:

Next steps with the Image to 3D API

You now have the complete workflow: create an API key, submit an image, poll or use a webhook for the result, then download your model. The same four steps scale from a quick prototype to a production pipeline that turns thousands of images into 3D assets automatically. Grab your key from the API settings page and ship your first model today. Prefer to start from a prompt instead of a photo? Use the Text to 3D Model API.

Frequently Asked Questions

How do I convert an image to a 3D model via the API?

Send a POST request to /openapi/v1/image-to-3d with your image_url and API key, then poll the task (or use a webhook) until its status is SUCCEEDED. The response returns download links for the generated model. The full four-step flow—key, submit, retrieve, download—is covered in the step-by-step guide above.

What output formats (STL, GLB, OBJ) does the API support?

Every task returns GLB, FBX, OBJ, USDZ, STL, and MTL by default, with 3MF available on request via target_formats. GLB is best for web and AR, FBX and OBJ for DCC tools and game engines, USDZ for iOS AR, and STL for 3D printing.

What image formats can I upload?

The Image to 3D API supports JPG, JPEG, and PNG images up to 100 MB—larger than the 20 MB limit in the Meshy Workspace UI. For the most accurate results, use a PNG with a transparent or clean white background, which helps the API isolate the subject and generate a higher-quality 3D model.

Can I get a textured 3D model from the API?

Yes. Texturing is enabled by default ("should_texture": true). To add PBR maps (metallic, roughness, normal), set "enable_pbr": true—on meshy-6/latest this also includes an emission map. For a 4K base color texture, set "hd_texture": true (supported on meshy-6/latest only; PBR maps stay at 2K). You can also steer the texture style with a texture_prompt or a texture_image_url.

Can I generate a 3D model ready for 3D printing (STL)?

Yes—STL is generated by default, so an image to 3D STL conversion needs no extra parameters: just grab model_urls.stl when the task completes. That makes image to 3D print workflows simple, since STL is the standard format slicers expect. If you only want STL, set "target_formats": ["stl"] to skip the other formats and cut generation time.

Which plans include API access?

API access is available on Pro, Studio, and Enterprise plans—it's a Pro-and-above feature. The free Starter plan does not include API access. See Pricing for details.

How long are download links valid?

Download links are valid for 3 days on Pro and Studio plans. Enterprise customers get permanent links. Save your files promptly—expired links cannot be recovered, and you'll need to re-run the task.

Can I run multiple tasks at the same time?

Yes, concurrent requests are supported. If you hit a 429 Too Many Requests error, your account has reached its rate limit—implement exponential backoff and retry. See the Rate Limits page for your plan's limits.

The task shows FAILED — what do I do?

Check task_error.message for the cause. Common ones:

If the issue persists, contact Meshy support.