Rodin Gen-2.5

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"Raw"

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.5. Defaults to medium. The mapping depends on mesh_mode:

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

Raw: high 1000000, medium 500000, low 60000, extra-low 20000.

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

Default"medium"

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

quality_override?integer

Optional. Custom target face count from 500 to 2000000 for Gen-2.5. Takes precedence over quality when present. Gen-2.5-High and Gen-2.5-Extreme-High support up to 2000000; all other Gen-2.5 tiers support up to 1000000. Quad mode has an additional maximum of 200000.

Optional. Custom target face count from 500 to 2000000 for Gen-2.5. Takes precedence over `quality` when present. `Gen-2.5-High` and `Gen-2.5-Extreme-High` support up to 2000000; all other Gen-2.5 tiers support up to 1000000. `Quad` mode has an additional maximum of 200000.

Range500 <= value <= 2000000

tier*string

Required. Select and explicitly send a Gen-2.5 tier. If omitted, the endpoint falls back to Regular and generates a Gen-1/1.5 asset.

See Tier for more information.

This parameter may affect billing. See Pricing.

Required. Select and explicitly send a Gen-2.5 tier. If omitted, the endpoint falls back to `Regular` and generates a Gen-1/1.5 asset. See [Tier](/en/api-specification/rodin-gen2-5#tier) for more information. This parameter may affect billing. See [Pricing](/en/api-specification/rodin-gen2-5#pricing).

Default"Regular"

Value in"Gen-2.5-Extreme-Low""Gen-2.5-Low""Gen-2.5-Medium""Gen-2.5-High""Gen-2.5-Extreme-High"

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 add-on. Upgrades pack textures from 2K to 4K. For Gen-2.5, 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

Optional. If true, provides an additional high-quality render image in the download list. Defaults to false.

If use the Fast mode, this parameter is ignored.

Optional. If true, provides an additional high-quality render image in the download list. Defaults to `false`. If use the [Fast mode](/en/api-specification/rodin-gen2-5#fast-mode), this parameter is ignored.

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

texture_mode?string

Optional. Texture mode for the generated model.

Higher modes generally produce richer, higher-resolution texture detail but take longer and may affect billing. See Pricing.

legacy: Use the legacy texture pipeline.

extreme-high: Can produce up to 12K textures. See Texture resolution.

The default value depends on the selected tier, see Texture mode.

Optional. Texture mode for the generated model. Higher modes generally produce richer, higher-resolution texture detail but take longer and may affect billing. See [Pricing](/en/api-specification/rodin-gen2-5#pricing). - `legacy`: Use the legacy texture pipeline. - `extreme-high`: Can produce up to 12K textures. See [Texture resolution](/en/api-specification/rodin-gen2-5#texture-resolution). The default value depends on the selected `tier`, see [Texture mode](/en/api-specification/rodin-gen2-5#texture-mode).

Value in"legacy""extreme-low""low""medium""high""extreme-high"

is_micro?boolean

Whether to generate micro-scale surface detail. Only allowed when tier is Gen-2.5-Extreme-High; any other tier is rejected with INVALID_REQUEST.

Tips: We recommend leaving this parameter unset or set to default value.

Whether to generate micro-scale surface detail. Only allowed when `tier` is `Gen-2.5-Extreme-High`; any other tier is rejected with `INVALID_REQUEST`. Tips: We recommend leaving this parameter unset or set to default value.

Defaultfalse

geometry_instruct_mode?string

Optional. Selects the geometry-generation strategy. creative favors richer or more imaginative structure with less strict input fidelity; faithful stays closer to the provided image and prompt, but may not always produce a closer match or higher-quality results. Availability depends on the selected tier.

Tips: We recommend omitting this parameter to use the default value. faithful is an experimental option, may be discontinued in the future, and is not recommended for production use.

Optional. Selects the geometry-generation strategy. `creative` favors richer or more imaginative structure with less strict input fidelity; `faithful` stays closer to the provided image and prompt, but may not always produce a closer match or higher-quality results. Availability depends on the selected `tier`. Tips: We recommend omitting this parameter to use the default value. `faithful` is an experimental option, may be discontinued in the future, and is not recommended for production use.

Default"creative"

Value in"faithful""creative"

texture_delight?boolean

Optional. If true, removes highlights and baked lighting from texture-reference images before texture generation to reduce lighting artifacts in the generated material.

Tips: We recommend leaving this parameter unset or omitting it entirely unless you have specific lighting requirements.

Optional. If `true`, removes highlights and baked lighting from texture-reference images before texture generation to reduce lighting artifacts in the generated material. Tips: We recommend leaving this parameter unset or omitting it entirely unless you have specific lighting requirements.

Defaultfalse

uhd_texture?boolean

Optional. Applies additional sharpening to texture details. This can improve perceived detail but may also introduce artifacts. This parameter may affect texture resolution. See Texture resolution.

Optional. Applies additional sharpening to texture details. This can improve perceived detail but may also introduce artifacts. This parameter may affect texture resolution. See [Texture resolution](/en/api-specification/rodin-gen2-5#texture-resolution).

Defaultfalse

image_label?array<>

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: ?

The viewing direction of each uploaded image, positionally matched to images. Entries default to ? (unknown) and the list is padded to the image count. Supplying more labels than images is rejected with IMAGE_LABEL_LENGTH_TOO_LONG. Support direction labels: - `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`: `?`

Default[]

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"

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

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.5-Extreme-Low'

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

Image-to-3D

Submit one to five images. The first image is used for material generation. prompt is optional; when omitted, the service derives guidance from the images.

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.5-Medium' \
  --form 'mesh_mode=Raw' \
  --form 'quality=medium'

Text-to-3D

Submit a prompt and omit images.

curl --fail-with-body --request POST 'https://api.hyper3d.com/api/v2/rodin' \
  --header "Authorization: Bearer ${RODIN_API_KEY}" \
  --form 'prompt=A small wooden treasure chest with brass trim' \
  --form 'tier=Gen-2.5-Medium' \
  --form 'mesh_mode=Raw' \
  --form 'quality=medium'

Tier

tier is required

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

tier selects the generation family and how much detail the model resolves. It is independent of the mesh and texture controls below: any tier can be combined with any mesh_mode, quality, or texture_mode the schema allows.

Tier	Intended use
`Gen-2.5-Extreme-Low`	Quick generation of simple assets.
`Gen-2.5-Low`	Clean assets and small hard-surface props.
`Gen-2.5-Medium`	Balanced structure and detail.
`Gen-2.5-High`	Richer structure and smoother surfaces.
`Gen-2.5-Extreme-High`	High-frequency detail reproduction. This tier also returns an additional mesh with up to 10M of faces.

Geometry generation modes

geometry_instruct_mode selects how the input guides geometry generation. faithful emphasizes matching the image and prompt, though results vary.

Experimental option: faithful

faithful may be discontinued and is not recommended for production use. For routine generation, omit geometry_instruct_mode to use the default.

Fast mode

When the submitted task meets all of the following conditions, Fast mode is triggered and resulting in faster generation.

tier is not Gen-2.5-Extreme-High.
geometry_file_format is glb \ fbx \ usdz.
mesh_mode is Raw.
quality_override <= 20000.

Texture mode

texture_mode selects the texture generation effort level. The default value of texture_mode depends on the selected tier.

Tier	Default `texture_mode`
`Gen-2.5-Extreme-Low`	`extreme-low`
`Gen-2.5-Low`	`low`
`Gen-2.5-Medium`	`medium`
`Gen-2.5-High`	`high`
`Gen-2.5-Extreme-High`	`high`

Texture resolution

The texture resolution is jointly determined by texture_mode, uhd_texture, and addons.

HighPack increases pack texture resolution as shown below. For Gen-2.5, it does not change geometry or generate an additional high-poly model.

texture_mode	addons	uhd_texture	resolution
extreme-low, low, medium, high	[]	false	2K
	[]	true	4K
	HighPack	false	4K
	HighPack	true	8K
extreme-high	[]	false	6K
	[]	true	6K
	HighPack	false	12K
	HighPack	true	12K

Pricing

Item	Charge
Base Gen-2.5 generation	`0.5 credits`
`tier=Gen-2.5-Extreme-High`	`+0.5 credits`
`texture_mode=extreme-high`	`+2.0 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.5

AuthorizationCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

InputCopy Anchor Link

Image-to-3DCopy Anchor Link

Text-to-3DCopy Anchor Link

TierCopy Anchor Link

Geometry generation modesCopy Anchor Link

Fast modeCopy Anchor Link

Texture modeCopy Anchor Link

Texture resolutionCopy Anchor Link

PricingCopy Anchor Link

Response and lifecycleCopy Anchor Link

Authorization

Request Body

Response Body

Input

Image-to-3D

Text-to-3D

Tier

Geometry generation modes

Fast mode

Texture mode

Texture resolution

Pricing

Response and lifecycle