Hitem3D

Use this skill to turn images into downloadable 3D models via scripts/hitem3d.sh.

Use the script

Resolve all relative paths against this skill directory.

Script: scripts/hitem3d.sh
API reference: references/api.md
Product guide / positioning: references/product-guide.md
ClawHub-style description: references/clawhub-description.md
Release checklist: references/release-checklist.md
Live validation notes: references/live-validation.md

If the user asks for a normal one-off generation, prefer the full pipeline:

submit task
wait for completion
download result
report output path, format, model, and estimated credit cost

Do not leave the user with only a task ID unless they explicitly want async handling.

Operator standard

Act like a production 3D operator, not a thin API wrapper.

Infer likely intent from the request instead of asking obvious questions.
Distinguish single-image, portrait, multi-view, and batch every time.
Prefer finishing the workflow over handing back raw JSON.
Surface cost, output path, format, and caveats in plain language.
Stop early on ambiguous expensive jobs, invalid inputs, or unsafe assumptions.
Never echo secrets, bearer tokens, or raw Authorization headers.

Required setup

Runtime requirements

Binaries: curl, python3, base64
Required env vars: HITEM3D_AK, HITEM3D_SK
Optional env var: HITEM3D_TOKEN

The user must provide credentials through environment variables:

export HITEM3D_AK="your_access_key"
export HITEM3D_SK="your_secret_key"

If credentials are missing, stop and tell the user exactly which variables are not set.

Default operating policy

When the user says “turn this image into 3D” without more detail, use these defaults:

model: hitem3dv2.0
request type: 3 (geometry + texture)
resolution: 1536
format: 2 (GLB)
face count: unset

Why: this is the best general-purpose quality/output tradeoff.

Choose the right mode

Single-image general object

Use when the input is one product shot, concept image, illustration, object render, furniture photo, toy, packaging, or other non-portrait asset.

Default command pattern:

scripts/hitem3d.sh run input.png

Portrait / bust generation

Use portrait models when the user explicitly wants a person, face, bust, avatar head, or half-body likeness.

Preferred defaults:

model: scene-portraitv2.1
resolution: 1536pro
format: GLB unless user asks otherwise

Command pattern:

scripts/hitem3d.sh run face.jpg --model scene-portraitv2.1 --resolution 1536pro

3D printing

If the user mentions 3D printing, printer, slicer, or STL, prefer:

format: 3 (STL)
request type: 1 for mesh-only when texture is irrelevant
optionally set higher face count for smoother geometry

Command pattern:

scripts/hitem3d.sh run object.png --format 3 --type 1 --face 500000

AR / Apple preview

If the user mentions Apple AR, Quick Look, Vision Pro, AR preview, or iPhone preview, prefer format 5 (USDZ).

Fast / cheap draft

If the user wants a rough draft, cheap test, or low-cost preview, prefer:

model: hitem3dv1.5
resolution: 512
type: 1 or 3 depending on whether texture matters

Multi-view reconstruction

Use multi-view when the user provides 2-4 images of the same subject from different angles.

Use:

generate-multi or run-multi
pass a bitmap describing which views are present

Bitmap order is:

front
back
left
right

Examples:

front + left = 1010
front + back + left + right = 1111
front + right = 1001

Do not use multi-view mode for unrelated images.

Batch processing

Use batch mode only when the user wants to process many separate images independently. Do not confuse batch with multi-view.

Batch means:

one task per image
submit all
wait/download each
return a concise summary of successes/failures and output paths

Cost policy

Before batch jobs or obviously expensive jobs, tell the user the expected cost and ask for confirmation.

Must confirm before proceeding when either is true:

batch job with more than 5 images
likely cost exceeds 100 credits total
the request implies repeated retries, alternative variants, or multiple output formats that would multiply spend

For one-off standard jobs, confirmation is not required unless the user has asked to be cost-cautious.

Reference pricing in references/api.md.

Practical heuristics:

cheapest draft: hitem3dv1.5 + 512 + mesh-only = 5 credits
default general result: hitem3dv2.0 + 1536 + textured = 50 credits
premium portrait / 1536pro textured = about 70 credits

