Rodin Gen-1/1.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"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"

condition_mode?string

Multi-image generation mode. Optional. This parameter only applies to Gen-1/1.5.

fuse: combines features from all uploaded images; useful when images contain multiple objects;

concat: treats uploaded images as multi-view captures of one object.

Multi-image generation mode. Optional. This parameter only applies to Gen-1/1.5. - `fuse`: combines features from all uploaded images; useful when images contain multiple objects; - `concat`: treats uploaded images as multi-view captures of one object.

Default"concat"

Value in"fuse""concat"

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-1/1.5. Defaults to medium. The preset mapping is the same for both mesh modes:

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

Raw: high 50000, medium 18000, low 8000, extra-low 4000.

Optional. Preset target face count for Gen-1/1.5. Defaults to `medium`. The preset mapping is the same for both mesh modes: - `Quad`: `high` 50000, `medium` 18000, `low` 8000, `extra-low` 4000; - `Raw`: `high` 50000, `medium` 18000, `low` 8000, `extra-low` 4000.

Default"medium"

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

quality_override?integer

Optional. Custom target face count from 500 to 200000 for Gen-1/1.5. Takes precedence over quality when present.

Optional. Custom target face count from 500 to 200000 for Gen-1/1.5. Takes precedence over `quality` when present.

Range500 <= value <= 200000

tier*string

Required. Rodin Gen-1/1.5 generation tier: Sketch, Regular, Detail, or Smooth.

Required. Rodin Gen-1/1.5 generation tier: `Sketch`, `Regular`, `Detail`, or `Smooth`.

Default"Regular"

Value in"Regular""Detail""Smooth""Sketch"

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. Always upgrades pack textures from 2K to 4K. For Sketch and Regular in Quad mode, an explicitly supplied quality_override of 100000 or less also requests a high-poly model with about 16 times that face count. For Detail and Smooth, HighPack changes texture resolution only.

Optional paid add-on. Always upgrades pack textures from 2K to 4K. For `Sketch` and `Regular` in `Quad` mode, an explicitly supplied `quality_override` of 100000 or less also requests a high-poly model with about 16 times that face count. For `Detail` and `Smooth`, HighPack changes texture resolution only.

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

mesh_simplify?boolean

Controls whether generated Raw meshes are simplified. Optional. This parameter only applies to Gen-1/1.5 when mesh_mode is Raw.

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

Controls whether generated `Raw` meshes are simplified. Optional. This parameter only applies to Gen-1/1.5 when `mesh_mode` is `Raw`. Tips: We recommend leaving this parameter unset or omitting it entirely.

Defaulttrue

mesh_smooth?boolean

Controls whether generated Quad meshes are smoothed. Optional. This parameter only applies to Gen-1/1.5 when mesh_mode is Quad.

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

Controls whether generated `Quad` meshes are smoothed. Optional. This parameter only applies to Gen-1/1.5 when `mesh_mode` is `Quad`. Tips: We recommend leaving this parameter unset or omitting it entirely.

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=Sketch'

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

Choose one of the Sketch, Regular, Detail, or Smooth tiers. For Image-to-3D, submit one to five images; for Text-to-3D, submit prompt and omit 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=Regular' \
  --form 'mesh_mode=Quad' \
  --form 'quality=medium'

Multi-image behavior

condition_mode=concat treats the uploaded images as views of one object.
condition_mode=fuse combines features from images that may contain different objects.
mesh_mode accepts Quad or Raw and defaults to Quad.
quality selects a preset target face count and defaults to medium:
- Quad: high 50000, medium 18000, low 8000, extra-low 4000.
- Raw: high 50000, medium 18000, low 8000, extra-low 4000.
quality_override accepts a custom target face count from 500 to 200000 and takes precedence over quality.

Two options apply only to this generation: mesh_simplify simplifies Raw meshes and is on by default, while mesh_smooth smooths Quad meshes and is off by default. Add-on availability depends on the selected tier.

HighPack always upgrades pack textures from 2K to 4K. For Sketch and Regular in Quad mode, explicitly setting quality_override to 100000 or less also requests a high-poly model with about 16 times that face count. For Detail and Smooth, HighPack changes texture resolution only.

Pricing

Item	Charge
Base Gen-1/1.5 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-1/1.5

AuthorizationCopy Anchor Link

Request BodyCopy Anchor Link

Response BodyCopy Anchor Link

InputCopy Anchor Link

Multi-image behaviorCopy Anchor Link

PricingCopy Anchor Link

Response and lifecycleCopy Anchor Link

Authorization

Request Body

Response Body

Input

Multi-image behavior

Pricing

Response and lifecycle