Integrazione degli SDK

Usa gli SDK Tripo ufficiali per inviare un’attività di generazione di un modello da testo, attenderne il completamento, verificarne lo stato finale e scaricare il modello generato. Le origini di installazione riportate di seguito sono bloccate alle versioni usate per verificare questa pagina.

SDK supportati

Linguaggio	API	Versione bloccata	Origine di installazione
JavaScript / TypeScript	V3	`e351348`	Commit Git ufficiale
Python	V2 + limited V3	`v0.4.2`	PyPI `tripo3d==0.4.2`
Go	V3	`2c8c8d4`	Pseudo-versione Go `v0.0.0-20260713072120-2c8c8d4e6a9e`
Rust	V3	`f992f6a`	Dipendenza Git di Cargo
Java	V3	`7b6a68d`	Compilazione dai sorgenti; Maven locale `0.1.0-SNAPSHOT`

1. Configurare una chiave API e la regione

Crea una chiave nella console Tripo ed esponila soltanto al processo lato server. Non inserire una chiave API nel codice del browser e non salvarla nel controllo di versione.

Bash

export TRIPO_API_KEY="tsk_..."

JavaScript, Go e Rust usano https://openapi.tripo3d.ai/v3 a livello globale e https://openapi.tripo3d.com/v3 in Cina. Java seleziona TripoRegion.GLOBAL o TripoRegion.CN; l’SDK parte dall’origine .ai o .com corrispondente e aggiunge /v3. Il client V2 principale di Python 0.4.2 usa https://api.tripo3d.ai/v2/openapi a livello globale e https://api.tripo3d.com/v2/openapi in Cina; il flusso limitato di segmentazione V3 usa anche l’origine corrispondente https://openapi.tripo3d.ai o .com.

2. Installare l’SDK

Installa ogni SDK dalla relativa origine di produzione bloccata.

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 compilazione Java installa ai.tripo3d:tripo-sdk:0.1.0-SNAPSHOT nel repository Maven locale. Aggiungi queste coordinate all’applicazione al termine della compilazione dai sorgenti.

3. Inviare, attendere e scaricare

Ogni esempio lato server legge TRIPO_API_KEY, invia un’attività di generazione di un modello da testo, attende un risultato finale, verifica che abbia avuto successo e salva subito il modello principale. Gli URL dei modelli generati sono temporanei.

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 e Java usano deliberatamente client HTTP nativi per l’URL firmato del modello e non aggiungono un header Authorization. Anche i metodi di download degli SDK Go e Rust recuperano l’URL firmato senza la chiave API.

4. Supporto delle route V3

La matrice riunisce tutte e cinque le implementazioni SDK nelle versioni bloccate indicate sopra. Un segno di spunta indica che un flusso pubblico dell’SDK raggiunge la route HTTP V3 finale, direttamente o tramite un passaggio interno; le costanti di route inutilizzate non vengono conteggiate.