When estimating cost, say whether the number is per task or total batch cost.

Output policy

Prefer saving downloads into a user-relevant folder under the current workspace unless the user provides a destination.

Suggested defaults:

one-off tasks: ./output/hitem3d/
batch tasks: ./output/hitem3d/<batch-name>/

When reporting completion, include:

task ID
final status
saved file path
output format
model used
resolution
estimated credit cost

If the API returns a preview/cover URL, include it when useful.

Common commands

Check balance

scripts/hitem3d.sh balance

Submit only

scripts/hitem3d.sh generate photo.png

Full one-shot pipeline

scripts/hitem3d.sh run photo.png

For long jobs, explicitly raise the timeout instead of assuming 10 minutes is enough:

scripts/hitem3d.sh run photo.png --timeout-seconds 3600 --poll-seconds 8

Full one-shot pipeline with custom options

scripts/hitem3d.sh run photo.png --model hitem3dv1.5 --resolution 1024 --format 3 --type 1 --download-dir ./output/hitem3d/

Multi-view submit

scripts/hitem3d.sh generate-multi front.png left.png --views 1010

Multi-view full pipeline

scripts/hitem3d.sh run-multi front.png back.png left.png right.png --views 1111 --model hitem3dv2.0 --download-dir ./output/hitem3d/multi/

Long-running jobs

If a job is likely to take a while, set explicit polling and timeout values:

scripts/hitem3d.sh run-multi front.png left.png --views 1010 --timeout-seconds 3600 --poll-seconds 8

Wait for an existing task and download

scripts/hitem3d.sh wait <task_id> --download ./output/hitem3d/

For slow tasks:

scripts/hitem3d.sh wait <task_id> --download ./output/hitem3d/ --timeout-seconds 3600 --poll-seconds 8

Batch folder processing

scripts/hitem3d.sh batch ./images --glob '*.png' --download-dir ./output/hitem3d/batch/

Decision rules

If the user does not specify format:

use GLB by default
use STL for 3D printing intent
use USDZ for Apple AR intent

If the user does not specify model:

use scene-portraitv2.1 for portraits
otherwise use hitem3dv2.0

If the user does not specify resolution:

use 1536 for general work
use 1536pro for portrait premium output
use 512 for cheap drafts

If the user says “highest quality”:

general object: hitem3dv2.0 + 1536
portrait: scene-portraitv2.1 + 1536pro
mention expected credit usage before running

Failure handling

Missing credentials

Stop and ask the user to set HITEM3D_AK and HITEM3D_SK.

Bad input images

Reject unsupported formats and files larger than 20MB before calling the API.

Auth failure

Tell the user credentials are invalid or expired. Do not keep retrying.

Generation failure

If API error is 50010001, tell the user the image likely could not be parsed and credits should be refunded automatically.

Token expiry

The script auto-fetches tokens. Retry once if a token-related request fails.

URL expiry

If the returned download URL has expired, re-query task status to fetch a fresh URL before declaring failure.

Multi-view mismatch

If the user labels images as multi-view but the set is missing the front view, warn that Hitem3D expects the front view and that results may fail or degrade.

Security rules

Never print or store AK/SK in user-visible output.
Treat callback URLs as advanced usage; do not invent or auto-fill webhooks.
Do not claim full production validation unless live API runs have been completed with real credentials.
If credentials are unavailable, say the skill is design-validated but not fully live-validated.

Download URL expiry

If the result URL expired, re-query task status to obtain a fresh result URL if available, then download again.

Unsupported combination

Reject obviously bad combos before calling the API, especially:

request type 2 with hitem3dv2.0
multi-view without a valid 4-bit view bitmap
face count outside 100000-2000000

Notes for good judgment

A user saying “folder of 30 product renders” means batch, not multi-view.
A user sending front/back/left/right of the same object means multi-view, not batch.
For printing intent, geometry matters more than texture.
For showcase/demo intent, textured GLB is usually the right default.
Prefer completing the full task over dumping raw API responses.
Keep user-visible replies concise and outcome-focused.