Hyper3DHyper3D Docs
API Specification

Low-poly

Create a low-poly model from a Rodin asset, an uploaded model, images, or text, then track and download the result.

POST
/api/v2/polygen

Authorization

bearer
headerAuthorizationBearer <token>

Request Body

multipart/form-data
  1. body
asset_id?string
Formatuuid
model?file
Formatbinary
transfer_texture?boolean
Defaulttrue
images?array<>
Items1 <= items <= 5
prompt?string
image_label?array<>
Default[]
face_count?integer
Range200 <= value <= 10000
mesh_mode?string
Default"Quad"
Value in"Quad""Raw""NGon"
geometry_file_format?string

Optional. Output file format. Defaults to obj.

Default"obj"
Value in"glb""usdz""fbx""obj""stl"
material?string
Default"None"
Value in"PBR""Shaded""All""Hybrid""None"
resolution?string
Default"Basic"
Value in"Basic""High"
texture_mode?string
Default"medium"
Value in"legacy""extreme-low""low""medium""high""extreme-high"
uhd_texture?boolean

Response Body

application/json
  1. response
message?string

Success message or detailed error information.

uuid?string
Formatuuid
submit_time?string

Server time when the task was submitted.

Formatdate-time
jobs?
consumed?number

Credits consumed by this request.

error?ApiGeneratePolygenError
Value in"INVALID_REQUEST""NO_SUCH_TASK""PERMISSION_DENIED""ASSET_NOT_AVAILABLE""NO_ACTIVE_SUBSCRIPTION""INSUFFICIENT_FUNDS""UNKNOWN"
Example Request
curl -X POST 'https://api.hyper3d.com/api/v2/polygen'
Example Response
{  "message": "Submitted.",  "uuid": "123e4567-e89b-12d3-a456-426614174000",  "submit_time": "2019-08-24T14:15:22Z",  "jobs": {    "uuids": [      "52faea01-729e-4195-85e8-6050a65315e3"    ],    "subscription_key": "string"  },  "consumed": 0.5,  "error": "INVALID_REQUEST"}

POST /api/v2/polygen creates a Smart Low Poly model from an existing Rodin asset, a model file, reference images, or a text description. Generation runs in the background: you submit a task, poll its status, and download the result when it finishes. Requests need a bearer API key with Full API access.

Choose your input

Start from whichever input you have. Send uploads as multipart/form-data.

InputWhat to sendTextures
A completed Rodin taskIts top-level uuid as asset_idGenerated when you set material
A model fileThe file as modelTransferred from the original model
Reference imagesOne to five files as repeated imagesGenerated when you set material
A text descriptionprompt, without any of the aboveGenerated when you set material

Choose the mesh and export format

  • face_count: Target face count, from 200 to 10,000. If you omit it, PolyGen targets 4,000 faces for uploaded models and picks a count automatically for other inputs.
  • mesh_mode: Quad (default) for quadrilateral faces, Raw for triangles, or NGon for polygons.
  • geometry_file_format: obj (default), glb, usdz, fbx, or stl. The glb, usdz, and fbx formats embed textures in the model file.

Add textures

When you start from an asset, images, or text, PolyGen generates geometry only by default. To generate textures as well, set material to PBR, Shaded, Hybrid, or All. Uploaded models work differently; see From an uploaded model.

texture_mode controls how much texture detail PolyGen generates: extreme-low, low, medium (default), high, or extreme-high. Higher modes produce richer detail but take longer. legacy uses the previous texture pipeline.

uhd_texture=true sharpens fine texture detail. If the result shows artifacts, leave it off.

Texture resolution

The resolution of generated textures depends on texture_mode, uhd_texture, and resolution.

resolution defaults to Basic; High requires high-resolution export access.

texture_moderesolutionuhd_texture=falseuhd_texture=true
extreme-low, low, medium, highBasic2K*4K
extreme-low, low, medium, highHigh4K*8K
extreme-highBasic6K6K
extreme-highHigh12K12K

* Affects only the base color texture; normal, metallic, and roughness textures keep their resolution.

Submit a generation task

From a Rodin asset

Pass the top-level uuid of a completed Rodin Gen-2 or Gen-2.5 task as asset_id. You can't pass tasks that started from an uploaded model, such as PolyGen or Rigging tasks submitted with model. To simplify one of those results, download it and upload it as model.

