Text to 3D Model — H Series

http

Base URL: https://openapi.tripo3d.ai/v3

Endpoint: POST /generation/text-to-model

Generate a 3D model from a text prompt. Produces geometry, optional textures, and optional PBR material maps.

Note

This endpoint requires an API Key. Include it in the Authorization header as Bearer {api_key}.
This is an asynchronous API. After submitting the request, use the Task Query API to poll for results, or configure a Webhook to receive automatic notifications when the task completes.

Request Parameters

Request Body

promptstringRequired

Text prompt, up to 1024 characters. Describe shape, material, style, and scale.

Notes

Good: "A low-poly medieval wooden treasure chest with iron hinges and a rusty lock."
Bad: "A box."
Include material and style hints for better PBR results.

modelstringRequired

AI model version.

v3.1-20260211 — latest, best quality.
v3.0-20250812 — stable, advanced features.
v2.5-20250123 — balanced.

negative_promptstring

Negative prompt, up to 255 characters. Describe what you do NOT want in the generated model. For example: "blurry, low quality, broken mesh".

model_seedinteger

Random seed for geometry generation. Using the same seed with the same input will produce an identical 3D mesh. If not set, a random seed is used each time.

image_seedinteger

Random seed for the internal text-to-image stage. Controls the reference image generated from your text prompt before 3D conversion. If not set, a random seed is used each time.

face_limitinteger

Maximum polycount for the output mesh.

Notes

If omitted, the model uses adaptive topology.

Upper limits by mode

Mode	Standard	Ultra
Triangle — v3.1	1,500,000	2,000,000
Triangle — v3.0	1,000,000	2,000,000
Triangle — v2.5	500,000	/
Quad (`quad: true`)	150,000

Game-ready assets: 50,000 – 100,000. Web/mobile: 10,000 – 50,000.
When smart_low_poly: true, face limits are fixed regardless of model version: Triangle 500 – 20,000, Quad 500 – 10,000.

texturebooleandefault: true

Whether to generate texture maps for the model. Set to false to get a bare geometry without any textures. Default is true.

pbrbooleandefault: true

Enable PBR material maps (base_color, metallic, roughness, normal).

When pbr is set to true, texture will be automatically forced to true.

texture_seedinteger

Random seed for texture generation. Using the same seed will produce identical textures. If not set, a random seed will be used each time. To get a model with different textures but the same geometry, keep model_seed unchanged and vary texture_seed.

texture_qualitystringdefault: standard

Texture quality level.

standard — balanced quality and speed.
detailed — higher fidelity, slower generation.
extreme — 8K textures, highest fidelity. Costs additional credits compared to detailed.

geometry_qualitystringdefault: standard

Geometry quality level.

standard — balanced quality and speed.
detailed — Ultra mode, finer geometry detail.

Only effective for model version ≥ v3.0. Do NOT use this parameter with v2.5.

auto_sizebooleandefault: false

Whether to automatically scale the generated model to real-world dimensions. When enabled, the model size will be in meters, suitable for AR/VR or game engine scenes. Default is false.

quadbooleandefault: false

Whether to output a quad mesh (four-sided polygons) instead of triangles. If face_limit is not set, the default face count will be 10,000.

Enabling quad will force the output format to FBX.

smart_low_polybooleandefault: false

Whether to generate a low-poly model with hand-crafted, clean topology style. Best suited for simple, non-complex inputs. Complex models may occasionally fail. Default is false.

generate_partsbooleandefault: false

Generate editable segmented parts.

Not compatible with texture=true, pbr=true, or quad=true. To use this, set all three to false.

compressstring

Compression type.

geometry — meshopt compression for reduced file size.

Notes

The following parameters are only valid when model ≥ v3.0-20250812: texture_quality, geometry_quality, auto_size, quad, smart_low_poly, generate_parts, compress.

export_uvbooleandefault: true

Controls UV unwrapping during generation. Set false for faster generation and smaller file size. UV unwrapping will be handled during texturing.

Examples

Basic

{
  "prompt": "A cat wearing a spacesuit",
  "model": "v3.1-20260211",
  "texture": true,
  "pbr": true,
  "texture_quality": "detailed"}

Advanced

{
  "prompt": "A futuristic sci-fi helmet with glowing blue visor.",
  "model": "v3.1-20260211",
  "face_limit": 80000,
  "geometry_quality": "detailed",
  "auto_size": true
}

Create task

{
  "code": 0,
  "data": {
    "task_id": "task_abc123"}
}

Task result

{
  "code": 0,
  "data": {
    "task_id": "task_abc123",
    "type": "text_to_model",
    "status": "success",
    "progress": 100,
    "output": {
      "model_url": "https://cdn.tripo3d.ai/output/model_pbr.glb",
      "rendered_image_url": "https://cdn.tripo3d.ai/output/preview.png"},
    "credits_consumed": 100,
    "created_at": "2026-04-28T12:00:00Z",
    "completed_at": "2026-04-28T12:01:30Z"}
}

Text to 3D Model — H Series

curl --request POST \
  --url https://openapi.tripo3d.ai/v3/generation/text-to-model \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "prompt": "A cat wearing a spacesuit",
  "model": "v3.1-20260211",
  "texture": true,
  "pbr": true,
  "texture_quality": "detailed"}'

200Response

{
  "code": 0,
  "data": {
    "task_id": "task_abc123"}
}