Skip to main content

tripo/h3.1/image-to-3d

Tripo H3.1 Image to 3D turns one picture into a GLB with PBR textures by default, with switches for HD textures, detailed geometry, quad topology, face count, real-world scale, orientation and separate geometry and texture seeds.

From $0.432/request

Workbench

Send a request

Quickstart

Examples use the selected endpoint’s public parameter definitions. Replace the API key and example media, then send the request from your server.

SDKs & integrations
POSThttps://api.spicyapi.ai/api/v1/jobs/createTask

API authentication

Keep the API key in the server environment variable SPICY_API_KEY. Use Bearer authentication and Content-Type: application/json for JSON requests.

Authorization: Bearer $SPICY_API_KEY
# Generate the idempotency key once; reuse it when retrying after a lost response.
export SPICY_IDEMPOTENCY_KEY="${SPICY_IDEMPOTENCY_KEY:-$(uuidgen)}"
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
  -d '{
  "model": "tripo/h3.1/image-to-3d",
  "input": {
    "generate_parts": false,
    "generate_pbr": true,
    "generate_texture": true,
    "geometry_quality": "standard",
    "image_url": "https://example.com/reference.png",
    "low_poly": false
  }
}'

# Copy data.taskId from the response into TASK_ID, then poll the status.
TASK_ID="TASK_ID_FROM_RESPONSE"
curl "https://api.spicyapi.ai/api/v1/jobs/recordInfo?taskId=$TASK_ID" \
  -H "Authorization: Bearer $SPICY_API_KEY"

Generated from this model’s input schema — the same one the API validates every request against.

Input parameters

Place these fields inside the request body’s input object. Names and types match the API. Do not assume a default when none is specified.

image_urlstringRequired

The picture to model: JPEG, PNG or WebP up to 10 MB. One subject, fully in frame, on a plain background; a three-quarter view gives the model the most depth information.

Default
Not specified
Constraints
minLength:1
contentMediaType:["image/jpeg","image/png","image/webp","image/gif"]
texture_seedintegerOptional

Optional seed for the texture step. Keep seed fixed and change this to try new textures on the same shape.

Default
Not specified
Constraints
minimum:0
maximum:2147483647
seedintegerOptional

Optional seed for the geometry step. Keep it fixed to reproduce the same shape.

Default
Not specified
Constraints
minimum:0
maximum:2147483647
uv_unwrapbooleanOptional

On by default. Off skips UV unwrapping for a faster, smaller file, but the mesh then has no texture coordinates for texturing later. Does not change the price.

Default
true
auto_sizebooleanOptional

Off by default. On scales the mesh to estimated real-world dimensions, useful for AR and printing. Does not change the price.

Default
false
texture_alignmentstringOptional

original_image (the default) aligns the texture to the picture; geometry aligns it to the generated shape. Does not change the price.

Default
"original_image"
Allowed values
"original_image""geometry"
model_orientationstringOptional

default keeps the model's standard orientation; align_image rotates the result to match the view in the picture. Does not change the price.

Default
"default"
Allowed values
"default""align_image"
image_autofixbooleanOptional

Off by default. On repairs a blurry, noisy or low-resolution picture before modelling, which takes longer. Does not change the price.

Default
false
face_limitintegerOptional

Optional target face count from 1,000 to 2,000,000. Leave it empty to let the model decide, which can mean more than a million faces; 50,000 to 200,000 suits most web viewers. Does not change the price.

Default
Not specified
Constraints
minimum:1000
maximum:2000000
generate_partsbooleanOptionalAffects price

Off by default. On returns the model as separate named parts in one GLB (18 parts for our toy astronaut). Parts carry no textures and are always triangles, so the texture options and quad_mesh are ignored and not billed; the total is still higher than the textured default.

Default
false
low_polybooleanOptionalAffects price

Off by default. On builds a light mesh with clean, hand-modelled-style topology, best for simple props; keep face_limit at 20,000 or below. In our run, face_limit 5,000 on the boot returned 7,675 triangles. Adds to the price.

Default
false
quad_meshbooleanOptionalAffects price

Off by default. On returns four-sided (quad) polygons instead of triangles, which are easier to edit in modelling tools, and the file comes back as FBX (textures embedded) instead of GLB. Adds a small amount to the price. Ignored, and not charged, when generate_parts is on: the parts stay triangles in a GLB.

Default
false
geometry_qualitystringOptionalAffects price

standard (the default) or detailed. detailed builds finer surface detail and is the most expensive add-on.

Default
"standard"
Allowed values
"standard""detailed"
remove_lightingbooleanOptional

On by default. Strips the highlights and shadows baked into the picture before texturing, so the model reacts to your own scene lights. Takes effect only with the v3.5 texture model. Does not change the price.

Default
true
texture_versionstringOptional

v3.0-20250812 (the default) or the newer v3.5-20260815. texture_quality fast and remove_lighting rely on v3.5. Does not change the price.

