Integración de SDK

Usa los SDK oficiales de Tripo para enviar una tarea de texto a modelo, esperar a que termine, verificar el estado final y descargar el modelo generado. Las fuentes de instalación que figuran a continuación están fijadas a las versiones utilizadas para verificar esta página.

SDK compatibles

Lenguaje	API	Versión fijada	Fuente de instalación
JavaScript / TypeScript	V3	`e351348`	Commit oficial de Git
Python	V2 + limited V3	`v0.4.2`	PyPI `tripo3d==0.4.2`
Go	V3	`2c8c8d4`	Pseudoversión de Go `v0.0.0-20260713072120-2c8c8d4e6a9e`
Rust	V3	`f992f6a`	Dependencia Git de Cargo
Java	V3	`7b6a68d`	Compilación desde el código fuente; Maven local `0.1.0-SNAPSHOT`

1. Configurar una clave de API y la región

Crea una clave en la consola de Tripo y exponla únicamente al proceso del servidor. No incluyas una clave de API en el código del navegador ni la añadas al control de versiones.

Bash

export TRIPO_API_KEY="tsk_..."

JavaScript, Go y Rust usan https://openapi.tripo3d.ai/v3 globalmente y https://openapi.tripo3d.ai/v3 en China. Java selecciona TripoRegion.GLOBAL o TripoRegion.CN; el SDK parte del origen .ai o .ai correspondiente y añade /v3. El cliente V2 principal de Python 0.4.2 usa https://api.tripo3d.ai/v2/openapi globalmente y https://api.tripo3d.ai/v2/openapi en China; su flujo limitado de segmentación V3 también usa el origen correspondiente https://openapi.tripo3d.ai o .ai.

2. Instalar el SDK

Instala cada SDK desde su fuente de producción fijada.

npm install github:VAST-AI-Research/tripo-js-sdk#e35134801b339caac0b84f36fe02d08e73e217b2

python -m pip install tripo3d==0.4.2

go get github.com/VAST-AI-Research/tripo-go-sdk@v0.0.0-20260713072120-2c8c8d4e6a9e

[dependencies]
tripo3d-sdk = { git = "https://github.com/VAST-AI-Research/tripo-rust-sdk.git", rev = "f992f6a7cf7a28c10781f9fa28e4630c7802291c" }
tokio = { version = "1", features = ["full"] }
anyhow = "1"

git clone https://github.com/VAST-AI-Research/tripo-java-sdk.git
cd tripo-java-sdk
git checkout 7b6a68d855e01a0b098775b1ee14ce7f3c8ac7d9
./mvnw install

La compilación de Java instala ai.tripo3d:tripo-sdk:0.1.0-SNAPSHOT en el repositorio Maven local. Añade esas coordenadas a tu aplicación cuando termine la compilación desde el código fuente.

3. Enviar, esperar y descargar

Cada ejemplo del servidor lee TRIPO_API_KEY, envía una tarea de texto a modelo, espera un resultado final, comprueba que se haya completado correctamente y guarda de inmediato el modelo principal. Las URL de los modelos generados son temporales.

import { writeFile } from 'node:fs/promises';
import { TripoClient, ModelVersion, TaskStatus } from 'tripo3d-sdk-js';

const apiKey = process.env.TRIPO_API_KEY;
if (!apiKey) throw new Error('TRIPO_API_KEY is required');

const client = new TripoClient({
  apiKey,
  baseUrl: 'https://openapi.tripo3d.ai/v3',
});

const taskId = await client.textToModel({
  prompt: 'a cute red panda holding bamboo',
  model: ModelVersion.H3_1,
  texture: true,
  pbr: true,
  texture_quality: 'detailed',
});

const task = await client.waitForTask(taskId, {
  pollingIntervalMs: 2000,
  onProgress: (value) => console.log(`${value.status} — ${value.progress ?? 0}%`),
});

