Skip to main content

Quick Start

3D generation is an asynchronous operation. The whole process is divided into three steps:
Minimal Example

API Overview

Base URL: https://aihubmix.com Authentication: Bearer Token
Unlike the video API, the 3D API has no /content download endpoint and no DELETE endpoint: outputs are downloaded directly via the content_url in the output[] array of the query response.

Supported Models

Generation Types (generate_type)

API Details

Request Headers

Create a 3D Generation Task

Request Body

Parameter Validation Rules
  • prompt and input_references are mutually exclusive (only one may be provided); the only exception is generate_type: "Sketch", which allows both together (sketch + text description).
  • Within each input_references item, exactly one of image_url and image_base64 must be provided:
    • image_url only supports public http(s) URLs; data URLs are not supported (use image_base64 instead);
    • image_base64 must not exceed 6MB after decoding.
  • hy-3d-3.1 does not support the LowPoly generation type.
  • The total request body size must not exceed 10MB.
Using extra_body: Upstream native parameters (such as polygon_type) can be placed at the top level of extra_body for pass-through. The following parameters must be passed as top-level fields — including them in extra_body returns 400: model, prompt, image_url, image_base64, generate_type, enable_pbr, face_count, result_format; multi_view_images (multi-view images) is not supported yet.

Example Response

Status Values

Query Task Status

Poll this endpoint to check whether the task is complete. We recommend querying every 10-15 seconds. Queries are not billed.

Example Response (Generation Complete)

output[] Field Description
content_url and preview_url are temporary links that expire after a period of time. Download the files and transfer them to your own storage as soon as the task completes. The task ID remains queryable for 24 hours after creation (the expires_at field indicates the query deadline); querying after expiration returns an error. The temporary links only support GET requests; HEAD requests return 403.

Usage Examples

Complete Invocation Examples

Billing

  • Billed per generation: the price is determined by the combination of model × generate_type × PBR enabled × face count specified × format specified. See the Model Gallery for specific prices.
  • Billing occurs when the task is created successfully; querying task status and downloading outputs are not billed.
  • Parameter combinations without a configured price return 400 directly at creation time and incur no charge.

FAQ

How long does 3D generation take?

It usually takes several minutes, depending on the model, generation type, and face count settings. We recommend polling the query endpoint at a 10-15 second interval.
  • The task ID remains queryable for 24 hours after creation; the expires_at field in the response indicates the query deadline.
  • content_url / preview_url are temporary upstream links that expire after a period of time; download and save them promptly after the task completes.

Can I pass both prompt and a reference image?

No — the two are mutually exclusive. The only exception is generate_type: "Sketch" (sketch-to-3D), which allows passing both a sketch image and a text description.

What are the differences between the generate_type options?

How do I handle a failed task?

When status is failed, the error field in the response contains error information:
Common failure reasons include: content policy violations, unsupported image formats, inaccessible reference images, etc. Adjust based on the error message and retry.
Last updated: 2026-07-17