Ir al contenido principal

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

Tripo H3.1 Image to 3D convierte una imagen en un GLB con texturas PBR por defecto, con interruptores para textura HD, geometría detallada, topología de quads, número de caras, escala real, orientación y seeds separados para geometría y textura.

Desde $0.432/solicitud

Playground

Enviar una solicitud

Inicio rápido

Los ejemplos usan las definiciones públicas de parámetros del endpoint seleccionado. Sustituye la clave de API y los medios de ejemplo, y envía la solicitud desde tu servidor.

SDK e integraciones
POSThttps://api.spicyapi.ai/api/v1/jobs/createTask

Autenticación de API

Guarda la clave de API en la variable de entorno del servidor SPICY_API_KEY. Usa autenticación Bearer y Content-Type: application/json en las solicitudes JSON.

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"

Generado a partir del esquema de entrada de este modelo: el mismo con el que la API valida cada solicitud.

Parámetros de entrada

Incluye estos campos en el objeto input del cuerpo de la solicitud. Los nombres y tipos coinciden con la API. No supongas un valor predeterminado si no está indicado.

image_urlstringObligatorio

La imagen que se va a modelar: JPEG, PNG o WebP de hasta 10 MB. Un solo sujeto, completo en el encuadre, sobre fondo liso; una vista de tres cuartos le da al modelo la mayor información de profundidad.

Valor predeterminado
Sin especificar
Restricciones
minLength:1
contentMediaType:["image/jpeg","image/png","image/webp","image/gif"]
texture_seedintegerOpcional

Seed opcional de la etapa de textura. Mantén seed fijo y cambia este para probar texturas nuevas sobre la misma forma.

Valor predeterminado
Sin especificar
Restricciones
minimum:0
maximum:2147483647
seedintegerOpcional

Seed opcional de la etapa de geometría. Mantenlo fijo para reproducir la misma forma.

Valor predeterminado
Sin especificar
Restricciones
minimum:0
maximum:2147483647
uv_unwrapbooleanOpcional

Activado por defecto. Desactivado omite el desenvolvido UV para obtener un archivo más rápido y pequeño, pero la malla entonces no tiene coordenadas de textura para texturizar después. No cambia el precio.

Valor predeterminado
true
auto_sizebooleanOpcional

Desactivado por defecto. Activado escala la malla a dimensiones reales estimadas, útil para RA e impresión. No cambia el precio.

Valor predeterminado
false
texture_alignmentstringOpcional

original_image (predeterminado) alinea la textura con la imagen; geometry la alinea con la forma generada. No cambia el precio.

Valor predeterminado
"original_image"
Valores permitidos
"original_image""geometry"
model_orientationstringOpcional

default mantiene la orientación estándar del modelo; align_image gira el resultado para que coincida con la vista de la imagen. No cambia el precio.

Valor predeterminado
"default"
Valores permitidos
"default""align_image"
image_autofixbooleanOpcional

Desactivado por defecto. Activado repara una imagen borrosa, con ruido o de baja resolución antes de modelar, lo que tarda más. No cambia el precio.

Valor predeterminado
false
face_limitintegerOpcional

Número de caras objetivo opcional, de 1.000 a 2.000.000. Si lo dejas vacío decide el modelo, a veces por encima del millón de caras; entre 50.000 y 200.000 va bien para la mayoría de los visores web. No cambia el precio.

Valor predeterminado
Sin especificar
Restricciones
minimum:1000
maximum:2000000
generate_partsbooleanOpcionalAfecta al precio

Desactivado por defecto. Activado devuelve el modelo como partes separadas con nombre en un solo GLB (18 partes para nuestro astronauta de juguete). Las partes no llevan texturas y siempre son triángulos, así que las opciones de textura y quad_mesh se ignoran y no se cobran; el total sigue siendo más alto que el predeterminado con textura.

Valor predeterminado
false
low_polybooleanOpcionalAfecta al precio

Desactivado por defecto. Activado construye una malla ligera con topología limpia, de estilo modelado a mano, ideal para accesorios sencillos; mantén face_limit en 20.000 o menos. En nuestra prueba, face_limit de 5.000 en la bota devolvió 7.675 triángulos. Suma al precio.

Valor predeterminado
false
quad_meshbooleanOpcionalAfecta al precio