if (task.status !== TaskStatus.SUCCESS) {
  throw new Error(`Task did not succeed: ${task.status}`);
}

const modelUrl = task.output.model_url ?? task.output.model;
if (!modelUrl) throw new Error('Task returned no model URL');

const response = await fetch(modelUrl);
if (!response.ok) throw new Error(`Download failed: HTTP ${response.status}`);

await writeFile(`tripo-${taskId}.glb`, Buffer.from(await response.arrayBuffer()));

import asyncio
import os
import shutil
from urllib.request import urlopen

from tripo3d import TripoClient
from tripo3d.models import TaskStatus


def download_file(url, path):
    with urlopen(url) as response, open(path, "wb") as output:
        shutil.copyfileobj(response, output)


async def main():
    api_key = os.environ["TRIPO_API_KEY"]
    os.makedirs("./output", exist_ok=True)

    async with TripoClient(api_key=api_key) as client:
        task_id = await client.text_to_model(
            prompt="a cute red panda holding bamboo",
            model_version="v2.5-20250123",
        )
        task = await client.wait_for_task(task_id, verbose=True)

        if task.status != TaskStatus.SUCCESS:
            raise RuntimeError(f"Task did not succeed: {task.status}")

        model_url = task.output.model
        if not model_url:
            raise RuntimeError("Task returned no model URL")

        output_path = "./output/model.glb"
        await asyncio.to_thread(download_file, model_url, output_path)
        print(f"Downloaded model: {output_path}")


asyncio.run(main())

package main

import (
	"context"
	"fmt"
	"log"
	"os"
	"time"

	tripo3d "github.com/VAST-AI-Research/tripo-go-sdk"
)

func main() {
	apiKey := os.Getenv("TRIPO_API_KEY")
	if apiKey == "" {
		log.Fatal("TRIPO_API_KEY is required")
	}

	client, err := tripo3d.NewClient(tripo3d.ClientOptions{
		APIKey:  apiKey,
		BaseURL: "https://openapi.tripo3d.ai/v3",
	})
	if err != nil {
		log.Fatal(err)
	}

	ctx := context.Background()
	taskID, err := client.TextToModel(ctx, tripo3d.TextToModelParams{
		Prompt:         "a cute red panda holding bamboo",
		Model:          tripo3d.String(tripo3d.ModelVersionH31),
		Texture:        tripo3d.Bool(true),
		PBR:            tripo3d.Bool(true),
		TextureQuality: tripo3d.String("detailed"),
	})
	if err != nil {
		log.Fatal(err)
	}

	task, err := client.WaitForTask(ctx, taskID, tripo3d.WaitOptions{
		PollInterval: 2 * time.Second,
	})
	if err != nil {
		log.Fatal(err)
	}
	if task.Status != tripo3d.TaskStatusSuccess {
		log.Fatalf("Task did not succeed: %s", task.Status)
	}

	downloaded, err := client.DownloadModel(ctx, task)
	if err != nil {
		log.Fatal(err)
	}
	if downloaded == nil {
		log.Fatal("Task returned no model URL")
	}

	filename := fmt.Sprintf("tripo-%s.glb", taskID)
	if err := os.WriteFile(filename, downloaded.Data, 0o644); err != nil {
		log.Fatal(err)
	}
}

use tokio::fs;
use tripo3d_sdk::{
    constants::model_version,
    params::TextToModelParams,
    ClientOptions,
    TaskStatus,
    TripoClient,
    WaitOptions,
};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let api_key = std::env::var("TRIPO_API_KEY")?;
    let client = TripoClient::new(ClientOptions {
        api_key: Some(api_key),
        base_url: Some("https://openapi.tripo3d.ai/v3".into()),
        ..Default::default()
    })?;

    let task_id = client
        .text_to_model(TextToModelParams {
            prompt: "a cute red panda holding bamboo".into(),
            model: Some(model_version::H3_1.to_string()),
            texture: Some(true),
            pbr: Some(true),
            texture_quality: Some("detailed".into()),
            ..Default::default()
        })
        .await?;

    let task = client
        .wait_for_task(&task_id, WaitOptions::default())
        .await?;
    if task.status != TaskStatus::Success {
        anyhow::bail!("Task did not succeed: {}", task.status);
    }

    let downloaded = client
        .download_model(&task)
        .await?
        .ok_or_else(|| anyhow::anyhow!("Task returned no model URL"))?;

    fs::write(format!("tripo-{task_id}.glb"), downloaded.data).await?;
    Ok(())
}