The example below generates geometry only. If you set material, PolyGen textures the model using the source task's input images and prompt. To use different references, upload images or pass a new prompt.

curl --fail-with-body --request POST 'https://api.hyper3d.com/api/v2/polygen' \
  --header "Authorization: Bearer ${RODIN_API_KEY}" \
  --form 'asset_id=123e4567-e89b-12d3-a456-426614174000' \
  --form 'geometry_file_format=obj' \
  --form 'mesh_mode=Quad' \
  --form 'face_count=4000'

From an uploaded model

Upload an obj, glb, stl, fbx, usd, usda, usdz, or usdc file as model. PolyGen simplifies the mesh and transfers the original textures to it. Set transfer_texture=false if you only need geometry.

PolyGen doesn't generate new textures for uploaded models, so material, texture_mode, uhd_texture, and prompt have no effect here. resolution sets the size of the transferred textures: Basic exports 2K and High exports 4K. You can also upload images as references for refining the mesh.

curl --fail-with-body --request POST 'https://api.hyper3d.com/api/v2/polygen' \
  --header "Authorization: Bearer ${RODIN_API_KEY}" \
  --form 'model=@./model.glb' \
  --form 'transfer_texture=true' \
  --form 'geometry_file_format=obj' \
  --form 'mesh_mode=Quad' \
  --form 'face_count=4000'

From images

Upload one to five images, such as PNG, JPEG, or WebP files, as repeated images fields. PolyGen builds the mesh from them and also uses them as texture references.

The example below uploads front and back views of an object and requests PBR textures. image_label is an optional JSON array of viewing directions in upload order, so ["F","B"] marks the first image as the front and the second as the back. Use prompt to describe details the images don't show clearly, such as surface materials.

curl --fail-with-body --request POST 'https://api.hyper3d.com/api/v2/polygen' \
  --header "Authorization: Bearer ${RODIN_API_KEY}" \
  --form 'images=@./front.png' \
  --form 'images=@./back.png' \
  --form 'image_label=["F","B"]' \
  --form 'prompt=A small wooden toy robot with a square head and short arms.' \
  --form 'geometry_file_format=obj' \
  --form 'mesh_mode=Quad' \
  --form 'face_count=4000' \
  --form 'material=PBR'

From text

Describe the object in prompt, up to 1,024 characters. PolyGen first generates a reference image from the description, then builds the low-poly model from that image. The example below describes a wooden toy robot and generates geometry only.

curl --fail-with-body --request POST 'https://api.hyper3d.com/api/v2/polygen' \
  --header "Authorization: Bearer ${RODIN_API_KEY}" \
  --form 'prompt=A small wooden toy robot with a square head and short arms.' \
  --form 'geometry_file_format=obj' \
  --form 'mesh_mode=Quad' \
  --form 'face_count=4000'

Wait for completion and download

A successful submission returns the new task's identifiers:

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "jobs": {
    "uuids": ["123e4567-e89b-12d3-a456-426614174001"],
    "subscription_key": "123e4567-e89b-12d3-a456-426614174002"
  }
}

If the response contains error instead, no task was created. See Resolve submission errors.

  1. Poll Check Status with jobs.subscription_key until every job is Done. If a job reports Failed, the task won't produce a result.
  2. Pass the top-level uuid as task_uuid to Download Results, then download the files from the returned URLs.

Pricing

Each PolyGen task costs 0.5 credits. The response shows the charge in consumed.

Resolve submission errors

If a field can't be parsed or fails validation, the API returns HTTP 400. Other rejections return HTTP 201 with an error code, and message explains the cause. For how the API reports errors in general, see Errors.

ErrorMeaning and fix
INVALID_REQUESTThe request has no input, combines asset_id with model, or contains an invalid file or value. message names the problem.
NO_SUCH_TASKasset_id doesn't match a task. Use the top-level task uuid, not a job UUID or subscription key.
ASSET_NOT_AVAILABLEThe source task hasn't finished or can't be reused. Wait for it to complete, or download the model and upload it as model.
PERMISSION_DENIEDCheck that the API key has Full API access, that you own the source asset, and that you have high-resolution export access if you set resolution=High.
INSUFFICIENT_FUNDSYour balance is too low. Add credits and submit again.