Low-poly
Create a low-poly model from a Rodin asset, an uploaded model, images, or text, then track and download the result.
bearerAuthorizationBearer <token>multipart/form-data- body
asset_id?string**Mutually exclusive with `model`.** Top-level task UUID of a completed Rodin asset. Check the [source asset requirements](/en/api-specification/polygen#from-a-rodin-asset). If you omit `images`, PolyGen reuses the source asset's input images as texture references.
uuidmodel?file**Mutually exclusive with `asset_id`.** Mesh file to simplify: `obj`, `glb`, `stl`, `fbx`, `usd`, `usda`, `usdz`, or `usdc`. PolyGen simplifies the mesh and transfers its original textures unless `transfer_texture` is `false`.
binarytransfer_texture?boolean**Optional.** Transfers the uploaded model's original textures to the low-poly mesh. Defaults to `true`. Applies only when passing `model`.
trueimages?array<>One to five uploaded images (PNG, JPEG, WebP), sent as repeated multipart `images` fields. With `model`, these are optional references for mesh refinement. With `asset_id`, they replace the texture references. Without either, they drive mesh generation and are also used as texture references. To generate textures from them, also set `material`.
1 <= items <= 5prompt?string**Required only for Text-to-3D.** You can omit this field when you pass `images`, `asset_id`, or `model`. - **Omitting `images`, `asset_id`, and `model`:** Pass a non-blank description of up to 1,024 characters. PolyGen generates a reference image from the text and uses it to create the 3D model. - **Passing `images` without `asset_id` or `model`:** Use `prompt` to guide Image-to-3D and any requested texture generation. If you omit `prompt`, PolyGen uses a general 3D model prompt. - **Passing `asset_id`:** Use `prompt` to guide new textures if you request them. If you omit `prompt`, PolyGen reuses the source asset's prompt, if available. - **Passing `model`:** PolyGen ignores `prompt`.
image_label?array<>**Optional.** Viewing directions, positionally matched to uploaded `images`. Send a JSON array. Missing entries are padded with `?` (unknown). More labels than uploaded images are rejected with `INVALID_REQUEST`. Existing asset labels are preserved when no images are uploaded. Supported directions: - Front: `F` - Front-left: `FL` - Front-right: `FR` - Back: `B` - Back-left: `BL` - Back-right: `BR` - Left: `L` - Right: `R` - Up: `U` - Down: `D` - Unknown: `?`
[]face_count?integer**Optional.** Target face count (200–10,000). When omitted, PolyGen targets 4,000 faces for uploaded models and picks a count automatically for other inputs.
200 <= value <= 10000mesh_mode?string**Optional.** Mesh topology: - `Quad` for quadrilateral faces. - `Raw` for triangle faces. - `NGon` for polygon faces. Defaults to `Quad`.
"Quad""Quad""Raw""NGon"geometry_file_format?stringOptional. Output file format. Defaults to obj.
"obj""glb""usdz""fbx""obj""stl"material?string**Optional.** Defaults to `None`. For asset, image, or text inputs, `None` exports geometry only; `PBR`, `Shaded`, `Hybrid` and `All` generate and export textures. Ignored with `model`, which transfers the original textures by default.
"None""PBR""Shaded""All""Hybrid""None"resolution?string**Optional.** Output texture resolution. Defaults to `Basic`. `High` increases the export resolution and requires high-resolution export access. When generating new textures, the final resolution also depends on the texture mode and sharpening. See [Texture resolution](/en/api-specification/polygen#texture-resolution). Ignored when the request only produces geometry.
"Basic""Basic""High"texture_mode?string**Optional.** Texture mode for the generated model. Higher modes generally produce richer, higher-resolution texture detail but take longer. - `legacy`: Use the legacy texture pipeline. - `extreme-high`: Can produce up to 12K textures. See [Texture resolution](/en/api-specification/polygen#texture-resolution). Defaults to `medium`. Ignored when uploading `model` or when `material=None`.
"medium""legacy""extreme-low""low""medium""high""extreme-high"uhd_texture?boolean**Optional.** Sharpens fine texture detail. Leave it off if the result shows artifacts. Except in `extreme-high` mode, it also doubles the texture resolution. It only affects the resolution of the base color texture and does not change the resolution of other maps (normal, metallic, roughness). See [Texture resolution](/en/api-specification/polygen#texture-resolution). Ignored when uploading `model` or when `material=None`.
application/json- response
message?stringSuccess message or detailed error information.
uuid?stringUUID of the new Low Poly task. Use as `task_uuid` with `POST /api/v2/download`.
uuidsubmit_time?stringServer time when the task was submitted.
date-timejobs?Submitted jobs. Use `subscription_key` with `POST /api/v2/status`.
consumed?numberCredits consumed by this request.
error?ApiGeneratePolygenErrorError code when the task could not be submitted. Omitted on success.
"INVALID_REQUEST""NO_SUCH_TASK""PERMISSION_DENIED""ASSET_NOT_AVAILABLE""NO_ACTIVE_SUBSCRIPTION""INSUFFICIENT_FUNDS""UNKNOWN"curl -X POST 'https://api.hyper3d.com/api/v2/polygen'{ "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.
| Input | What to send | Textures |
|---|---|---|
| A completed Rodin task | Its top-level uuid as asset_id | Generated when you set material |
| A model file | The file as model | Transferred from the original model |
| Reference images | One to five files as repeated images | Generated when you set material |
| A text description | prompt, without any of the above | Generated 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,Rawfor triangles, orNGonfor polygons.geometry_file_format:obj(default),glb,usdz,fbx, orstl. Theglb,usdz, andfbxformats 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_mode | resolution | uhd_texture=false | uhd_texture=true |
|---|---|---|---|
extreme-low, low, medium, high | Basic | 2K | *4K |
extreme-low, low, medium, high | High | 4K | *8K |
extreme-high | Basic | 6K | 6K |
extreme-high | High | 12K | 12K |
* 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.
- Poll Check Status with
jobs.subscription_keyuntil every job isDone. If a job reportsFailed, the task won't produce a result. - Pass the top-level
uuidastask_uuidto 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.
| Error | Meaning and fix |
|---|---|
INVALID_REQUEST | The request has no input, combines asset_id with model, or contains an invalid file or value. message names the problem. |
NO_SUCH_TASK | asset_id doesn't match a task. Use the top-level task uuid, not a job UUID or subscription key. |
ASSET_NOT_AVAILABLE | The 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_DENIED | Check 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_FUNDS | Your balance is too low. Add credits and submit again. |