Default
"v3.0-20250812"
Allowed values
"v3.0-20250812""v3.5-20260815"
texture_qualitystringOptionalAffects price

standard (the default), detailed, extreme or fast. detailed gives higher-resolution textures and extreme 8K textures, each adding to the price; fast keeps the standard size, uses the v3.5 texture model and costs the same as standard. None of them applies to an untextured mesh or to generate_parts.

Default
"standard"
Allowed values
"standard""detailed""extreme""fast"
generate_pbrbooleanOptionalAffects price

On by default. Adds PBR material maps (metal-roughness and normal) next to the base colour, and turns texturing on even when generate_texture is off. Off together with generate_texture gives a bare, cheaper mesh.

Default
true
generate_texturebooleanOptionalAffects price

On by default. Paints a texture onto the mesh. Turning this off saves the texture add-on only if generate_pbr is off as well, because PBR materials switch texturing back on.

Default
true

Track the task

HTTP 202 means the task was accepted, not completed. Save the returned taskId and query that task. Do not create another task while waiting for its result.

Accepted response
HTTP/1.1 202 Accepted
Location: /api/v1/jobs/recordInfo?taskId=job_01k3m8x9q2z4v7n5p6r8s0t1w3

{
  "code": 200,
  "msg": "success",
  "request_id": "req_example_create",
  "data": {
    "taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
    "state": "queued",
    "estimatedCost": "0.750000"
  }
}

The accepted response includes the estimate so your app can show the same amount in task history and billing.

Read the job
curl --get "https://api.spicyapi.ai/api/v1/jobs/recordInfo" \
  --data-urlencode "taskId=$TASK_ID" \
  -H "Authorization: Bearer $SPICY_API_KEY"

Start polling at about 2 seconds and gradually increase the interval. Stop at a terminal state. After a connection failure, query the original taskId. Retry creation only with the original idempotency key and body.

Or let the callback find you
import { verifyWebhook } from "@spicyapi/sdk";

// express.raw keeps the bytes we signed; express.json never matches.
app.post("/hooks/spicy", express.raw({ type: "application/json" }), (req, res) => {
  const { payload } = verifyWebhook({
    rawBody: req.body,
    timestamp: req.header("X-Webhook-Timestamp"),
    signature: req.header("X-Webhook-Signature"),
    payloadVersion: Number(req.header("X-Webhook-Payload-Version")),
    secret: process.env.SPICY_WEBHOOK_SECRET,
  });
  res.status(200).end();
  void handleFinishedTask(payload);
});

Pass callBackUrl when you create the task and the finished record is POSTed to you — no polling loop at all. Every delivery carries X-Webhook-Timestamp, X-Webhook-Signature and X-Webhook-Payload-Version. The signature is a base64 HMAC-SHA256 over taskId.timestamp.sha256(body), so it must be checked against the raw bytes: parsing the JSON and re-serialising it changes them and the check will fail. Failed deliveries are retried, so the same taskId can arrive twice — make the handler idempotent. Answer 2xx first and do the work afterwards; a slow handler is treated as a failed delivery.

Read the result

Consume output only when state is succeeded. On failure, use errorCode, errorMessage and request_id to investigate. Example costs and states do not represent an actual bill.

Completed response example
{
  "code": 200,
  "msg": "success",
  "request_id": "req_example_record",
  "data": {
    "taskId": "job_01k3m8x9q2z4v7n5p6r8s0t1w3",
    "model": "tripo/h3.1/image-to-3d",
    "state": "succeeded",
    "output": {
      "assets": [
        {
          "key": "tasks/2026/08/28/job_01k3m8x9q2z4v7n5p6r8s0t1w3/3f7a1c9e5b2d48f0a6c1e3d5b7f9a1c3.png",
          "mime": "image/png",
          "url": "https://example.r2.cloudflarestorage.com/results/job_01k3m8x9q2z4v7n5p6r8s0t1w3/result.png?X-Amz-Signature=SIGNATURE_FROM_RESPONSE",
          "expiresAt": "2026-08-28T12:20:08.000Z"
        }
      ]
    },
    "cost": "0.750000",
    "settled": true,
    "createdAt": "2026-08-28T12:00:00Z",
    "completedAt": "2026-08-28T12:00:30Z"
  }
}

For each available asset, open or download assets[].url directly without an API Authorization header. The signed URL expires at expiresAt; poll the task again to refresh it while the asset remains within its retention period. A pending or unavailable asset has no URL. Treat signed URLs as private.

SDKs & integrations

Use SpicyAPI in your app, terminal, AI assistant or visual workflow. Choose a setup guide below.

Use it in ComfyUI

Install the SpicyAPI nodes from ComfyUI Manager or with the command below, then search for Tripo H3.1 · Image to 3D on the canvas. The node has the same options as this page and shows its price before it runs.

cd ComfyUI/custom_nodes
git clone https://github.com/spicyapi-ai/comfyui-spicyapi