Hunyuan3d V3 Text To 3d API Documentation

Hunyuan3d V3 Text To 3d API Documentation

Playground

Turn text prompts into detailed, fully-textured 3D models with Tencent’s Hunyuan3D V3. Generate high-quality 3D assets with PBR materials from simple descriptions, ready for Unity, Unreal, and Blender. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

Hunyuan3D v3 Text-to-3D is a 3D asset generation wrapper that turns a short text description into a downloadable 3D model you can use in DCC tools (Blender/Maya), game engines, or product visualization pipelines. It’s designed for fast iteration: describe an object, pick a generation mode (textured vs. geometry-only), and generate a mesh with an optional texture/material setup.

This task is best for single-object assets (props, furniture, simple characters) where you want a usable starting point and can refine topology/materials afterward.

Key capabilities

• Text-to-3D generation with multiple output styles Choose between a textured mesh and a geometry-only white model depending on your target workflow.

• Optional PBR material generation Enable PBR materials for more realistic shading (e.g., metal/roughness/normal-style textures), when supported by the selected generation type.

• Face-count targeting for mesh density Generate higher-detail or lighter meshes by specifying a target face count within the supported range.

• Standardized 3D file outputs with preview Results typically include a downloadable 3D file (e.g., OBJ/GLB) plus a preview image URL for quick inspection.

Parameters and how to use

• prompt: (required) Text describing the 3D asset you want.
• generate_type: Generation mode. Values are Normal (textured) and Geometry (white model).
• enable_pbr: Whether to generate PBR materials (when supported by the selected mode).
• face_count: Target face count for the generated mesh (within the supported range).

Prompt

Write prompts like you’re briefing a 3D artist:

• Start with the object and its category: “a modern desk lamp”, “a sci-fi handheld scanner”.
• Add shape cues: silhouette, proportions, key parts (“cylindrical base, articulated arm, conical shade”).
• Add material and finish: plastic/metal/wood, matte/glossy, worn/new.
• Avoid clutter: one object per run whenever possible.

Example prompt:

> “A compact camping lantern, cylindrical body with a handle loop on top, translucent plastic cover, brushed metal base, realistic product photo style.”

Other parameters

• generate_type Pick the output style:

• Normal – textured 3D model (default in many setups)

• Geometry – geometry-only (no textures / white model)

• enable_pbr

• true – generate PBR materials when supported

• false – standard materials/textures Note: In geometry-only modes, PBR may not apply. {/* :contentReference[oaicite:7]{index=7} */}

• face_count

• Default is commonly 500,000

• Supported range is typically 40,000–1,500,000 Use smaller values for faster iteration and larger values for more surface detail.

After you finish configuring the parameters, click Run, preview the result, and iterate if needed.

Pricing

Pricing depends on the selected generation type and whether PBR materials are enabled.

Billing Rules

• Prices include the face-count allowance, including when the default face count is used.
• Changing face_count within the supported range does not add further charges.
• Enabling enable_pbr adds $0.18 per request.
• Default configuration (Normal, PBR disabled): $0.63 per request.

Notes

• Treat face count as “target,” not a guarantee. If you need strict budgets (e.g., mobile game assets), plan to retopologize or decimate after generation.
• Use Geometry for downstream texturing workflows. If you plan to texture in Substance or do custom UV work, starting with a clean geometry-only mesh can be easier.
• Start simple, then add detail. A clear base prompt usually produces better structure than a long, highly stylized prompt.

Related Models

• Tencent Hunyuan3D v2.1 – A strong earlier Hunyuan3D generation option when you want a proven baseline model.
• Hunyuan3D v2 Base – A practical, lower-cost option for image-to-3D style workflows and quick iterations.
• Hunyuan3D v2 Mini – Faster/leaner variant for previews and early-stage ideation.
• Hunyuan3D v2 Multi-View – Best when you have multiple reference images and want higher geometric fidelity from views.

Authentication

For authentication details, please refer to the Authentication Guide.

API Endpoints

Submit Task & Query Result

set -euo pipefail

export WAVESPEED_API_KEY="your-api-key"

REQUEST_BODY=$(cat <<'JSON'
{
  "prompt": "A cinematic ocean wave at sunrise, highly detailed",
  "enable_pbr": false,
  "face_count": 500000,
  "generate_type": "Normal"
}
JSON
)

# 1. Submit the prediction once. Never retry this request automatically:
# a retry after an unclear failure can create a second, billed task.
CHECK='The task may already exist. Check History or the predictions list before submitting again.'
if ! SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --connect-timeout 10 --max-time 60 \
  -X POST "https://api.wavespeed.ai/api/v3/wavespeed-ai/hunyuan3d-v3/text-to-3d" \
  -H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}"); then
  printf 'Submit failed. %s\n' "${CHECK}" >&2
  exit 1
fi

TASK=$(printf '%s' "${SUBMIT_RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
PREDICTION_ID=$(printf '%s' "${TASK}" | jq -r '.id // empty')
if [ -z "${PREDICTION_ID}" ]; then
  printf 'Submission response did not contain a prediction id. %s\n' "${CHECK}" >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

# 2. Poll until the prediction reaches a final status.
BODY_FILE=$(mktemp)
trap 'rm -f "${BODY_FILE}"' EXIT
while true; do
  # Transient errors (429, 5xx) are retried, honoring Retry-After.
  HTTP_CODE=$(curl --silent --show-error --fail-with-body \
    --connect-timeout 10 --max-time 60 --retry 5 --retry-delay 2 \
    --output "${BODY_FILE}" --write-out '%{http_code}' \
    "${RESULT_URL}" \
    -H "Authorization: Bearer ${WAVESPEED_API_KEY}" || true)
  case "${HTTP_CODE}" in
    2??) ;;
    000|429|5??)  # dropped connection or temporary error: keep polling
      printf 'Task %s: HTTP %s, polling again in 10s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
      sleep 10; continue ;;
    *) printf 'Task %s: HTTP %s\n' "${PREDICTION_ID}" "${HTTP_CODE}" >&2
      cat "${BODY_FILE}" >&2; exit 1 ;;
  esac
  RESULT=$(jq 'if type == "object" and has("data") then .data else . end' "${BODY_FILE}")
  STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')

  case "${STATUS}" in
    completed) printf '%s\n' "${RESULT}" | jq '.outputs'; break ;;
    failed|cancelled|timeout|deleted)
      printf 'Task %s ended with status %s\n' "${PREDICTION_ID}" "${STATUS}" >&2
      printf '%s\n' "${RESULT}" | jq . >&2; exit 1 ;;
    *) sleep 2 ;;
  esac
done

Parameters

Task Submission Parameters

Request Parameters

Response Parameters

Result Request Parameters

Result Response Parameters