Async tasks: submit, poll and retry safely
A 3D model takes from seconds to minutes, so POST /v1/generate returns at once with a workflow id and you poll GET /v1/workflows/{id} for the result.
Response envelope
Every JSON response is {"code": 0, "message": "ok", "data": …} on success. Failures carry "code": -1, a readable message, a real HTTP status, and — when there is one — a machine code in data.code.
Submitting
POST /v1/generate takes {mediaType, model, scene, prompt, options}. For 3D, mediaType is 3d and scene picks the input mode (text-to-3d, image-to-3d, …). The response's data.id is the workflow id and data.totalCredits is what was charged.
Input images are passed as public https URLs in options.image. The API does not accept file bytes, multipart uploads or base64 data.
Workflow statuses
| Status | Final? |
|---|---|
pending | no |
processing | no |
success | yes |
partial | yes |
failed | yes |
canceled | yes |
Stop polling when data.workflow.isTerminal is true. A failed or canceled workflow names the reason in data.workflow.errorCode (see error codes) and reports returned credits in data.workflow.refundedCredits.
How often to poll
Poll every 5 seconds. One polling loop then uses 12 of the 60 requests each key may make per minute. Typical run times per model are on the pricing page.
Idempotency-Key: safe retries
POST /v1/generaterequires anIdempotency-Keyheader of up to 191 printable ASCII characters. A UUID per generation works.- Retrying with the same key and the same body returns the ORIGINAL workflow and does not charge again — retry timeouts and 5xx answers this way.
- The same key with a different body is refused with
422.
Downloading results
data.assets[].storedUrl is the URL of each model file (normally an absolute https URL; the samples resolve a relative one against the base URL). Results also appear in the account's creations library in the web app.
Batches: one run per picture
POST /v1/batches runs one model with the same options over several pictures in your Library, one run per picture, started in the background as your plan's concurrency allows. The scenes and models an app batches are generation.batches in GET /v1/capabilities; how many pictures your plan lets one batch hold is allowance on GET /v1/batches?scene=.
- Each picture is
{"assetId": …}: theassets[].idof a finished image run. A batch takes no URLs and no file bytes. - Nothing is charged on submit. Each run is charged as it starts and refunded if it fails, but your balance must cover the whole
quotedCreditsnow. - Poll
GET /v1/batches/{id}. Each started item names itsworkflowId, andGET /v1/workflows/{id}gives its files. POST /v1/batches/{id}/retryqueues the failed ones again. A batch cannot be cancelled: a run that stalls fails on its own and is refunded.- An
Idempotency-Keyis required, as for/v1/generate. A key's monthly credit limit must have room for the whole quote when the batch is accepted; each picture then counts its real cost, and nothing if it fails, is cancelled or is refused.
Converting and repairing a model on the server
POST /v1/tools/convert turns one of your Library models (a GLB, OBJ or STL file) into GLB, STL, 3MF, OBJ or PLY, optionally simplified, meshopt-compressed, scaled to a real-world size or repaired for printing, and files the result in your Library as a new creation made from it. It costs no credits and answers in the same request, with the new workflowId and the file's url.
- Name the model by
assetId: theassets[].idof a finished 3D run. A URL or file bytes are not accepted. - STL and 3MF are written in millimetres and Z-up, as slicers read them. OBJ and PLY carry geometry only, in metres. GLB keeps materials and textures. An OBJ is read alone, as geometry (no mtl or texture travels with it), and an STL is read as millimetres, Z-up.
resizeHeightorresizeLongestSide(metres) scales the model, andoriginputs its origin at the bottom centre (the default when resizing) or the centre.repair: trueruns the free repair tool's steps first — weld, drop collapsed and duplicate faces and loose debris, turn the faces outward, fill holes — for STL, 3MF, OBJ or PLY (a GLB's textures would no longer fit), up to 200,000 triangles aftersimplify(too_dense_to_repairpast that).report.repairholds the geometrybeforeandafter(watertight, holes, non-manifold edges, shells) and thechangeseach step made.- A model over 50 MB or 2,000,000 triangles, or Draco-compressed, answers
422or413with the reason indata.code; so does a compression that would not make an already-compressed GLB smaller (not_smaller). - The same model and options return the same creation (
created: false), so a retry is safe. Each account may convert 10 models a minute and 300 a day.