Route HTTP	Scopo	JavaScript	Python	Go	Rust	Java
`POST /v3/generation/text-to-model`	Generare un modello dal testo	✓	—	✓	✓	✓
`POST /v3/generation/image-to-model`	Generare un modello da una singola immagine	✓	—	✓	✓	✓
`POST /v3/generation/multiview-to-model`	Generare un modello da più viste	✓	—	✓	✓	✓
`POST /v3/generation/text-to-image`	Generare un’immagine dal testo	✓	—	✓	✓	—
`POST /v3/generation/image-to-image`	Trasformare un’immagine	✓	—	✓	✓	—
`POST /v3/generation/image-to-multiview`	Generare immagini multivista	✓	—	✓	✓	✓
`POST /v3/generation/edit-multiview`	Modificare l’output multivista	✓	—	✓	✓	—
`POST /v3/generation/image-to-splat`	Generare uno splat gaussiano	—	—	—	—	✓
`POST /v3/models/refine`	Rifinire un modello preliminare	—	—	—	—	✓
`POST /v3/models/texture`	Applicare o rigenerare le texture	✓	—	✓	✓	✓
`POST /v3/models/stylize`	Stilizzare un modello	—	—	—	—	✓
`POST /v3/models/convert`	Convertire il formato del modello	✓	—	✓	✓	✓
`POST /v3/models/import`	Importare un modello esterno	—	—	—	—	✓
`POST /v3/mesh/segment`	Segmentare una mesh	✓	✓	✓	✓	✓
`POST /v3/mesh/complete`	Completare o riparare una mesh	✓	—	✓	✓	✓
`POST /v3/mesh/decimate`	Ridurre il numero di facce	✓	—	✓	✓	✓
`POST /v3/animations/rig-check`	Verificare se un modello può essere sottoposto a rigging	✓	—	✓	✓	✓
`POST /v3/animations/rig`	Aggiungere uno scheletro	✓	—	✓	✓	✓
`POST /v3/animations/retarget`	Applicare un’animazione predefinita	✓	—	✓	✓	✓
`GET /v3/tasks/{task_id}`	Recuperare un’attività	✓	✓	✓	✓	✓
`POST /v3/tasks/list`	Recuperare più attività	✓	—	✓	✓	✓
`POST /v3/files`	Caricare un file	✓	✓	✓	✓	✓
`POST /v3/files/presign`	Creare un caricamento prefirmato	—	—	—	—	✓
`GET /v3/account/balance`	Ottenere il saldo dell’account	✓	—	✓	✓	✓
`GET /v3/account/usage`	Ottenere la cronologia di utilizzo	—	—	—	—	✓

In questa versione bloccata, soltanto Java espone image-to-splat, refine, stylize, import, presign e usage. Java non espone text-to-image, image-to-image o edit-multiview. Il descrittore interno per /v3/files/upload-credentials non dispone di un servizio né di un metodo client pubblico, quindi non viene conteggiato come supportato.

Python rimane principalmente un SDK V2. Il ramo mesh_segmentation(..., model_version="v2.0-20260430") usa inoltre POST /v3/mesh/segment, GET /v3/tasks/{task_id} e POST /v3/files quando deve caricare un ref_image locale.

Supporto delle route Python V2

Python 0.4.2 espone cinque route HTTP V2 finali. POST /v2/openapi/task è condivisa dai metodi di generazione, elaborazione del modello, mesh e animazione; non è limitata alla generazione da testo.

Route HTTP	Scopo
`POST /v2/openapi/task`	Inviare qualsiasi attività V2 supportata
`GET /v2/openapi/task/{task_id}`	Interrogare lo stato e l’output dell’attività
`GET /v2/openapi/user/balance`	Ottenere il saldo dell’account
`POST /v2/openapi/upload/sts/token`	Ottenere credenziali di caricamento STS quando `boto3` è disponibile
`POST /v2/openapi/upload`	Caricare un file tramite il fallback multipart legacy dell’SDK

Java e gli altri SDK V3 inviano la selezione del modello tramite i rispettivi modelli di parametri V3 ufficiali. Nel formato wire di Java, il campo si chiama model.

5. Risoluzione dei problemi

Chiave mancante: imposta TRIPO_API_KEY nel processo server. Consulta Autenticazione.
Regione errata: seleziona l’endpoint globale o cinese corrispondente all’SDK e alla versione API in uso.
Attività non riuscita o scaduta: conserva il task_id, controlla lo stato finale e consulta Ciclo di vita delle attività e Gestione degli errori.
URL del modello scaduto: interroga nuovamente l’attività quando l’SDK lo supporta, quindi scarica subito il modello. Non archiviare un URL firmato temporaneo come risorsa permanente.

Integrazione degli SDK

Integrazione degli SDK

SDK supportati

1. Configurare una chiave API e la regione

2. Installare l’SDK

3. Inviare, attendere e scaricare

4. Supporto delle route V3

Supporto delle route Python V2

5. Risoluzione dei problemi

Repository ufficiali