name: image-to-threejs-hunyuan description: Turn one image or an ordered multi-view image set into a validated GLB and a production-ready Three.js page using either the default free local Hunyuan3D deployment or an explicitly configured paid Hunyuan cloud provider. Use when Codex needs to run or repair Hunyuan3D locally, configure or call a user-supplied Hunyuan cloud API, generate an image-to-3D asset, texture an existing mesh, build a Three.js or React Three Fiber viewer with camera, lighting and controls, or debug an image-to-3D-to-web pipeline.

Image To Three.js With Hunyuan

Build the asset pipeline in separate gates: input, generation, asset validation, scene composition, and browser verification. Never describe a model inferred from one image as a metric reconstruction.

Choose The Provider And Mode

Choose and record the provider before generation:

Do not switch to cloud generation merely because local inference is slow or fails. If hunyuan-cloud is requested without an endpoint contract, ask for the official API documentation or a working curl example before submitting an image. Never guess a Tencent endpoint, request signing scheme, model id, or billing parameter.

Read references/hunyuan-cloud.md before configuring the paid provider. Keep the API key in an environment variable or the user's credential vault, never in source, scene.json, browser code, screenshots, or command output.

Inspect every image first. For a single image, identify background contamination, watermarks, severe occlusion, and whether the subject is complete. Request clean foreground imagery or a turntable set when the source cannot support the desired geometry.

Local-Free Hunyuan Gate

Read references/hunyuan-local.md before starting or repairing Hunyuan. Keep the user's model weights, Hub cache, U2NET and output files outside the skill package and browser bundle.

本技能來自小蔥技能站7w4.net。

Before generating, verify all of these:

1. Resolve this skill's installed directory and invoke its bundled scripts by absolute path. Do not assume the current directory is the skill root.
2. Ask for or discover the user's local Hunyuan3D deployment root; do not hard-code a drive letter or package that deployment, model weights, caches, generated assets, or logs.
3. Run check_hunyuan_environment.py against the chosen deployment before submitting work.
4. The API listens only on an intended local address and port.
5. The model process uses CUDA; do not mistake download or API startup for inference.
6. The input image is readable and the output destination is outside the source-model directory.

For example, after resolving <skill-root> and <hunyuan-root> for this installation:

python <skill-root>\scripts\check_hunyuan_environment.py --project-root <hunyuan-root> --profile mini --require-api --require-cuda
python <skill-root>\scripts\generate_hunyuan_glb.py --image <input-image> --output <project-root>\assets\object.glb

Pass --texture only when the server was started with its texture pipeline enabled and has enough VRAM. Read the texture section in references/hunyuan-local.md first.

Hunyuan Cloud Gate

When provider=hunyuan-cloud, implement the user's official provider contract in a server-side adapter. The adapter must:

1. Submit the source image and explicit shape/texture parameters without exposing credentials to the browser.
2. Poll asynchronous jobs until a documented terminal state, with bounded retries and timeout.
3. Download the returned GLB to the project asset directory and reject non-GLB bytes.
4. Remove temporary signed URLs and request payloads from logs after download.

Keep the cloud adapter separate from the browser viewer. The browser receives only the downloaded GLB and a non-secret manifest. If the cloud API returns a textured GLB, preserve its authored PBR materials; if it returns shape-only geometry, label the viewer as untextured and apply only an intentional preview material.

Asset Gate

Validate every generated GLB before adding it to a page:

python <skill-root>\scripts\validate_glb.py <project-root>\assets\object.glb
python <skill-root>\scripts\create_scene_manifest.py <project-root>\assets\object.glb --source <input-image> --output <project-root>\scene.json

For multiview-asset, repeat --source in the supplied view order and pass --mode multiview-asset.

Reject an asset with no mesh, no faces, non-finite bounds, or a non-GLB response accidentally saved from an API error. Preserve the unmodified generated GLB when optimization is destructive.

Compose The Viewer

Read references/threejs-delivery.md while writing the page.

Use GLTFLoader, preserve authored PBR materials, center the model on X/Z, rest it on Y=0, and derive camera planes, orbit distances, floor size, and shadow camera from the loaded world bounds. Implement loading, error, resize, and disposal states. Use a neutral studio preset: environment contribution, key light, gentle fill, shadow receiver, and a rim light only when it improves silhouette separation.

Keep provider code and input images out of browser runtime logic. Store only public GLB assets and a non-secret scene.json in the project.

Verify

Use a real browser after the page is served:

1. Check fresh desktop and mobile loads.
2. Confirm the GLB request returns 200, no relevant console errors occur, and the canvas is nonblank.
3. Test orbit, zoom, and resize/orientation framing.
4. Capture desktop and mobile screenshots and record the result in scene.json.

Treat incorrect one-image geometry as an input-coverage limitation, not a Three.js lighting bug. Read references/threejs-delivery.md for the acceptance checklist and failure triage.

這個技能質量紮實，文件邏輯清晰、步驟完整，錯誤處理和故障排查做得很細緻，安全提示也很到位。它能幫你把圖片變成3D模型並生成可互動的網頁，展示效果專業。不過它目前只支援Windows系統使用，而且缺少可以直接執行的網頁示例。另外紋理生成功能對電腦配置要求較高，低端顯示卡可能跑不動。