Hunyuan3d V3 Sketch To 3d API Documentation

Hunyuan3d V3 Sketch To 3d API Documentation

Playground

Transform your sketches into detailed 3D models with Tencent’s Hunyuan3D V3. Convert hand-drawn sketches and concept art into high-quality 3D assets with textures, perfect for rapid prototyping and game development. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

Hunyuan3D v3 Sketch-to-3D turns a sketch or line drawing into a 3D asset you can preview and download. It’s designed for fast iteration: provide a clear sketch, optionally add a short text description (materials, colors, style), and get back a mesh you can refine.

This wrapper uses the Sketch task type, where a sketch image and a prompt can be provided together to guide both shape and appearance.

Key capabilities

• Sketch-conditioned 3D generation Generates a 3D model from a sketch/line drawing input.

• Prompt-guided appearance control Add a prompt to clarify object identity, material, and style. In Sketch mode, prompt + image work together.

• Optional PBR materials Enable PBR output when you need more realistic materials (typical metallic/roughness workflows).

• Mesh complexity control Set a target face_count to trade off detail vs. runtime and editability.

• Asynchronous job workflow Submit a job, then poll status until it finishes. Results include downloadable files and preview URLs.

Parameters and how to use

• input_image_url: (required) A URL to the sketch / line drawing image.
• prompt: A short text description to guide object identity and appearance.
• enable_pbr: Whether to generate PBR materials.
• face_count: Target face count for the generated mesh.

Prompt

Sketches often don’t contain enough information for materials, color, and surface detail. Use prompt to fill in what the sketch doesn’t say.

Tips:

• Start with what it is + what it’s made of + key visual traits.
• If the sketch is ambiguous, specify front/back, symmetry, and proportions.
• Keep it single-subject. Avoid prompts that describe multiple objects.

Example prompts:

• “single ceramic coffee mug, matte white glaze, slight lip on rim, minimal style”
• “sports sneaker, rubber sole, mesh upper, black and neon green accents, product-style lighting”

Media (Images)

Input

• Provide a publicly accessible image URL (or upload via your media pipeline and paste the resulting URL).
• Supported formats: JPG / JPEG / PNG / WEBP.

Other parameters

enable_pbr

• Type: boolean

• Default: false

• What it does: generates PBR materials when enabled.

• When to use:

• false for faster previews, simpler assets, or when you’ll re-shade in a 3D tool.

• true when you want more realistic materials out of the box.

face_count

• Type: integer

• Default: 500000

• Range: 40000–1500000

• What it does: requests a target face count for the generated mesh.

• Typical guidance:

• 40000–150000: mobile / real-time previews

• 150000–600000: general-purpose assets

• 600000–1500000: close-ups or heavier editing

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

Pricing

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.15 per request.
• Default configuration (PBR disabled): $0.525 per request.

Notes

• Use prompt + sketch together. If your sketch is minimal, a short prompt can significantly improve interpretation of parts and materials.
• Download outputs promptly. Result URLs may expire, so persist assets you want to keep.
• Batching considerations. For pipelines, plan around concurrency and rate limits.
• Cost/latency trade-offs. Enabling PBR and specifying a custom face_count may take longer to finish.

Related Models

• Hunyuan3D V2 Base – Image-to-3D baseline when you have a clean reference image instead of a sketch.
• Hunyuan3D V2 Mini – Faster / lighter image-to-3D option for rapid iteration and previews.
• Hunyuan3D V2 Multi-View – Best when you can provide multiple views to improve reconstruction stability and shape fidelity.
• SAM 3D Objects Generator – Image-to-3D with optional mask guidance for cleaner object isolation from complex backgrounds.

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",
  "image": "https://interactive-examples.mdn.mozilla.net/media/cc0-images/painted-hand-298-332.jpg",
  "enable_pbr": false,
  "face_count": 500000
}
JSON
)

# 1. Submit the prediction.
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  -X POST "https://api.wavespeed.ai/api/v3/wavespeed-ai/hunyuan3d-v3/sketch-to-3d" \
  -H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}")

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
' >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

# 2. Poll until the prediction finishes.
while true; do
  RESPONSE=$(curl --silent --show-error --fail-with-body \
    "${RESULT_URL}" \
    -H "Authorization: Bearer ${WAVESPEED_API_KEY}")
  RESULT=$(printf '%s' "${RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
  STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')

  case "${STATUS}" in
    completed) printf '%s\n' "${RESULT}" | jq '.outputs'; break ;;
    failed|cancelled|timeout|deleted) 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