Skip to content
Image to STL
Back to blog

Image to 3D API: build a reliable generation workflow

Choose an image-to-3D API and design upload, async jobs, GLB storage, retries and cost controls for a website or SaaS product.

Image to STL Editorial

An image-to-3D API lets your application submit an image, track a generation job and retrieve a model such as GLB. Build it as an asynchronous workflow: validate the upload, submit on the server, save the job identifier, observe completion, copy the permitted output into durable storage and present the model to the correct user.

A provider's web demo is useful for initial evaluation, but API availability, pricing, allowed formats and output retention can differ from the web app. Confirm the API contract you will actually integrate before promising a free quota or a particular export to your own users.

Compare providers by the job you need to complete

For a textured ecommerce asset, geometry-only output is insufficient. For a print-focused application, color may be less important than shape and downstream mesh checks. For a game pipeline, mesh complexity, material layout and available cleanup tools matter.

RequirementWhat to verify in the API documentation
Single-image generationAccepted image formats, dimensions, upload method and size limits
Multiple viewsWhich views are supported and how they are associated with one object
Textured GLBWhether texturing is included, optional or a separate task
Job lifecycleSubmission response, status values, polling interval and webhook support
Failure handlingError semantics, retry behavior, cancellation and charging rules
Asset retrievalResult URL lifetime, authentication, retention and download limits
Production useCommercial terms, data handling, region availability and rate limits
BudgetGeneration, texture, remesh, conversion and retry costs

Meshy's image-to-3D API documentation, for example, documents input options, output formats and task operations. Its API pricing documentation describes prepaid API credits. Do not substitute the web app's subscription allowance for the API billing model.

Microsoft's TRELLIS.2 repository and Tencent's Hunyuan3D-2 repository describe software you can evaluate for self-hosting. Running a model is a different integration from calling a managed API: you also own GPU capacity, dependencies, deployment, queuing and operations. Read each release's license rather than assuming all downloadable models have the same terms.

Use an asynchronous state machine

A useful application-level lifecycle is:

validated -> submitting -> queued -> processing -> ready
                                \-> failed
             \-> submission_unknown

These are example application states, not a provider's literal status values. Map the provider's documented states to your own record. Keep the original provider status and a safe diagnostic code for operations.

Save the authenticated owner, input reference, requested options, provider, model version and creation time. Once the provider accepts the task, persist its job identifier. Treat that identifier as the link to an existing remote job, not as permission for any user to access it.

A page refresh should resume observation of the saved job. It should not submit the same generation again. Keep job creation separate from status polling and from model downloads.

Validate inputs before paid submission

Check the image's actual type and decoded dimensions, not only its filename. Enforce the limits of your chosen provider and your application's own upload budget. A small compressed file can still decode to a very large image.

Store API credentials on the server. Authenticate generation requests and apply per-user and application-wide limits. If your application uses credits, reserve or deduct them atomically with the creation of the local job record so concurrent requests cannot overspend the balance.

Explain when an image leaves the user's device and which service processes it. Keep images, signed asset URLs and provider credentials out of marketing analytics. Use an intentional retention policy for both the input and the generated result.

Handle retries without charging twice

A timeout does not always mean that submission failed. The provider may have accepted the job before your server lost the response. Automatically resubmitting can create a second paid generation.

Use provider-supported idempotency where available and a durable local request identifier. If acceptance is uncertain, record that uncertainty and reconcile it using the provider's supported mechanisms. Do not mark it as a confirmed failure solely because your HTTP request timed out.

Distinguish at least three situations:

  • Rejected before acceptance: fix the input or configuration before allowing another submission.
  • Accepted and later failed: apply the provider's documented failure and charging policy, then update your own ledger consistently.
  • Acceptance unknown: reconcile the original request before retrying, refunding or deducting again.

Make ledger adjustments idempotent. Receiving the same webhook twice should not give the user two refunds, and polling after a webhook should not charge them again.

Poll or receive webhooks according to the contract

Polling is simple when the provider supplies a task-status endpoint. Use its documented limits, back off appropriately, and stop polling completed jobs. Keep polling on the server or behind an authenticated application endpoint so you do not expose provider credentials.

If webhooks are available, verify their authentication and associate events with a known task. Expect duplicate events, delayed events and events that arrive out of order. A background reconciliation process can recover jobs whose completion notification was missed.

Neither a spinner nor an estimated progress value should imply an exact completion time. Show meaningful states and let users leave and return to their saved job.

Copy and validate output files safely

A result URL may expire or depend on provider-side retention. When allowed, fetch the completed asset into storage you control and save its metadata. Check content type, byte limits and file structure before making it available to the user.

Restrict server-side downloads to documented provider result hosts and approved protocols. Do not build an unrestricted URL fetcher from a user-supplied address. Apply timeouts and streaming byte limits so a bad response cannot exhaust memory or storage.

Authorize each asset download against the job's owner. Avoid returning arbitrary provider result records, internal diagnostics or credentials to the browser. If your product offers public sharing, treat that as a separate, explicit access decision.

Budget for the complete usable result

A low generation price does not describe the cost of the whole workflow. Track optional texturing, remeshing, retries, storage, delivery, queue processing and any cleanup required before the user accepts the output.

For a self-hosted system, include GPU runtime, idle capacity, startup latency and maintenance. “Open source” removes neither compute cost nor operational responsibility.

Evaluate providers with the same images and destination checks. Record generation time, success or failure, actual downloadable formats, file size and whether the model passes your task-specific review. This creates useful product evidence without pretending that one attractive preview establishes universal quality.

Complete the downstream workflow

For web use, retain GLB materials and follow the website display guide. For printing, convert a copy to the required format, inspect scale and geometry, and check the slicer's layers. Exporting STL does not itself repair a mesh.

Image to STL provides an end-user image workbench and a local GLB-to-STL tool. This article describes API integration patterns; it is not documentation for a publicly supported Image to STL developer API.

Sources

API and model references checked November 18, 2026: Meshy image-to-3D API, Meshy API pricing, Microsoft TRELLIS.2 and Tencent Hunyuan3D-2. State names and system design examples here are illustrative; use the selected provider's current documentation for request fields and billing behavior.