Rodin Gen-2

POST

/api/v2/rodin

Generate a 3D model and textures from images or a text prompt.

Authorization

bearer

headerAuthorizationBearer <token>

Request Body

multipart/form-data

body

images*array<>

Images to be used in generation, up to 5 images. As the form data request will preserve the order of the images, For Image-to-3D generation: required (one or more images are needed, maximum 5 images)

For Text-to-3D generation: omit this field.

Images to be used in generation, up to 5 images. As the form data request will preserve the order of the images, For Image-to-3D generation: required (one or more images are needed, maximum 5 images) For Text-to-3D generation: omit this field.

Items1 <= items <= 5

prompt?string

A textual prompt to guide the model generation.

For Image-to-3D generation: optional, provide orientation-level guidance (symmetric, sharp, detail...) for generation process

For Text-to-3D generation: required. The prompt is first rendered to an image, so a text-only request can also be rejected with IMAGE_CONTENT_VIOLATION.

Tips: it is recommended to omit this field for Image-to-3D generation.

A textual prompt to guide the model generation. For Image-to-3D generation: optional, provide orientation-level guidance (symmetric, sharp, detail...) for generation process For Text-to-3D generation: required. The prompt is first rendered to an image, so a text-only request can also be rejected with `IMAGE_CONTENT_VIOLATION`. Tips: it is recommended to omit this field for Image-to-3D generation.

Lengthlength <= 1024

seed?integer

Optional. A seed value for randomization in the mesh and texture generation.

Range0 <= value <= 65535

mesh_mode?string

Optional. Mesh topology of the generated model. Raw stands for Triangle face, Quad stands for Quad face.

When omitted the default depends on tier: Gen-2.5 tiers default to Raw, every other tier defaults to Quad.

Optional. Mesh topology of the generated model. `Raw` stands for Triangle face, `Quad` stands for Quad face. When omitted the default depends on `tier`: Gen-2.5 tiers default to `Raw`, every other tier defaults to `Quad`.

Default"Quad"

Value in"Quad""Raw"

geometry_file_format?string

Optional. Output geometry file format. Supported formats: glb, usdz, fbx, obj, and stl.

Optional. Output geometry file format. Supported formats: `glb`, `usdz`, `fbx`, `obj`, and `stl`.

Default"glb"

Value in"glb""usdz""fbx""obj""stl"

material?string

Optional. Material type.

PBR: Physically Based Materials, including base color texture, metallicness texture, normal texture and roughness texture, providing high realism and physically accurate response to dynamic lighting.

Shaded: Only base color texture with baked lighting, providing stylized visuals.

All: Both PBR and Shaded will be delivered.

Hybrid: PBR texture maps with a base color texture that includes baked lighting.

None: Asset without material. This will speed up generation.

Optional. Material type. - `PBR`: Physically Based Materials, including base color texture, metallicness texture, normal texture and roughness texture, providing high realism and physically accurate response to dynamic lighting. - `Shaded`: Only base color texture with baked lighting, providing stylized visuals. - `All`: Both PBR and Shaded will be delivered. - `Hybrid`: PBR texture maps with a base color texture that includes baked lighting. - `None`: Asset without material. This will speed up generation.

Default"PBR"

Value in"PBR""Shaded""All""Hybrid""None"

quality?string

Optional. Preset target face count for Gen-2. Defaults to medium. The mapping depends on mesh_mode:

Quad: high 50000, medium 18000, low 8000, extra-low 4000;

Raw: high 500000, medium 150000, low 20000, extra-low 2000.

Optional. Preset target face count for Gen-2. Defaults to `medium`. The mapping depends on `mesh_mode`: - `Quad`: `high` 50000, `medium` 18000, `low` 8000, `extra-low` 4000; - `Raw`: `high` 500000, `medium` 150000, `low` 20000, `extra-low` 2000.

Default"medium"

Value in"high""medium""low""extra-low"

quality_override?integer

Optional. Custom target face count from 500 to 1000000 for Gen-2. Takes precedence over quality when present. Quad mode has an additional maximum of 200000; Raw mode supports up to 1000000.

Optional. Custom target face count from 500 to 1000000 for Gen-2. Takes precedence over `quality` when present. `Quad` mode has an additional maximum of 200000; `Raw` mode supports up to 1000000.

Range500 <= value <= 1000000

tier*"Gen-2"

Required. Set this field explicitly to Gen-2. If omitted, the endpoint falls back to Regular and generates a Gen-1/1.5 asset.

Required. Set this field explicitly to `Gen-2`. If omitted, the endpoint falls back to `Regular` and generates a Gen-1/1.5 asset.

Default"Regular"

Value in"Gen-2"

bbox_condition?array<>

Optional. Controls the maximum dimensions of the generated model. Provide exactly three integers in Width (X-axis), Height (Y-axis), Length (Z-axis) order (x, y, z). See BBOX Control.

Optional. Controls the maximum dimensions of the generated model. Provide exactly three integers in Width (X-axis), Height (Y-axis), Length (Z-axis) order `(x, y, z)`. See [BBOX Control](/en/api-specification/bbox-control).

Items3 <= items <= 3

addons?array<>

Optional paid add-on. Upgrades pack textures from 2K to 4K. For Gen-2, HighPack does not change geometry or generate an additional high-poly model.

Default[]

TAPose?boolean

Optional. For a human-like subject, enables rest-pose conditioning so the result is generated in a T-pose or A-pose suitable for animation. When false, the input pose is reconstructed as-is.

