Imagen a modelo 3D

POST /v3/generation/image-to-model

Generar un modelo 3D a partir de una imagen.

Solicitar parámetros

Encabezados de solicitud

Parámetro	Tipo	Requerido	Predeterminado	Descripción
Content-Type	cadena	si	-	`application/json`
Authorization	cadena	si	-	`Bearer {api_key}`

Parámetro	Tipo	Requerido	Predeterminado	Descripción
input	cadena	si	-	Fuente de la imagen. Acepta un token de archivo que comienza con `file_`, un URL que comienza con `http(s)://` o una tarea ID que comienza con `task_`.
model	cadena	No	`tripo-v3.1`	Versión del modelo AI. Valores admitidos: `tripo-p1`, `tripo-turbo`, `tripo-v3.1`, `tripo-v3.0`, `tripo-v2.5`, `tripo-v2.0`
enable_image_autofix	booleano	No	`false`	Se usa para completado por IA y mejora del resultado 3D. Mejore automáticamente las imágenes de entrada de baja calidad
texture_alignment	cadena	No	`original_image`	Prioridad de alineación de textura. Valores admitidos: `original_image` (priorizar la coincidencia con la imagen original), `geometry` (priorizar la coincidencia con la geometría)
orientation	cadena	No	`default`	Orientación del modelo. Valores admitidos: `default`, `align_image` (alinearse con el punto de vista de la imagen de entrada)
face_limit	entero	No	Adaptativo	Polígono máximo para la salida
texture	booleano	No	`true`	Habilitar mapas de textura
pbr	booleano	No	`true`	Habilite los materiales PBR. Cuando está habilitado, `texture` se fuerza a `true`
texture_seed	entero	No	Aleatorio	Semilla aleatoria para generación de textura.
texture_quality	cadena	No	`standard`	Calidad de la textura. Valores admitidos: `fast` (requiere `texture_version=v3.5-20260815`), `standard`, `detailed`, `extreme`
texture_version	cadena	No	Derivado de model	Fija el modelo de textura con independencia de la geometría. Valores admitidos: `v3.5-20260815`, `v3.0-20250812`, `v2.5-20250123`. Si se omite, se deriva del `model` de geometría (geometría v2.5 → `v2.5-20250123`; en caso contrario, `v3.0-20250812`)
delight	booleano	No	`true`	Elimina la iluminación incrustada de la imagen de referencia antes de texturizar. Solo se aplica cuando `texture_version=v3.5-20260815`
geometry_quality	cadena	No	`standard`	Calidad de la geometría. `standard` (equilibrado), `detailed` (modo Ultra)
auto_size	booleano	No	`false`	Escale automáticamente el modelo a dimensiones reales en metros.
quad	booleano	No	`false`	Genera una malla cuádruple. Cuando está habilitado, el formato de salida se fuerza a FBX
smart_low_poly	booleano	No	`false`	Genere un modelo low-poly con un estilo de topología hecho a mano
generate_parts	booleano	No	`false`	Genera piezas segmentadas editables. No compatible con `texture`, `pbr`, `quad` ni `smart_low_poly` — véase la nota a continuación
compress	cadena	No	-	Tipo de compresión. `geometry` (compresión de tienda)
export_orientation	cadena	No	`+x`	Orientación exportadora. Valores disponibles: `-x`, `-y`, `+y`

Notas sobre generate_parts:

No compatible con texture, pbr, quad ni smart_low_poly:

texture=true o pbr=true — incluida la omisión de texture, que por defecto es true — la solicitud se rechaza con el código de error 1004.
quad=true — quad se ignora; las piezas devueltas son mallas de triángulos.
smart_low_poly=true — smart_low_poly tiene prioridad y las piezas NO se producen.

Para generar piezas, establezca texture=false y pbr=false, y no envíe quad ni smart_low_poly.

Notas sobre export_orientation:

Se aplica solo a esta generación. Si el modelo se va a usar en tareas de postprocesamiento (textura, rig, reorientación, conversión, …), se recomienda no establecer este parámetro.
Si se establece, el postprocesamiento puede afectar el resultado final debido a una orientación incorrecta del modelo, aunque la tarea siga informando status: success — no se genera ningún error. Úselo con precaución.
Si planea postprocesar el modelo, deje este parámetro sin definir y convierta la orientación en el último paso mediante /v3/models/convert.

Los siguientes parámetros solo son válidos cuando model >= tripo-v3.0: texture_quality, geometry_quality, auto_size, quad, smart_low_poly, generate_parts, compress.

Ejemplos de solicitudes

curl -X POST https://openapi.tripo3d.ai/v3/generation/image-to-model \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {api_key}" \
  -d '{
    "input": "https://example.com/image.png",
    "model": "tripo-v3.1",
    "texture": true,
    "pbr": true,
    "texture_quality": "detailed"
  }'

import requests

url = "https://openapi.tripo3d.ai/v3/generation/image-to-model"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer {api_key}"
}
payload = {
    "input": "https://example.com/image.png",
    "model": "tripo-v3.1",
    "texture": True,
    "pbr": True,
    "texture_quality": "detailed"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

const url = "https://openapi.tripo3d.ai/v3/generation/image-to-model";

const response = await fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer {api_key}"
  },
  body: JSON.stringify({
    input: "https://example.com/image.png",
    model: "tripo-v3.1",
    texture: true,
    pbr: true,
    texture_quality: "detailed"
  })
});

const data = await response.json();
console.log(data);

Respuesta

Respuesta exitosa

JSON

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

Campos de respuesta

Parámetro	Tipo	Descripción
code	entero	Código de estado. `0` indica éxito
data.task_id	cadena	Identificador de tarea único utilizado para consultar el progreso y los resultados de la generación.

Códigos de error

Código de estado HTTP	Código de error	Descripción	Recomendación
429	2000	Límite de generación excedido	Reduzca la frecuencia de las solicitudes y vuelva a intentarlo más tarde
400	2002	Parámetro de solicitud no admitido	Verifique los nombres de los parámetros del cuerpo de la solicitud y los rangos de valores
400	2003	El archivo de entrada está vacío	Confirme que el archivo cargado no esté vacío o que se pueda acceder al URL
400	2004	Tipo de archivo no compatible	Utilice un formato de imagen compatible (PNG, JPEG, WebP)
400	2008	La entrada viola la política de contenido.	Reemplace la imagen de entrada y elimine el contenido que infringe las políticas
403	2010	Créditos insuficientes	Añade créditos y vuelve a intentarlo
400	2015	Versión del modelo obsoleta	Actualice `model` a una versión actualmente compatible
400	2018	El modelo es demasiado complejo para volver a mallarlo.	Bajar `face_limit` o simplificar la entrada