Skip to content

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

StatusFinal?
pendingno
processingno
successyes
partialyes
failedyes
canceledyes

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/generate requires an Idempotency-Key header 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": …}: the assets[].id of 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 quotedCredits now.
  • Poll GET /v1/batches/{id}. Each started item names its workflowId, and GET /v1/workflows/{id} gives its files.
  • POST /v1/batches/{id}/retry queues the failed ones again. A batch cannot be cancelled: a run that stalls fails on its own and is refunded.
  • An Idempotency-Key is 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: the assets[].id of 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.
  • resizeHeight or resizeLongestSide (metres) scales the model, and origin puts its origin at the bottom centre (the default when resizing) or the centre.
  • repair: true runs 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 after simplify (too_dense_to_repair past that). report.repair holds the geometry before and after (watertight, holes, non-manifold edges, shells) and the changes each step made.
  • A model over 50 MB or 2,000,000 triangles, or Draco-compressed, answers 422 or 413 with the reason in data.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.