Optional. For a human-like subject, enables rest-pose conditioning so the result is generated in a T-pose or A-pose suitable for animation. When `false`, the input pose is reconstructed as-is.

Defaultfalse

use_original_alpha?boolean

Optional. If true, preserves and uses the uploaded image alpha channel during image preprocessing. Has no effect when the input image has no alpha channel.

Optional. If `true`, preserves and uses the uploaded image alpha channel during image preprocessing. Has no effect when the input image has no alpha channel.

Defaultfalse

preview_render?boolean

Defaultfalse

hd_texture?boolean

Optional. Enables an additional texture super-resolution and enhancement pass. This can improve fine-detail clarity but may also introduce artifacts. It does not select the final 2K or 4K pack resolution; use the HighPack add-on for 4K output.

Defaultfalse

soft?boolean

Optional. Appends smooth edges to the final geometry-generation prompt without changing the generation tier.

Tips: We recommend leaving this parameter unset or omitting it entirely.

Optional. Appends smooth edges to the final geometry-generation prompt without changing the generation tier. Tips: We recommend leaving this parameter unset or omitting it entirely.

Defaultfalse

detail_level?integer

Optional. Controls how many final geometry-refinement stages use RGB image conditioning. Higher values preserve more visual detail. Omit to use the default refinement path.

Tips: We recommend leaving this parameter unset or omitting it entirely.

Optional. Controls how many final geometry-refinement stages use RGB image conditioning. Higher values preserve more visual detail. Omit to use the default refinement path. Tips: We recommend leaving this parameter unset or omitting it entirely.

Range1 <= value <= 3

is_symmetric?string

Optional. Intended symmetry of the generated geometry. Use symmetric for objects that should mirror left and right, asymmetric for posed or irregular objects, and balanced for mostly symmetric objects that should retain small natural differences. Use unknown to let the system infer the mode from the prompt and input images.

Optional. Intended symmetry of the generated geometry. Use `symmetric` for objects that should mirror left and right, `asymmetric` for posed or irregular objects, and `balanced` for mostly symmetric objects that should retain small natural differences. Use `unknown` to let the system infer the mode from the prompt and input images.

Default"unknown"

Value in"symmetric""balanced""asymmetric""unknown"

quad_normal?boolean

Optional. Bakes high-resolution geometry detail into a normal map during mesh refinement.

Defaultfalse

Response Body

application/json

response

error?string

Error code, if the request could not be submitted. This is returned in the response body alongside HTTP 201, so clients must check this field rather than relying on the HTTP status alone. This field is omitted on success. For detailed error code information, please refer to: errors

Value in"NO_SUCH_TASK""ASSET_NOT_AVAILABLE""IMAGE_LABEL_LENGTH_TOO_LONG""INVALID_REQUEST""API_NO_ACTIVE_SUBSCRIPTION""API_SUBSCRIPTION_PLAN_TOO_LOW""API_PARALLELISM_LIMIT_REACHED""API_INSUFFICIENT_FUNDS""API_OBJECT_NOT_FOUND_ON_IMAGE""IMAGE_CONTENT_VIOLATION""PERMISSION_DENIED""API_UNKNOWN"

message?string

Success message or detailed error information.

uuid?string

Unique identifier for the submitted generation task.

Formatuuid

submit_time?string

Server time when the task was submitted.

Formatdate-time

jobs?

A job object, containing details of individual jobs executed as part of the generation process.

consumed?number

Credits consumed by this request.

prompt?string

The prompt actually used for generation.

Example Request

curl -X POST 'https://api.hyper3d.com/api/v2/rodin' \  -F 'tier=Gen-2'

Example ResponseSchema

{  "error": "NO_SUCH_TASK",  "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,  "prompt": "string"}

Input

Set tier=Gen-2. For Image-to-3D, submit one to five images and optionally a prompt. For Text-to-3D, submit prompt and omit images.

tier is required

Always send tier=Gen-2. If tier is omitted, the endpoint falls back to Regular and generates a Gen-1/1.5 asset.

curl --fail-with-body --request POST 'https://api.hyper3d.com/api/v2/rodin' \
  --header "Authorization: Bearer ${RODIN_API_KEY}" \
  --form 'images=@./input.png' \
  --form 'tier=Gen-2' \
  --form 'mesh_mode=Raw' \
  --form 'quality=medium'

HighPack upgrades pack textures from 2K to 4K. For Gen-2 it does not change geometry or generate an additional high-poly model.

Pricing

Item	Charge
Base Gen-2 generation	`0.5 credits`

Charges are additive. Base generation costs only 0.5 credits, and parameters not listed above do not incur additional charges.

Response and lifecycle

{
  "message": "Submitted.",
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "jobs": {
    "uuids": ["223e4567-e89b-12d3-a456-426614174000"],
    "subscription_key": "subscription-key-from-generation-response"
  },
  "consumed": 0.5
}

Use jobs.subscription_key for Check Status and top-level uuid for Download Results. HTTP 201 means the endpoint handled the request; acceptance requires an absent or empty error and a non-empty top-level uuid. HTTP 400 indicates invalid fields/files, 401 indicates invalid authentication, and 429 indicates throttling.

Rodin Gen-2

AuthorizationCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

InputCopy Anchor Link

PricingCopy Anchor Link

Response and lifecycleCopy Anchor Link

Authorization

Request Body

Response Body

Input

Pricing

Response and lifecycle