import ai.tripo3d.sdk.api.TripoClient;
import ai.tripo3d.sdk.api.TripoClientConfig;
import ai.tripo3d.sdk.api.TripoRegion;
import ai.tripo3d.sdk.model.request.TaskRequestPayload;
import ai.tripo3d.sdk.model.response.TaskDetail;

import java.io.InputStream;
import java.net.URL;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.nio.file.StandardCopyOption;
import java.util.Map;

public final class TripoQuickStart {
    public static void main(String[] args) throws Exception {
        String apiKey = System.getenv("TRIPO_API_KEY");
        if (apiKey == null || apiKey.trim().isEmpty()) {
            throw new IllegalStateException("TRIPO_API_KEY is required");
        }

        try (TripoClient client = TripoClient.create(
                TripoClientConfig.builder(apiKey)
                        .region(TripoRegion.GLOBAL)
                        .build())) {
            TaskDetail created = client.textToModel(TaskRequestPayload.builder()
                    .prompt("a wooden chair")
                    .model("v3.1-20260211")
                    .build());

            TaskDetail done = client.pollUntilTerminal(created.taskId());
            if (!"success".equalsIgnoreCase(done.status())) {
                throw new IllegalStateException(
                        "Task failed: status=" + done.status()
                                + ", message=" + done.errorMsg());
            }

            Map<String, Object> output = done.output();
            Object modelUrl = output == null ? null : output.get("model_url");
            if (!(modelUrl instanceof String)) {
                throw new IllegalStateException(
                        "Task output does not contain model_url");
            }

            try (InputStream input =
                         new URL((String) modelUrl).openStream()) {
                Files.copy(
                        input,
                        Paths.get("model.glb"),
                        StandardCopyOption.REPLACE_EXISTING);
            }
        }
    }
}

JavaScript, Python y Java usan deliberadamente clientes HTTP nativos para la URL firmada del modelo y no adjuntan un encabezado Authorization. Los métodos de descarga de los SDK de Go y Rust también obtienen la URL firmada sin la clave de API.

4. Compatibilidad con las rutas V3

La matriz reúne las cinco implementaciones de SDK en las versiones fijadas anteriormente. Una marca de verificación indica que un flujo público del SDK alcanza la ruta HTTP V3 final, directamente o mediante un paso interno; las constantes de ruta sin usar no cuentan.

