# Tripo3d Tripo3d H3.1 — Image To 3d > Use the Tripo3D H3.1 API on GPTProto for high-detail 3D assets from text, images, or multiview inputs, with PBR, quad meshes, and up to 2M faces. ## Overview - **Guide status: available** - **API availability**: not tested; available means a model-specific request is documented - **Base URL**: `https://gptproto.com/api/v3` - **Endpoint**: `POST https://gptproto.com/api/v3/tripo3d/tripo3d-h3.1/image-to-3d` - **Result URL**: `GET https://gptproto.com/api/v3/predictions/{result_id}/result` — the submit response also returns the authoritative URL in `data.urls.get` - **Model ID**: `tripo3d-h3.1` - **Request model value**: not a shared body parameter; use the endpoint and request schema below - **Vendor**: Tripo3d - **Scene**: `image-to-3d` - **Category**: image-to-video - **Modalities**: input image → output video - **Playground**: https://gptproto.com/model/tripo3d/tripo3d-h3.1 Send API requests to the absolute Endpoint URL in this guide. The website address used to read documentation, including localhost, is not an inference base URL. ## Authentication Every request needs a GPTProto API key in the `Authorization` header. Create one at https://gptproto.com/dashboard/api-key, then export it: ```bash export GPTPROTO_API_KEY="your-api-key" ``` Header: `Authorization: Bearer $GPTPROTO_API_KEY` (plus `Content-Type: application/json` on POST). ## Pricing Platform price by tier (USD, already includes the GPTProto discount): - **Per run** — $0.36 per run Price range: $0.36 – $0.36 per generation. Prices may change. The model page always shows the live price: https://gptproto.com/model/tripo3d/tripo3d-h3.1 ## API Information The API is asynchronous: POST the endpoint to create a prediction, then poll its result URL until `status` is `completed` or `failed`. ### Input Schema The endpoint accepts the following JSON body parameters: - **`image`** (`string`, _required_): Reference image for reconstructing the object. A clear background and minimal occlusion are recommended. - Max items: 1 - Accepts: image/png,image/jpeg,image/webp - **`texture`** (`boolean`, _optional_): Create surface textures. Disable both texture and pbr for geometry-only output. - Default: `true` - Options: true, false - **`pbr`** (`boolean`, _optional_): Create base-color、 metallic、 roughness and normal maps. Enabling this also enables textures. - Default: `true` - Options: true, false - **`texture_quality`** (`enum`, _optional_): Texture detail level. extreme provides 8K textures. fast uses standard-sized textures with faster generation. - Default: `standard` - Options: standard, detailed, extreme, fast - **`texture_version`** (`enum`, _optional_): Texture generator version. fast quality uses v3.5-20260815. - Default: `v3.0-20250812` - Options: v3.0-20250812, v3.5-20260815 - **`delight`** (`boolean`, _optional_): Reduce lighting baked into the reference image. Effective only with texture version v3.5-20260815. - Default: `true` - Options: true, false - **`geometry_quality`** (`enum`, _optional_): Mesh detail level. detailed supports up to 2 million faces. - Default: `standard` - Options: standard, detailed - **`quad`** (`boolean`, _optional_): Generate FBX quad topology. If face_limit is omitted、 the target is approximately 10、000 faces. - Default: `false` - Options: true, false - **`smart_low_poly`** (`boolean`, _optional_): Generate lightweight topology、 particularly suitable for simple objects. - Default: `false` - Options: true, false - **`generate_parts`** (`boolean`, _optional_): Produce separately editable components as untextured triangle meshes. Texture、 PBR and quad settings are ignored. - Default: `false` - Options: true, false - **`face_limit`** (`range`, _optional_): Optional face cap. Omit for adaptive selection. Maximum: standard geometry 1、500、000; detailed geometry 2、000、000; quad 150、000. smart_low_poly supports 500-20、000. - Range: 48–2000000 - **`texture_alignment`** (`enum`, _optional_): Prioritize reference-image colors or generated geometry when applying textures. - Default: `original_image` - Options: original_image, geometry - **`enable_image_autofix`** (`boolean`, _optional_): Preprocess low-quality reference images before generation. Increases processing time. - Default: `false` - Options: true, false - **`auto_size`** (`boolean`, _optional_): Estimate real-world dimensions in meters. Requires textured output. - Default: `false` - Options: true, false - **`export_uv`** (`boolean`, _optional_): Include UV unwrapping. Disabling it reduces generation time and file size. - Default: `true` - Options: true, false - **`model_seed`** (`integer`, _optional_): Seed controlling geometry reproducibility. - **`texture_seed`** (`integer`, _optional_): Seed controlling texture variation. Keep model_seed fixed to vary textures on the same mesh. - **`enable_base64_output`** (`boolean`, _optional_): Global API option. Return eligible files as raw Base64 without a data-URI prefix. Files over 64 MiB or unavailable for retrieval remain URLs. Cannot be combined with webhooks. - Default: `false` - Options: true, false - **`enable_sync_mode`** (`boolean`, _optional_): Global API option. Wait within the synchronous response window. If still processing、 retain the prediction ID and poll for results. Cannot be combined with webhooks. - Default: `false` - Options: true, false **Required Parameters Example**: ```json { "image": "" } ``` **Full Example**: ```json { "image": "", "texture": true, "pbr": true, "texture_quality": "standard", "texture_version": "v3.0-20250812", "delight": true, "geometry_quality": "standard", "quad": false, "smart_low_poly": false, "generate_parts": false, "face_limit": null, "texture_alignment": "original_image", "enable_image_autofix": false, "auto_size": false, "export_uv": true, "model_seed": null, "texture_seed": null, "enable_base64_output": false, "enable_sync_mode": false } ``` ### Output Schema Both submit and poll return the same envelope: - **`data.id`** (`string`): Prediction id. Use it as `result_id` when polling for the result. - **`data.status`** (`string`): One of `created`, `running`, `completed`, `failed`. See Status Values below. - **`data.outputs`** (`array of string`): Generated files. Empty until `status` is `completed`; then it holds the output URLs (or base64 strings when the model exposes a base64 option). - **`data.urls.get`** (`string`): Authoritative result URL for this prediction. Prefer it over building the poll URL yourself. - **`data.error`** (`string | null`): Failure reason when `status` is `failed`, otherwise `null`. - **`data.executionTime`** (`integer`): Total processing time in milliseconds. - **`data.timings.inference`** (`integer`): Model inference time in milliseconds. - **`data.hasNsfwContents`** (`array of boolean`): Per-output moderation flags. - **`message`** (`string`): `success` on a normal response, otherwise the error message. - **`code`** (`integer`): Business status code. `200` means the request was accepted. **Example Response — submit (task accepted)**: ```json { "data": { "id": "pred_example_01", "model": "tripo3d-h3.1", "outputs": [], "urls": { "get": "https://gptproto.com/api/v3/predictions/pred_example_01/result" }, "hasNsfwContents": [], "status": "created", "createdAt": "2026-01-01T12:00:00Z", "executionTime": 0, "timings": { "inference": 0 } }, "message": "success", "code": 200 } ``` **Example Response — poll (completed)**: ```json { "data": { "id": "pred_example_01", "model": "tripo3d-h3.1", "outputs": [ "https://oss-us.gptproto.com/example/output.mp4" ], "urls": { "get": "https://gptproto.com/api/v3/predictions/pred_example_01/result" }, "status": "completed", "error": null, "executionTime": 12345, "timings": { "inference": 12000 }, "has_nsfw_contents": [], "created_at": "2026-01-01T12:00:00Z" }, "message": "success", "code": 200 } ``` ### Status Values - `created` — Task accepted. Use `data.id` as `result_id` for polling. - `running` — Generation is in progress. Keep polling. - `completed` — Finished successfully. Generated files are in `data.outputs`. - `failed` — Generation failed. Read `data.error` for the reason. ## Usage Examples ### 1. Submit a request ```bash curl --request POST "https://gptproto.com/api/v3/tripo3d/tripo3d-h3.1/image-to-3d" \ --header "Authorization: Bearer $GPTPROTO_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "image": "", "texture": true, "pbr": true, "texture_quality": "standard", "texture_version": "v3.0-20250812", "delight": true, "geometry_quality": "standard", "quad": false, "smart_low_poly": false, "generate_parts": false, "face_limit": null, "texture_alignment": "original_image", "enable_image_autofix": false, "auto_size": false, "export_uv": true, "model_seed": null, "texture_seed": null, "enable_base64_output": false, "enable_sync_mode": false }' ``` ```python import os import requests url = "https://gptproto.com/api/v3/tripo3d/tripo3d-h3.1/image-to-3d" headers = { "Authorization": f"Bearer {os.environ['GPTPROTO_API_KEY']}", "Content-Type": "application/json" } payload = { "image": "", "texture": True, "pbr": True, "texture_quality": "standard", "texture_version": "v3.0-20250812", "delight": True, "geometry_quality": "standard", "quad": False, "smart_low_poly": False, "generate_parts": False, "face_limit": None, "texture_alignment": "original_image", "enable_image_autofix": False, "auto_size": False, "export_uv": True, "model_seed": None, "texture_seed": None, "enable_base64_output": False, "enable_sync_mode": False } response = requests.request("POST", url, headers=headers, json=payload) print(response.json()) ``` ```typescript const response = await fetch("https://gptproto.com/api/v3/tripo3d/tripo3d-h3.1/image-to-3d", { method: "POST", headers: { "Authorization": `Bearer ${process.env.GPTPROTO_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ image: "", texture: true, pbr: true, texture_quality: "standard", texture_version: "v3.0-20250812", delight: true, geometry_quality: "standard", quad: false, smart_low_poly: false, generate_parts: false, face_limit: null, texture_alignment: "original_image", enable_image_autofix: false, auto_size: false, export_uv: true, model_seed: null, texture_seed: null, enable_base64_output: false, enable_sync_mode: false, }), }); const data = await response.json(); console.log(data); ``` ### 2. Poll until the task finishes Replace `YOUR_RESULT_ID` with `data.id` from the submit response (or call `data.urls.get` directly), and keep polling every 1–3 seconds while `status` is `created` or `running`. ```bash result_id="YOUR_RESULT_ID" curl --request GET "https://gptproto.com/api/v3/predictions/$result_id/result" \ --header "Authorization: Bearer $GPTPROTO_API_KEY" ``` ```python import os import requests result_id = "YOUR_RESULT_ID" url = f"https://gptproto.com/api/v3/predictions/{result_id}/result" headers = { "Authorization": f"Bearer {os.environ['GPTPROTO_API_KEY']}" } response = requests.request("GET", url, headers=headers) print(response.json()) ``` ```typescript const result_id = "YOUR_RESULT_ID"; const response = await fetch(`https://gptproto.com/api/v3/predictions/${result_id}/result`, { method: "GET", headers: { "Authorization": `Bearer ${process.env.GPTPROTO_API_KEY}`, }, }); const data = await response.json(); console.log(data); ``` ## HTTP Status Codes - `400` — malformed body, a parameter or value this model does not accept, or input blocked by the provider's content moderation - `401` — missing or invalid API key - `403` — insufficient credits - `413` — request body too large - `429` — rate limited; retry with backoff - `500` — An internal server error occurred - `502` — An internal server error occurred - `504` — Gateway timeout — upstream service did not respond in time; retry later ## Additional Resources - [Model playground](https://gptproto.com/model/tripo3d/tripo3d-h3.1) - [All models](https://gptproto.com/model) - [API keys](https://gptproto.com/dashboard/api-key) - [Platform overview for LLMs](https://gptproto.com/llms-full.txt) - Any other model: `https://gptproto.com/model/{vendor}/{model}/{scene}/llms.txt`