Desactivado por defecto. Activado devuelve polígonos de cuatro lados en vez de triángulos, más fáciles de editar en programas de modelado, y el archivo llega como FBX (texturas incrustadas) en lugar de GLB. Suma un recargo pequeño. Se ignora, y no se cobra, cuando generate_parts está activado: las partes siguen siendo triángulos en un GLB.

Valor predeterminado
false
geometry_qualitystringOpcionalAfecta al precio

standard (predeterminado) o detailed. detailed construye un relieve más fino y es el recargo más caro.

Valor predeterminado
"standard"
Valores permitidos
"standard""detailed"
remove_lightingbooleanOpcional

Activado por defecto. Quita los brillos y sombras horneados en la imagen antes de texturizar, para que el modelo reaccione a las luces de tu propia escena. Solo surte efecto con el modelo de textura v3.5. No cambia el precio.

Valor predeterminado
true
texture_versionstringOpcional

v3.0-20250812 (predeterminado) o la más reciente v3.5-20260815. texture_quality fast y remove_lighting dependen de v3.5. No cambia el precio.

Valor predeterminado
"v3.0-20250812"
Valores permitidos
"v3.0-20250812""v3.5-20260815"
texture_qualitystringOpcionalAfecta al precio

standard (predeterminado), detailed, extreme o fast. detailed da texturas de mayor resolución y extreme texturas de 8K; cada una suma al precio. fast mantiene el tamaño estándar, usa el modelo de textura v3.5 y cuesta lo mismo que standard. Ninguna de ellas se aplica a una malla sin textura ni a generate_parts.

Valor predeterminado
"standard"
Valores permitidos
"standard""detailed""extreme""fast"
generate_pbrbooleanOpcionalAfecta al precio

Activado por defecto. Añade mapas de material PBR (metal-rugosidad y normal) al color base y activa el texturizado aunque generate_texture esté desactivado. Desactivado junto con generate_texture da una malla sola más barata.

Valor predeterminado
true
generate_texturebooleanOpcionalAfecta al precio

Activado por defecto. Pinta una textura sobre la malla. Desactivarlo solo quita el recargo de textura si generate_pbr también está desactivado, porque los materiales PBR vuelven a activar el texturizado.

Valor predeterminado
true

Seguir la tarea

HTTP 202 significa que la tarea se aceptó, no que haya terminado. Guarda el taskId devuelto y consulta esa tarea. No crees otra mientras esperas el resultado.

Solicitud aceptada
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"
  }
}

La respuesta de aceptación incluye la estimación para que tu aplicación pueda mostrar el mismo importe en el historial de tareas y en la facturación.

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

Empieza consultando cada 2 segundos aproximadamente y ve espaciando los intentos. Párate en un estado final. Si se cae la conexión, consulta el taskId original. Vuelve a crear la tarea solo con la clave de idempotencia y el cuerpo originales.

O recibe el resultado por callback
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);
});

Pasa callBackUrl al crear la tarea y recibirás el registro terminado por POST, sin un bucle de consultas de estado. Cada entrega lleva X-Webhook-Timestamp, X-Webhook-Signature y X-Webhook-Payload-Version. La firma es un HMAC-SHA256 en base64 sobre taskId.timestamp.sha256(body), así que debes verificarla con los bytes originales: si analizas el JSON y vuelves a serializarlo, los bytes cambian y la verificación falla. Las entregas fallidas se reintentan, de modo que el mismo taskId puede llegar dos veces; haz que tu manejador sea idempotente. Responde 2xx primero y haz el trabajo después: un manejador lento se trata como una entrega fallida.

Leer el resultado

Procesa output solo cuando state sea succeeded. Si falla, consulta errorCode, errorMessage y request_id. Los costos y estados de ejemplo no representan una factura real.

Ejemplo de respuesta completada
{
  "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"
  }
}

Para cada archivo disponible, abre o descarga assets[].url directamente, sin la cabecera Authorization de la API. El enlace firmado expira en expiresAt: vuelve a consultar la tarea para renovarlo mientras el archivo siga dentro del periodo de conservación. Un archivo pendiente o no disponible no trae URL. Trata los enlaces firmados como datos privados.

SDK e integraciones

Usa SpicyAPI en tu app, terminal, asistente de IA o flujo visual. Elige una guía de configuración.

Úsalo en ComfyUI

Instala los nodos de SpicyAPI desde ComfyUI Manager o con el comando de abajo y busca Tripo H3.1 · Image to 3D en el lienzo. El nodo tiene las mismas opciones que esta página y muestra su precio antes de ejecutarse.

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