Ruta HTTP	Finalidad	JavaScript	Python	Go	Rust	Java
`POST /v3/generation/text-to-model`	Generar un modelo a partir de texto	✓	—	✓	✓	✓
`POST /v3/generation/image-to-model`	Generar un modelo a partir de una imagen	✓	—	✓	✓	✓
`POST /v3/generation/multiview-to-model`	Generar un modelo a partir de varias vistas	✓	—	✓	✓	✓
`POST /v3/generation/text-to-image`	Generar una imagen a partir de texto	✓	—	✓	✓	—
`POST /v3/generation/image-to-image`	Transformar una imagen	✓	—	✓	✓	—
`POST /v3/generation/image-to-multiview`	Generar imágenes multivista	✓	—	✓	✓	✓
`POST /v3/generation/edit-multiview`	Editar la salida multivista	✓	—	✓	✓	—
`POST /v3/generation/image-to-splat`	Generar un splat gaussiano	—	—	—	—	✓
`POST /v3/models/refine`	Refinar un modelo preliminar	—	—	—	—	✓
`POST /v3/models/texture`	Aplicar o regenerar texturas	✓	—	✓	✓	✓
`POST /v3/models/stylize`	Estilizar un modelo	—	—	—	—	✓
`POST /v3/models/convert`	Convertir el formato del modelo	✓	—	✓	✓	✓
`POST /v3/models/import`	Importar un modelo externo	—	—	—	—	✓
`POST /v3/mesh/segment`	Segmentar una malla	✓	✓	✓	✓	✓
`POST /v3/mesh/complete`	Completar o reparar una malla	✓	—	✓	✓	✓
`POST /v3/mesh/decimate`	Reducir el número de caras	✓	—	✓	✓	✓
`POST /v3/animations/rig-check`	Comprobar si se puede aplicar rigging a un modelo	✓	—	✓	✓	✓
`POST /v3/animations/rig`	Añadir un esqueleto	✓	—	✓	✓	✓
`POST /v3/animations/retarget`	Aplicar una animación predefinida	✓	—	✓	✓	✓
`GET /v3/tasks/{task_id}`	Obtener una tarea	✓	✓	✓	✓	✓
`POST /v3/tasks/list`	Obtener varias tareas	✓	—	✓	✓	✓
`POST /v3/files`	Subir un archivo	✓	✓	✓	✓	✓
`POST /v3/files/presign`	Crear una carga prefirmada	—	—	—	—	✓
`GET /v3/account/balance`	Obtener el saldo de la cuenta	✓	—	✓	✓	✓
`GET /v3/account/usage`	Obtener el historial de uso	—	—	—	—	✓

En esta versión fijada, solo Java expone image-to-splat, refine, stylize, import, presign y usage. Java no expone text-to-image, image-to-image ni edit-multiview. Su descriptor interno para /v3/files/upload-credentials no tiene servicio ni método público del cliente, por lo que no se cuenta como compatible.

Python sigue siendo principalmente un SDK V2. Su rama mesh_segmentation(..., model_version="v2.0-20260430") también usa POST /v3/mesh/segment, GET /v3/tasks/{task_id} y POST /v3/files cuando debe cargar un ref_image local.

Compatibilidad con las rutas V2 de Python

Python 0.4.2 expone cinco rutas HTTP V2 finales. POST /v2/openapi/task es compartida por sus métodos de generación, procesamiento de modelos, mallas y animación; no se limita a texto a modelo.

Ruta HTTP	Finalidad
`POST /v2/openapi/task`	Enviar cualquier tarea V2 compatible
`GET /v2/openapi/task/{task_id}`	Consultar el estado y la salida de la tarea
`GET /v2/openapi/user/balance`	Obtener el saldo de la cuenta
`POST /v2/openapi/upload/sts/token`	Obtener credenciales de carga STS cuando `boto3` está disponible
`POST /v2/openapi/upload`	Cargar un archivo mediante el modo multipart heredado del SDK

Java y los demás SDK V3 envían la selección del modelo mediante sus modelos de parámetros V3 oficiales. En el formato de Java, el campo se llama model.

5. Solución de problemas

Falta la clave: configura TRIPO_API_KEY en el proceso del servidor. Consulta Autenticación.
Región incorrecta: selecciona el endpoint global o de China correspondiente al SDK y a la versión de la API que utilices.
Tarea fallida o con tiempo de espera agotado: conserva el task_id, revisa el estado final y consulta Ciclo de vida de las tareas y Gestión de errores.
URL del modelo caducada: vuelve a consultar la tarea cuando el SDK lo admita y descarga el modelo inmediatamente. No guardes una URL firmada temporal como recurso permanente.

Integración de SDK

Integración de SDK

SDK compatibles

1. Configurar una clave de API y la región

2. Instalar el SDK

3. Enviar, esperar y descargar

4. Compatibilidad con las rutas V3

Compatibilidad con las rutas V2 de Python

5. Solución de problemas

Repositorios oficiales